diff --git a/README.md b/README.md
index 7e6c6b806c..f6aab62173 100644
--- a/README.md
+++ b/README.md
@@ -775,6 +775,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md
index a42d7c29ed..15b66446e5 100644
--- a/docs/USER_GUIDE.md
+++ b/docs/USER_GUIDE.md
@@ -339,6 +339,17 @@ omniroute --port 3000
The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### VPS Deployment
```bash
diff --git a/docs/i18n/ar/README.md b/docs/i18n/ar/README.md
index fe49c80a62..0fcede2e78 100644
--- a/docs/i18n/ar/README.md
+++ b/docs/i18n/ar/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/ar/docs/USER_GUIDE.md b/docs/i18n/ar/docs/USER_GUIDE.md
index 6a398eaf56..f6d7bf4f87 100644
--- a/docs/i18n/ar/docs/USER_GUIDE.md
+++ b/docs/i18n/ar/docs/USER_GUIDE.md
@@ -4,83 +4,104 @@
---
-الدليل الكامل لتكوين مقدمي الخدمات، وتشمل المجموعات، ودمج أدوات CLI، ونشر OmniRoute.---## Table of Contents
-- [نظرة سريعة على التسعير](#- التسعير في لمحة سريعة)
-- [حالات الاستخدام](#-حالات الاستخدام)
-- [إعداد الموفر](#-إعداد الموفر)
-- [تكامل CLI](#-cli-integration)
-- [النشر](#-النشر)
-- [النماذج التجريبية](#-النماذج التجريبية)
-- [الميزات المتقدمة](#-الميزات المتقدمة)---## 💰 Pricing at a Glance
-| ايرلندية | مقدم | التكلفة | إعادة ضبط الحصص | الكل لـ |
-| ---------------------------------- | ---------------------------- | ---------------------- | ----------------------- | ------------------------------------- |
-| **💳الإشتراك** | كلود كود (برو) | 20 شهريًا | 5 ساعات + أسبوعي | ❤ت بالفعل |
-| | الدستور الغذائي (زائد / برو) | 20-200 دولار شهريًا | 5 ساعات + أسبوعي | مستخدم OpenAI |
-| | الجوزاء CLI | **مجاني** | 180 ألف/شهر + 1 ألف/يوم | الجميع! |
-| | جيثب مساعد الطيار | 10-19 شهريًا | شهري | مستخدمين جيثب |
-| **🔑 مفتاح واجهة برمجة التطبيقات** | ديب سيك | الدفع لكل استخدام | لا شيء | الاستدلال الرخيص |
-| | جروك | الدفع لكل استخدام | لا شيء | الاستدلال فائق السرعة |
-| | xAI (جروك) | الدفع لكل استخدام | لا شيء | جروك 4 منطق |
-| | ميسترال | الدفع لكل استخدام | لا شيء | التطورات التي يكملها الاتحاد الأوروبي |
-| | الحيرة | الدفع لكل استخدام | لا شيء | البحث المعزز |
-| | منظمة العفو الدولية | الدفع لكل استخدام | لا شيء | نماذج مفتوحة المصدر |
-| | منظمة العفو الدولية للعبة | الدفع لكل استخدام | لا شيء | صور سريعة موتورز |
-| | الشيخ | الدفع لكل استخدام | لا شيء | السرعة على نطاق الراقة |
-| | كوهير | الدفع لكل استخدام | لا شيء | الأمر R+ RAG |
-| | نفيديا نيم | الدفع لكل استخدام | لا شيء | الأشياء |
-| **💰 رخيص** | جي إل إم-4.7 | 0.6 دولار/1 مليون | يوميا 10 صباحا | نسخة للميزانية |
-| | ميني ماكس M2.1 | 0.2 دولار/1 مليون | التداول لمدة 5 ساعات | الخيار الأرخص |
-| | كيمي ك2 | 9 دولارات شهريًا مسطحة | 10 مليون رمز/شهر | حساب التكلفة |
-| **🆓مجانًا** | قدير | $0 | غير محدود | 8 نماذج مجانية |
-| | كوين | $0 | غير محدود | 3 نماذج مجانية |
-| | كيرو | $0 | غير محدود | كلود مجاني |
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
-**💡 نصيحه العامه:**ابدأ مع Gemini CLI (180 ألف دولار شهريًا) + مجموعة Qoder (مجانية غير محدودة) = تكلفة 0 دولار!---## 🎯 Use Cases
+---
+
+## Table of Contents
+
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
+
+## 💰 Pricing at a Glance
+
+| Tier | Provider | Cost | Quota Reset | Best For |
+| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |
+| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |
+| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |
+| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
+
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
+
+## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**المشكلة:**تنتهي صلاحية الحصة غير المستخدمة، وتحد من المعدل أثناء عملية الترميز```
-التحرير والسرد: "تعظيم كلود"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/clude-opus-4-6 (استخدم الاشتراك بالكامل)
-2. glm/glm-4.7 (نسخة احتياطية رخيصة عند انتهاء الحصة)
-3. if/kimi-k2-thinking (الاحتياطي المجاني في حالات الطوارئ)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
-التكلفة الشهرية: 20 دولارًا (اشتراك) + ~ 5 دولارات (احتياطي) = إجمالي 25 دولارًا
-مقابل 20 دولارًا + حدود الوصول = الإحباط```
+Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
+vs. $20 + hitting limits = frustration
+```
### Case 2: "I want zero cost"
-**المشكلة:**لا أستطيع تحمل تكلفة الاشتراكات، وتحتاج إلى ترميز يعتمد على الذكاء الاصطناعي```
-Combo: "free-forever"
+**Problem:** Can't afford subscriptions, need reliable AI coding
-1. gc/gemini-3-flash (180K free/month)
-2. if/kimi-k2-thinking (unlimited free)
-3. qw/qwen3-coder-plus (unlimited free)
+```
+Combo: "free-forever"
+ 1. gc/gemini-3-flash (180K free/month)
+ 2. if/kimi-k2-thinking (unlimited free)
+ 3. qw/qwen3-coder-plus (unlimited free)
Monthly cost: $0
Quality: Production-ready models
-
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**المشكلة:**المواعيد النهائية، اضطرت إلى التوقف عن العمل```
-التحرير والسرد: "دائما على"
- 1.cc/كلود-opus-4-6 (أفضل جودة)
- 2.cx/gpt-5.2-codex (الاشتراك الثاني)
- 3. glm/glm-4.7 (رخيص، يُعاد ضبطه يوميًا)
- 4. minimax/MiniMax-M2.1 (الأرخص، إعادة ضبط لمدة 5 ساعات)
- 5. if/kimi-k2-thinking (مجاني غير محدود)
+**Problem:** Deadlines, can't afford downtime
-النتيجة: 5 طبقات احتياطية = صفر توقف
-التكلفة الشهرية: 20-200 دولار (اشتراكات) + 10-20 دولار (احتياطي)```
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
+
+Result: 5 layers of fallback = zero downtime
+Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
+```
### Case 4: "I want FREE AI in OpenClaw"
-**المشكلة:**تحتاج إلى مساعد الذكاء الاصطناعي في تطبيقات المراسلة، مجانًا تمامًا```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -88,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -109,16 +130,19 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**نصيحة الرأس:**استخدم Opus للمهام المعقدة، وSonnet للسرعة. OmniRoute يتتبع الحصة لكل نموذج!#### OpenAI Codex (Plus/Pro)```bash
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
+
+```bash
Dashboard → Providers → Connect Codex
→ OAuth login (port 1455)
→ 5-hour + weekly reset
Models:
-cx/gpt-5.2-codex
-cx/gpt-5.1-codex-max
-
-````
+ cx/gpt-5.2-codex
+ cx/gpt-5.1-codex-max
+```
#### Gemini CLI (FREE 180K/month!)
@@ -130,45 +154,56 @@ Dashboard → Providers → Connect Gemini CLI
Models:
gc/gemini-3-flash-preview
gc/gemini-2.5-pro
-````
+```
-**أفضل قيمة:**طبقة مجانية كبيرة! استخدم هذا من قبل حتى لا يتطلب الأمر.#### GitHub Copilot```bash
+**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.1-pro-preview
-
-````
+ gh/gpt-5
+ gh/claude-4.5-sonnet
+ gh/gemini-3.1-pro-preview
+```
### 💰 Cheap Providers
#### GLM-4.7 (Daily reset, $0.6/1M)
-1. قم بالتسجيل: [Zhipu AI](https://open.bigmodel.cn/)
-2. احصل على مفتاح API من خطة الترميز
-3. لوحة المعلومات → إضافة واجهة برمجة التطبيقات الرئيسية: الموفر: `glm`، واجهة برمجة التطبيقات الرئيسية: `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` —**نصيحة الرئيسة:**توفر خطة للأهداف 3× لتغطية 1/7! إعادة ضبط الساعة اليومية 10:00 صباحًا.#### MiniMax M2.1 (5hset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. قم بالتسجيل: [MiniMax](https://www.minimax.io/)
-2. الحصول على مفتاح API → لوحة المعلومات → إضافة مفتاح API
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**الاستخدام:**`minimax/MiniMax-M2.1` —**نصيحة الرأس:**الخيار الأرخص للسياق الطويل (مليون رمز)!#### Kimi K2 ($9/شهر ثابت)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. اشتراك: [Moonshot AI](https://platform.moonshot.ai/)
-2. الحصول على مفتاح API → لوحة المعلومات → إضافة مفتاح API
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**الاستخدام:**`kimi/kimi-latest` —**نصيحة شاملة:**سعر ثابت دفاع 9 دولارات شهريًا مقابل 10 ملايين رمز مميز = 0.90 دولار أمريكي/التكلفة يريد لمليون واحد!### 🆓 مقدمو الخدمات مجانًا#### Qoder (8 FREE models)
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
+
+#### Qoder (8 FREE models)
```bash
Dashboard → Connect Qoder → OAuth login → Unlimited usage
Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1
-````
+```
#### Qwen (3 FREE models)
@@ -190,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -231,22 +268,28 @@ Settings → Models → Advanced:
### Claude Code
-تحرير `~/.claude/config.json`:`json
+Edit `~/.claude/config.json`:
+
+```json
{
"anthropic_api_base": "http://localhost:20128/v1",
- "anthropic_api_key": "مفتاح واجهة برمجة التطبيقات الخاص بك"
-}`
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
-````bash
-تصدير OPENAI_BASE_URL = "http://localhost:20128"
-تصدير OPENAI_API_KEY = "مفتاح واجهة برمجة التطبيقات الخاص بك"
-المخطوطة "المطالبة الخاصة بك"```
+```bash
+export OPENAI_BASE_URL="http://localhost:20128"
+export OPENAI_API_KEY="your-omniroute-api-key"
+codex "your prompt"
+```
### OpenClaw
-تحرير `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
"agents": {
"defaults": {
@@ -264,15 +307,18 @@ Settings → Models → Advanced:
}
}
}
-````
+```
-**أو استخدام معلومات اللوحة:**أدوات CLI → OpenClaw → تفعيل التشغيل### Cline / متابعة / RooCode```
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
+
+```
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -293,9 +339,24 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-يقوم سطر التعديل بتحميل `.env` من `~/.omniroute/.env` أو `./.env`.### VPS Deployment```bash
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
+
+```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute && npm install && npm run build
@@ -309,24 +370,27 @@ export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"
npm run start
-
# Or: pm2 start npm --name omniroute -- start
-
-````
+```
### PM2 Deployment (Low Memory)
-بالنسبة لمكان فقدان الوصول العشوائي المحدودة، استخدم خيار الذاكرة:``bash
-# بحد 512 ميجابايت (افتراضي)
-PM2 ابدأ npm - اسم المسار الشامل - ابدأ
+For servers with limited RAM, use the memory limit option:
-# أو مع حد الذاكرة المخصصة
-OMNIROUTE_MEMORY_MB=512 مساءً2 ابدأ npm --اسم المسار الشامل -- ابدأ
+```bash
+# With 512MB limit (default)
+pm2 start npm --name omniroute -- start
-# أو باستخدام النظام البيئي.config.js
-PM2 ابدأ تشغيل النظام البيئي.config.js```
+# Or with custom memory limit
+OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
-قم بإنشاء "ecosystem.config.js":```javascript
+# Or using ecosystem.config.js
+pm2 start ecosystem.config.js
+```
+
+Create `ecosystem.config.js`:
+
+```javascript
module.exports = {
apps: [
{
@@ -344,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -356,171 +420,181 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-بالنسبة للوضع المدمج مع واجهة CLI، راجع قسم Docker في المستند الرئيسي.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-يمكن لمستخدمي Void Linux حزم OmniRoute وتثبيته محليًا باستخدام إطار عمل مشترك متقاطع `xbps-src`. يؤدي هذا إلى رسم إنشاء Node.js المستقل جنبًا إلى جنب مع الارتباطات الأصلية المطلوبة `better-sqlite3`.
+### Void Linux (xbps-src)
-<التفاصيل>
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
-عرض قالب xbps-src```bash
-# ملف القالب لـ "omniroute"
+
+View xbps-src template
+
+```bash
+# Template file for 'omniroute'
pkgname=omniroute
-الإصدار=3.2.4
-المراجعة=1
-hostmakedepends = "nodejs python3 make"
-يعتمد = "openssl"
-short_desc="بوابة الذكاء الاصطناعي العالمية مع التوجيه الذكي لموفري LLM المتعددين"
-المشرف = "zenobit "
-ترخيص = "معهد ماساتشوستس للتكنولوجيا"
-الصفحة الرئيسية = "https://github.com/diegosouzapw/OmniRoute"
-distfiles = "https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
-المجموع الاختباري=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
-حسابات النظام = "_omniroute"
-omniroute_homedir = "/var/lib/omniroute"
-تصدير NODE_ENV = الإنتاج
-تصدير npm_config_engine_strict=false
-تصدير npm_config_loglevel=خطأ
-تصدير npm_config_fund=false
-تصدير npm_config_audit=false
+version=3.2.4
+revision=1
+hostmakedepends="nodejs python3 make"
+depends="openssl"
+short_desc="Universal AI gateway with smart routing for multiple LLM providers"
+maintainer="zenobit "
+license="MIT"
+homepage="https://github.com/diegosouzapw/OmniRoute"
+distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
+checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
+system_accounts="_omniroute"
+omniroute_homedir="/var/lib/omniroute"
+export NODE_ENV=production
+export npm_config_engine_strict=false
+export npm_config_loglevel=error
+export npm_config_fund=false
+export npm_config_audit=false
-دو_بناء () { # تحديد قوس وحدة المعالجة المركزية المستهدف لـ Node-gyp
-\_gyp_arch المحلي
-الحالة "$XBPS_TARGET_MACHINE" في
-aarch64*) \_gyp_arch=arm64 ;;
-Armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-إسحاق
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) قم بتثبيت كافة الطلبات – تخطي البرامج النصية
- NODE_ENV=تطوير npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) أنشئ حزمة Next.js المستقلة
- بناء تشغيل npm
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) انسخ الأصول الثابتة إلى قائمة بذاتها
- cp -r .next/static .next/standalone/.next/static
- [ -d عام ] && cp -r public .next/standalone/public || صحيح
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) تجميع الربط الأصلي لـ sqlite3 بشكل أفضل
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cdNode_modules/better-sqlite3 && العقدة "$_node_gyp" إعادة البناء --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) ضع الرابط المترجم في الحزمة المستقلة
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- مكدير -p "$_bs3_release"
- cpNode_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) إزالة الحزم الحادة الخاصة بالقوس
- rm -rf .next/standalone/node_modules/@img
-
- # 7) انسخ عمليات حذف وقت التشغيل pino التي تم حذفها بواسطة التحليل الثابت لـ Next.js:
- لـ _mod في تحذير عملية pino-abstract-transport Split2؛ افعل
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- تم
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
-دو_شيك () {
-اختبار تشغيل npm: الوحدة
+do_check() {
+ npm run test:unit
}
-دو_تثبيت () {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+do_install() {
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # منع إزالة توجيهات تطبيق Next.js الفارغة عن طريق ربط ما بعد التثبيت
- ل _د في \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers؛ افعل
- المس "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- تمقطة > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
-#!/بن/ش
-تصدير بورت = "$ {ميناء: -20128}"
-تصدير DATA_DIR = "${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
-تصدير APP_LOG_TO_FILE = "${APP_LOG_TO_FILE:-false}"
-مكدير -p "${DATA_DIR}"
-عقدة exec /usr/lib/omniroute/.next/standalone/server.js "$@"
+ cat > "${WRKDIR}/omniroute" <<'EOF'
+#!/bin/sh
+export PORT="${PORT:-20128}"
+export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
+export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
+mkdir -p "${DATA_DIR}"
+exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
EOF
-فبن "${WRKDIR}/omniroute"
+ vbin "${WRKDIR}/omniroute"
}
-بوست_تثبيت () {
-ترخيص vlicense
-}```
+post_install() {
+ vlicense LICENSE
+}
+```
### Environment Variables
-| متغير | الافتراضي | الوصف |
-| --------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `JWT_SECRET` | `الطريق الشامل الافتراضي السري تغيير لي` | سر توقيع JWT (**تغيير في الإنتاج**) |
-| `INITIAL_PASSWORD` | `123456` | كلمة المرور الأولى لتسجيل الدخول |
-| `DATA_DIR` | `~/.omniroute` | دليل البيانات (ديسيبل، الاستخدام، السجلات) |
-| "ميناء" | الإطار الافتراضي | منفذ الخدمة ('20128` في الأمثلة) |
-| "اسم المضيف" | الإطار الافتراضي | ربط المضيف (إعدادات Docker الافتراضية هي `0.0.0.0`) |
-| `NODE_ENV` | وقت التشغيل الافتراضي | اضبط "الإنتاج" للنشر |
-| `BASE_URL` | `http://localhost:20128` | عنوان URL الأساسي الداخلي من جانب الخادم |
-| `CLOUD_URL` | `https://omniroute.dev` | عنوان URL الأساسي لنقطة نهاية المزامنة السحابية |
-| `API_KEY_SECRET` | `نقطة النهاية-الوكيل-واجهة برمجة التطبيقات-مفتاح-سر` | سر HMAC لمفاتيح API التي تم إنشاؤها |
-| `REQUIRE_API_KEY` | `كاذبة` | فرض مفتاح Bearer API على `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `كاذبة` | السماح لـ Api Manager بنسخ مفاتيح API الكاملة عند الطلب |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | إيقاع التحديث من جانب الخادم لبيانات حدود الموفر المخزنة مؤقتًا؛ لا تزال أزرار تحديث واجهة المستخدم تؤدي إلى المزامنة اليدوية |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `كاذبة` | تعطيل لقطات SQLite التلقائية قبل الكتابة/الاستيراد/الاستعادة؛ النسخ الاحتياطية اليدوية لا تزال تعمل |
-| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `كاذبة` | فرض ملف تعريف ارتباط المصادقة "الآمن" (خلف الوكيل العكسي HTTPS) |
-| `CLOUDFLARED_BIN` | غير محدد | استخدم ملفًا ثنائيًا موجودًا `cloudflared` بدلاً من التنزيل المُدار |
-| `CLOUDFLARED_PROTOCOL` | `http2` | النقل للأنفاق السريعة المُدارة (`http2` أو `quic` أو `auto`) |
-| `OMNIROUTE_MEMORY_MB` | `512` | الحد الأقصى لكومة Node.js بالميجابايت |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | الحد الأقصى لإدخالات ذاكرة التخزين المؤقت السريعة |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | الحد الأقصى لإدخالات ذاكرة التخزين المؤقت الدلالية | للحصول على مرجع متغير البيئة الكامل، راجع [README](../README.md).--- |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
+| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-<التفاصيل>
+
+View all available models
-عرض جميع النماذج المتاحة
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**كود كلود (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`، `cc/claude-sonnet-4-5-20250929`، `cc/claude-haiku-4-5-20251001`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**المخطوطة (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`، `cx/gpt-5.1-codex-max`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**Gemini CLI (`gc/`)**— مجانًا: `gc/gemini-3-flash-preview`، `gc/gemini-2.5-pro`
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GitHub Copilot (`gh/`)**: `gh/gpt-5`، `gh/claude-4.5-sonnet`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**GLM (`glm/`)**— 0.6 دولار/1 مليون: `glm/glm-4.7`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**MiniMax (`minimax/`)**— 0.2 دولار/1 مليون: `minimax/MiniMax-M2.1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qoder (`if/`)**- مجانًا: `if/kimi-k2-thinking`، `if/qwen3-coder-plus`، `if/deepseek-r1`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Qwen (`qw/`)**— مجانًا: `qw/qwen3-coder-plus`، `qw/qwen3-coder-flash`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
-**كيرو (`kr/`)**— مجانًا: `kr/clude-sonnet-4.5`، `kr/claude-haiku-4.5`
+**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
-**DeepSeek (`ds/`)**: `ds/deepseek-chat`، `ds/deepseek-reasoner`
+**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
-**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`، `groq/llama-4-maverick-17b-128e-instruct`
+**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
-**xAI (`xai/`)**: `xai/grok-4`، `xai/grok-4-0709-fast-reasoning`، `xai/grok-code-mini`
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**ميسترال (`ميسترال/`)**: `ميسترال/ميسترال-كبير-2501`، `ميسترال/كودسترال-2501`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**الحيرة (`pplx/`)**: `pplx/sonar-pro`، `pplx/sonar`
-
-**معًا AI (`معًا/`)**: `معًا/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**المخ (`المخ/`)**: `المخ/اللاما-3.3-70ب`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -528,166 +602,202 @@ EOF
### Custom Models
-أضف أي معرف نموذج إلى أي مزود دون انتظار تحديث التطبيق:```bash
+Add any model ID to any provider without waiting for an app update:
+```bash
# Via API
-
curl -X POST http://localhost:20128/api/provider-models \
- -H "Content-Type: application/json" \
- -d '{"provider": "openai", "modelId": "gpt-4.5-preview", "modelName": "GPT-4.5 Preview"}'
+ -H "Content-Type: application/json" \
+ -d '{"provider": "openai", "modelId": "gpt-4.5-preview", "modelName": "GPT-4.5 Preview"}'
# List: curl http://localhost:20128/api/provider-models?provider=openai
-
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
+```
-````
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-أو استخدام معلومات اللوحة:**المزودون → [الموفر] → الارتباطات الارتباطية**.
+Notes:
-التعليقات:
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-- تم إدارة موفري خدمات OpenRouter وOpenAI/Anthropic المتوافقين من**نماذج النماذج**فقط. يمكنك الإضافة اليدوية والاستيراد والنوبات بشكل تلقائي لجميع العناصر الموجودة في نفس قائمة الارتباطات المتاحة، لذلك لا يوجد قسم منفصل للنماذج المخصصة لهؤلاء الموفرين.
-- قسم**النماذج المتخصصة**مخصص للموزعين الذين لا يقومون بإدارة المنتجات المقدمة منهم، استيراد النتائج المتاحة للمصممين.### مسارات موفر مخصصة
+### Dedicated Provider Routes
-توجيه الطلبات مباشرة إلى موفر محدد مع التحقق من صحة النموذج:```bash
-نشر http://localhost:20128/v1/providers/openai/chat/completions
-مشاركة http://localhost:20128/v1/providers/openai/embeddings
-نشر http://localhost:20128/v1/providers/fireworks/images/generations```
-
-تتم إضافة بادئة الموفر تلقائيًا في حالة فقدانها. تُرجع النماذج غير المتطابقة "400".### Network Proxy Configuration
+Route requests directly to a specific provider with model validation:
```bash
-# تعيين الوكيل العالمي
-حليقة -X ضع http://localhost:20128/api/settings/proxy \
- -d '{"global": {"type": "http"، "host": "proxy.example.com"، "port": "8080"}}'
+POST http://localhost:20128/v1/providers/openai/chat/completions
+POST http://localhost:20128/v1/providers/openai/embeddings
+POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-# وكيل لكل مزود
-حليقة -X ضع http://localhost:20128/api/settings/proxy \
- -d '{"providers": {"openai": {"type": "socks5"، "host": "proxy.example.com"، "port": "1080"}}}'
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-# اختبار الوكيل
-حليقة -X POST http://localhost:20128/api/settings/proxy/test \
- -d '{"proxy":{"type": "socks5"، "host": "proxy.example.com"، "port": "1080"}}'```
-
-**الأسبقية:**خاص بالمفتاح ← خاص بالسرد والسرد ← خاص بالموفر ← عالمي ← البيئة.### Model Catalog API
+### Network Proxy Configuration
```bash
-حليقة http://localhost:20128/api/models/catalog```
+# Set global proxy
+curl -X PUT http://localhost:20128/api/settings/proxy \
+ -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
-إرجاع النماذج المجمعة حسب الموفر مع الأنواع (`الدردشة`، و`التضمين`، و`الصورة`).### Cloud Sync
+# Per-provider proxy
+curl -X PUT http://localhost:20128/api/settings/proxy \
+ -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
-- موفري المزامنة والمجموعات والإعدادات عبر الأجهزة
-- مزامنة خلفية تلقائية مع انتهاء المهلة + فشل سريع
-- تفضيل `BASE_URL`/`CLOUD_URL` من جانب الخادم في الإنتاج### Cloudflare Quick Tunnel
+# Test proxy
+curl -X POST http://localhost:20128/api/settings/proxy/test \
+ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
+```
-- متوفر في**Dashboard → Endpoints**لـ Docker وعمليات النشر الأخرى المستضافة ذاتيًا
-- إنشاء عنوان URL مؤقت `https://*.trycloudflare.com` يقوم بإعادة التوجيه إلى نقطة النهاية الحالية المتوافقة مع OpenAI `/v1`
-- قم أولاً بتمكين عمليات التثبيت `cloudflared` فقط عند الحاجة؛ يتم إعادة التشغيل لاحقًا لإعادة استخدام نفس الملف الثنائي المُدار
-- لا تتم استعادة الأنفاق السريعة تلقائيًا بعد إعادة تشغيل OmniRoute أو الحاوية؛ أعد تمكينها من لوحة التحكم عند الحاجة
-- عناوين URL للأنفاق سريعة الزوال وتتغير في كل مرة تقوم فيها بإيقاف/بدء تشغيل النفق
-- الأنفاق السريعة المدارة هي النقل الافتراضي عبر HTTP/2 لتجنب تحذيرات المخزن المؤقت QUIC UDP المزعجة في الحاويات المقيدة
-- قم بتعيين `CLOUDFLARED_PROTOCOL=quic` أو `auto` إذا كنت تريد تجاوز اختيار النقل المُدار
-- قم بتعيين `CLOUDFLARED_BIN` إذا كنت تفضل استخدام الملف الثنائي `cloudflared` المثبت مسبقًا بدلاً من التنزيل المُدار### LLM Gateway Intelligence (Phase 9)
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
--**ذاكرة التخزين المؤقت الدلالية**— ذاكرة تخزين مؤقت تلقائية غير متدفقة، درجة الحرارة = 0 استجابات (تجاوز باستخدام `X-OmniRoute-No-Cache: true`)
--**Request Idempotency**— إلغاء تكرار الطلبات خلال 5 ثوانٍ عبر رأس `Idempotency-Key` أو رأس `X-Request-Id`
--**تتبع التقدم**— الاشتراك في أحداث SSE `الحدث: التقدم` عبر رأس `X-OmniRoute-Progress: true`---
+### Model Catalog API
+
+```bash
+curl http://localhost:20128/api/models/catalog
+```
+
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
+
+### Cloud Sync
+
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
+
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-الوصول عبر**لوحة المعلومات → المترجم**. تصحيح الأخطاء وتصور كيفية قيام OmniRoute بترجمة طلبات واجهة برمجة التطبيقات (API) بين مقدمي الخدمة.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| الوضع | الغرض |
+| Mode | Purpose |
| ---------------- | -------------------------------------------------------------------------------------- |
-|**ساحة اللعب**| حدد تنسيقات المصدر/الهدف، والصق طلبًا، وشاهد المخرجات المترجمة على الفور |
-|**اختبار الدردشة**| أرسل رسائل الدردشة المباشرة من خلال الوكيل وافحص دورة الطلب/الاستجابة الكاملة |
-|**مقعد الاختبار**| قم بإجراء اختبارات مجمعة عبر مجموعات تنسيقات متعددة للتحقق من صحة الترجمة |
-|**مراقبة حية**| شاهد الترجمات في الوقت الفعلي أثناء تدفق الطلبات عبر الوكيل |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**حالات الاستخدام:**
+**Use cases:**
-- تصحيح سبب فشل مجموعة محددة من العميل/الموفر
-- التحقق من ترجمة علامات التفكير واستدعاءات الأدوات ومطالبات النظام بشكل صحيح
-- مقارنة اختلافات التنسيق بين تنسيقات OpenAI وClaude وGemini وResponsions API---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-قم بالتكوين عبر**لوحة المعلومات → الإعدادات → التوجيه**.
+Configure via **Dashboard → Settings → Routing**.
-| استراتيجية | الوصف |
+| Strategy | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------------ |
-|**املأ أولا**| يستخدم الحسابات بترتيب الأولوية — يعالج الحساب الأساسي جميع الطلبات حتى تصبح غير متاحة |
-|**راوند روبن**| للتنقل عبر جميع الحسابات بحد ثابت قابل للتكوين (الافتراضي: 3 مكالمات لكل حساب) |
-|**P2C (قوة الاختيارين)**| يختار حسابين عشوائيين ويوجهك إلى الحساب الأكثر صحة - الأرصدة محملة بالوعي الصحي |
-|**عشوائي**| تحديد حساب عشوائيًا لكل طلب باستخدام خلط Fisher-Yates |
-|**الأقل استخدامًا**| توجيهات إلى الحساب ذو الطابع الزمني الأقدم `lastUsedAt`، مع توزيع حركة المرور بالتساوي |
-|**التكلفة الأمثل**| التوجيهات إلى الحساب ذي أقل قيمة أولوية، مع تحسين موفري الخدمة الأقل تكلفة |#### External Sticky Session Header
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-بالنسبة لتقارب الجلسة الخارجية (على سبيل المثال، وكلاء Claude Code/Codex خلف الوكلاء العكسيين)، أرسل:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
-````
+```
-يقبل OmniRoute أيضًا `x_session_id` ويعيد مفتاح الكلام الفعال في `X-OmniRoute-Session-Id`.
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-إذا كنت تستخدم Nginx وترسل ترويسات على شكل شرطة سفلية، المجاورة بتمكين:`nginx
-underscores_in_headers على؛`
+If you use Nginx and send underscore-form headers, enable:
+
+```nginx
+underscores_in_headers on;
+```
#### Wildcard Model Aliases
-قم بإنشاء أنماط أحرف البدل لإعادة تعيين أسماء النماذج:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-تدعم أحرف البدل `*` (أي حرف) و`?` (حرف واحد).#### السلاسل الاحتياطية
+Wildcards support `*` (any characters) and `?` (single character).
-تحديد الخطوط التقليدية العالمية التي تنطبق على جميع الطلبات:```
-السلسلة: الإنتاج الاحتياطي
- 1. سم مكعب/كلود-أوبوس-4-6
- 2.gh/gpt-5.1-codex
- 3.glm/glm-4.7```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
+Chain: production-fallback
+ 1. cc/claude-opus-4-6
+ 2. gh/gpt-5.1-codex
+ 3. glm/glm-4.7
+```
---
### Resilience & Circuit Breakers
-قم بالتكوين عبر**لوحة المعلومات → الإعدادات → المرونة**.
+Configure via **Dashboard → Settings → Resilience**.
-تطبق OmniRoute المرونة على مستوى المزود من خلال أربعة مكونات:
+OmniRoute implements provider-level resilience with four components:
-1.**ملفات تعريف الموفر**— التكوين لكل موفر لـ:
- - عتبة الفشل (كم عدد حالات الفشل قبل الفتح)
- - مدة التهدئة
- - حساسية الكشف عن حد المعدل
- - معلمات التراجع الأسي
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-2.**حدود المعدل القابلة للتحرير**— الإعدادات الافتراضية على مستوى النظام قابلة للتكوين في لوحة المعلومات:
- -**الطلبات في الدقيقة (RPM)**— الحد الأقصى للطلبات في الدقيقة لكل حساب
- -**الحد الأدنى للوقت بين الطلبات**— الحد الأدنى للفجوة بالمللي ثانية بين الطلبات
- -**الحد الأقصى للطلبات المتزامنة**— الحد الأقصى للطلبات المتزامنة لكل حساب
- - انقر**تحرير**للتعديل، ثم**حفظ**أو**إلغاء**. تستمر القيم عبر واجهة برمجة تطبيقات المرونة.
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
-3.**قاطع الدائرة**— يتتبع حالات الفشل لكل مزود ويفتح الدائرة تلقائيًا عند الوصول إلى الحد الأدنى:
- -**مغلق**(صحي) — تتدفق الطلبات بشكل طبيعي
- -**مفتوح**— تم حظر الموفر مؤقتًا بعد الفشل المتكرر
- -**HALF_OPEN**— اختبار ما إذا كان الموفر قد استعاد عافيته
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-4.**السياسات والمعرفات المقفلة**— تعرض حالة قاطع الدائرة والمعرفات المقفلة مع إمكانية إلغاء القفل بالقوة.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
-5.**الاكتشاف التلقائي لحدود المعدل**— يراقب الرؤوس `429` و`إعادة المحاولة بعد` لتجنب الوصول إلى حدود معدل الموفر بشكل استباقي.
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
-**نصيحة احترافية:**استخدم زر**إعادة تعيين الكل**لمسح جميع قواطع الدائرة وفترات التهدئة عندما يتعافى المزود من انقطاع الخدمة.---
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
+
+---
### Database Export / Import
-إدارة النسخ الاحتياطية لقاعدة البيانات في**لوحة المعلومات → الإعدادات → النظام والتخزين**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| العمل | الوصف |
+| Action | Description |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-|**تصدير قاعدة البيانات**| يقوم بتنزيل قاعدة بيانات SQLite الحالية كملف `.sqlite` |
-|**تصدير الكل (.tar.gz)**| تنزيل أرشيف نسخ احتياطي كامل بما في ذلك: قاعدة البيانات، والإعدادات، والمجموعات، واتصالات الموفر (بدون بيانات اعتماد)، وبيانات تعريف مفتاح API |
-|**استيراد قاعدة البيانات**| قم بتحميل ملف `.sqlite` ليحل محل قاعدة البيانات الحالية. يتم إنشاء نسخة احتياطية للاستيراد المسبق تلقائيًا ما لم `DISABLE_SQLITE_AUTO_BACKUP=true` |```bash
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+
+```bash
# API: Export database
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
@@ -697,93 +807,119 @@ curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
curl -X POST http://localhost:20128/api/db-backups/import \
-F "file=@backup.sqlite"
-````
+```
-**التحقق من صحة الاستيراد:**التحقق من صحة الملف المستورد للتأكد من سلامته (التحقق من صحة الملف المستورد)، والجداول الأساسية (`provider_connections`، و`provider_nodes`، و`combos`، و`api_keys`)، غير (بحد أقصى 100 ميجابايت).
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**حالات الاستخدام:**
+**Use Cases:**
-- رحيل OmniRoute بين الأجهزة
-- إنشاء نسخة احتياطية خارجية للتعافي من الكوارث
-- مشاركة تلكات بين أعضاء الفريق (تصدير الكل → مشاركة الأرشيف)---### Settings Dashboard
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-يتم تنظيم إعدادات الصفحات في 6 علامات مخصصة للتخصيص:
+---
-| علامة التبويب | محتويات |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
-| **عام** | النظام، تحتاج إلى تخزين الأدوات، وعناصر التحكم في الميزات، وإمكانية رؤية الشريط الجانبي لكل العناصر |
-| **الأمن** | إعدادات تسجيل الدخول/كلمة المرور، تسجيل الدخول إلى IP، ومصادقة واجهة برمجة التطبيقات لـ `/models`، وحظر الموفر |
-| **التوجيه** | استراتيجية التوجيه العالمية (6 خيارات)، والأسماء المستعارة لنماذج أحرف البدل، والطرق الاحتياطية، وافتراضيات التحرير والسرد |
-| **المرونة** | ملفات تعريف الموفر، وحدود التصاميم الجميلة للتحرير، وحالة حدود، والسياسات والمعرفات المحجوبة |
-| **الذكاء الاصطناعي** | الاختيار الاختيار، والحقن القصير الشامل، وذاكرة الإحصائيات للتخزين السريع |
-| **متقدم** | المهمة الرسمية العالمية (HTTP/SOCKS5) | ---### Costs & Budget Management |
+### Settings Dashboard
-عبر**لوحة التحكم ← الأسعار**.
+The settings page is organized into 6 tabs for easy navigation:
-| علامة التبويب | الحصاد |
-| ------------- | ---------------------------------------------------------------------------------------------------- | ------- |
-| **الميزانية** | قم بتغطية النطاق الأقصى لكل مفتاح API باستخدام القياسات اليومية/الأسبوعية/الشهرية وتتبع الوقت الفعلي |
-| **التسعير** | نموذج عرض وتحرير التسجيلات الرقمية - التكلفة لكل ألف رمز التسجيل/الإخراج لكل تلفزيون | ```bash |
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
-# API: تحديد الميزانية
+---
-حليقة -X POST http://localhost:20128/api/usage/budget \
- -H "نوع المحتوى: application/json" \
- -d '{"keyId": "key-123"، "الحد": 50.00، "الفترة": "شهريًا"}'
+### Costs & Budget Management
-# API: احصل على حالة الميزانية الحالية
+Access via **Dashboard → Costs**.
-حليقة http://localhost:20128/api/usage/budget```
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
-**تتبع التكلفة:**يقوم كل طلب بتسجيل استخدام الرمز المميز وحساب التكلفة باستخدام جدول التسعير. عرض التفاصيل في**لوحة المعلومات → الاستخدام**حسب الموفر والطراز ومفتاح واجهة برمجة التطبيقات.---
+```bash
+# API: Set a budget
+curl -X POST http://localhost:20128/api/usage/budget \
+ -H "Content-Type: application/json" \
+ -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
+
+# API: Get current budget status
+curl http://localhost:20128/api/usage/budget
+```
+
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-يدعم OmniRoute النسخ الصوتي عبر نقطة النهاية المتوافقة مع OpenAI:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-الموفرون متاحون:**Deepgram**(`deepgram/`)،**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-تنسيقات الصوت المدعومة: `mp3`، `wav`، `m4a`، `flac`، `ogg`، `webm`.---### Combo Balancing Strategies
+---
-قم بتكوين مجموعة متنوعة في**لوحة المعلومات → المجموعات → إنشاء/تحرير → اختيار**.
+### Combo Balancing Strategies
-| استراتيجية | الوصف |
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
+
+| Strategy | Description |
| ------------------ | ------------------------------------------------------------------------ |
-|**جولة روبن**| التفاعل عبر الاتجاهات بالتتابع |
-|**الأولوية**| يحاول دائمًا النموذج الأول؛ لا يعود إلا على الخطأ |
-|**عشوائي**| اختيار نموذجًا من المجموعة لكل طلب |
-|**المولد**| تعتمد المسارات بشكل يتناسب مع الوزن المخصص لكل نموذج |
-|**الأقل استخدامًا**| توجيهات إلى النموذج الذي يحتوي على أقل عدد من الطلبات الأخيرة (يستخدم مقاييس التحرير والسرد) |
-|**التكلفة المقررة**| الطريق إلى خيارات الخيارات (يستخدم جدول التسعير) |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-يمكن ضبط إعدادات التحرير والسرد العام في**لوحة المعلومات → الإعدادات → التوجيه → إعدادات التحرير والسرد الافتراضي**.---### Health Dashboard
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
-عبر**لوحة التحكم → الصحة**. نظرة عامة على صحة النظام في الوقت الحقيقي مع 6 بطاقات:
+---
-| بطاقة | ما يظهر |
+### Health Dashboard
+
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
+
+| Card | What It Shows |
| --------------------- | ----------------------------------------------------------- |
-|**حالة النظام**| وقت التشغيل، الإصدار، استخدام الذاكرة، دليل البيانات |
-|**صحة المزود**| حالة فاصل كهربائي لكل الدائرة (مغلق/مفتوح/نصف مفتوح) |
-|**حدود التعديل**| لتهدئة بعض التغيير لأي حساب مع الوقت المؤقت |
-|**عمليات التأمين العضوي**| تم حظر مقدمي الخدمة مؤقتًا بواسطة شركة التأمين للتأمين |
-|**ذاكرة تخزين مؤقت للتوقيع**| إحصائيات إلغاء البيانات المكررة (المفاتيح العضوية، معدل الدخول) |
-|**قياس زمن الوصول**| p50/p95/p99 تجميع زمن الوصول لكل حدود |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**نصيحة شاملة:**يتم تحديث صفحة الصحة الطازجة كل 10. استخدم بطاقة القاطع للخدمة المقدمة الذين يستفيدون.---## 🖥️ Desktop Application (Electron)
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
-يسمى OmniRoute كتطبيق سطح المكتب الأصلي لأنظمة التشغيل Windows وmacOS وLinux.### تثبيت```bash
+---
+
+## 🖥️ Desktop Application (Electron)
+
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### تثبيت
+
+```bash
# From the electron directory:
cd electron
npm install
@@ -793,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -805,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-المنتج → ``الإلكترون/توزيع الإلكترون/`### الميزات الرئيسية
+Output → `electron/dist-electron/`
-| غرض | الوصف |
-| ------------------------ | -------------------------------------------------------- | ------------------ |
-| **جاهزة للخدم** | وكيلات قبل بدء التشغيل (لا توجد شاشة كافية) |
-| **علبة النظام** | تصغير إلى المرحاض، تغيير الشراب، والخروج من قائمة الدرج |
-| **إدارة المشاريع** | تغيير مدير الخادم من الدرج (خادم إعادة التشغيل التلقائي) |
-| **سياسة امان المحتوى** | ليس CSP عبر الحروف اللامكانية |
-| **مثيل واحد** | يمكن تشغيل تطبيق واحد فقط في الاستخدام |
-| **وضع غير متصل بالشبكة** | خادم Next.js المجمع يعمل بدون إنترنت | ### متغيرات البيئة |
+### Key Features
-| فنية | افتراضي | الوصف |
-| --------------------- | ------- | --------------------------------------------- |
-| `OMNIROUTE_PORT` | `20128` | منفذ الخادم |
-| `OMNIROUTE_MEMORY_MB` | `512` | الحد الأقصى لكومة Node.js (64–16384 ميجابايت) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 التوثيق الكامل: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/bg/README.md b/docs/i18n/bg/README.md
index f0bfe4f98d..d51568fa44 100644
--- a/docs/i18n/bg/README.md
+++ b/docs/i18n/bg/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/bg/docs/USER_GUIDE.md b/docs/i18n/bg/docs/USER_GUIDE.md
index b8abb5ca7e..5c0d7f9642 100644
--- a/docs/i18n/bg/docs/USER_GUIDE.md
+++ b/docs/i18n/bg/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Пълно ръководство за конфигуриране на доставчици, създаване на комбинации, интегриране на CLI инструменти и внедряване на OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Ценообразуване с един поглед](#-pricing-at-a-glance)
-- [Случаи на употреба](#-случаи на употреба)
-- [Настройка на доставчик](#-provider-setup)
-- [CLI интеграция](#-cli-интеграция)
-- [Разгръщане](#-разгръщане)
-- [Налични модели](#-налични-модели)
-- [Разширени функции](#-advanced-features)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 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** | DeepSeek | Плащане за използване | Няма | Евтини разсъждения |
-| | Groq | Плащане за използване | Няма | Свръхбърз извод |
-| | xAI (Grok) | Плащане за използване | Няма | Грок 4 разсъждения |
-| | Мистрал | Плащане за използване | Няма | Хоствани в ЕС модели |
-| | Недоумение | Плащане за използване | Няма | Разширено търсене |
-| | Заедно AI | Плащане за използване | Няма | Модели с отворен код |
-| | Фойерверки AI | Плащане за използване | Няма | Бързи FLUX изображения |
-| | Мозъци | Плащане за използване | Няма | Скорост на вафла |
-| | Cohere | Плащане за използване | Няма | Команда R+ RAG |
-| | NVIDIA NIM | Плащане за използване | Няма | Корпоративни модели |
-| **💰 ЕВТИНО** | GLM-4.7 | $0,6/1 милион | Ежедневно 10 сутринта | Резервно копие на бюджета |
-| | MiniMax M2.1 | $0,2/1 милион | 5-часово търкаляне | Най-евтиният вариант |
-| | Кими К2 | $9/месец апартамент | 10 милиона токена/месец | Предвидими разходи |
-| **🆓 БЕЗПЛАТНО** | Qoder | $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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Професионален съвет:**Започнете с Gemini CLI (180K безплатно/месец) + Qoder (неограничено безплатно) комбо = $0 цена!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Проблем:**Квотата изтича неизползвана, ограничения на скоростта по време на тежко кодиране```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Проблем:**Не мога да си позволя абонаменти, имам нужда от надеждно AI кодиране```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Проблем:**Крайни срокове, не мога да си позволя престой```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Проблем:**Имате нужда от AI асистент в приложенията за съобщения, напълно безплатно```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**Професионален съвет:**Използвайте Opus за сложни задачи, Sonnet за скорост. OmniRoute проследява квота за модел!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Най-добра стойност:**Огромно безплатно ниво! Използвайте това преди платените нива.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### GLM-4.7 (Daily reset, $0.6/1M)
-1. Регистрирайте се: [Zhipu AI](https://open.bigmodel.cn/)
-2. Вземете API ключ от Coding Plan
-3. Табло → Добавяне на API ключ: Доставчик: `glm`, API ключ: `вашият-ключ`
+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` —**Професионален съвет:**Планът за кодиране предлага 3× квота на цена 1/7! Нулирайте всеки ден в 10:00 ч.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Регистрирайте се: [MiniMax](https://www.minimax.io/)
-2. Вземете API ключ → Табло → Добавете API ключ
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Използвайте:**`minimax/MiniMax-M2.1` —**Професионален съвет:**Най-евтината опция за дълъг контекст (1M токени)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Абонирайте се: [Moonshot AI](https://platform.moonshot.ai/)
-2. Вземете API ключ → Табло → Добавете API ключ
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Използване:**`kimi/kimi-latest` —**Професионален съвет:**Фиксирани $9/месец за 10 милиона токена = $0,90/1 милион ефективна цена!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Редактирайте `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Settings → Models → Advanced:
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Редактирайте `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Или използвайте таблото за управление:**CLI инструменти → OpenClaw → Автоматично конфигуриране### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI автоматично зарежда `.env` от `~/.omniroute/.env` или `./.env`.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-За сървъри с ограничена RAM използвайте опцията за ограничаване на паметта:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Създайте `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,13 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-За интегриран в хост режим с двоични файлове на CLI вижте раздела Docker в основните документи.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Потребителите на Void Linux могат да пакетират и инсталират OmniRoute естествено, като използват рамката за кръстосано компилиране `xbps-src`. Това автоматизира самостоятелната компилация на Node.js заедно с необходимите нативни свързвания `better-sqlite3`.
+### Void Linux (xbps-src)
-<подробности>
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
-Преглед на шаблона xbps-src```bash
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -409,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -476,60 +516,63 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Променлива | По подразбиране | Описание |
-| ----------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | Тайна за подписване на JWT (**промяна в производството**) |
-| `ПЪРВОНАЧАЛНА_ПАРОЛА` | „123456“ | Първа парола за влизане |
-| `DATA_DIR` | `~/.omniroute` | Директория с данни (db, използване, регистрационни файлове) |
-| `ПОРТ` | рамка по подразбиране | Сервизен порт („20128“ в примерите) |
-| `ИМЕ НА ХОСТА` | рамка по подразбиране | Свързване на хост (Docker по подразбиране е `0.0.0.0`) |
-| `NODE_ENV` | по подразбиране по време на изпълнение | Задайте `production` за внедряване |
-| `ОСНОВЕН_URL` | `http://localhost:20128` | Вътрешен основен URL адрес от страната на сървъра |
-| `CLOUD_URL` | `https://omniroute.dev` | Основен URL адрес на крайна точка за синхронизиране в облак |
-| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC тайна за генерирани API ключове |
-| `REQUIRE_API_KEY` | `false` | Налагане на API ключ на носител на `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `false` | Разрешаване на Api Manager да копира пълни API ключове при поискване |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Честота на опресняване от страна на сървъра за кеширани данни за ограниченията на доставчика; Бутоните за опресняване на потребителския интерфейс все още задействат ръчно синхронизиране |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Деактивирайте автоматичните моментни снимки на SQLite преди запис/импорт/възстановяване; ръчните архиви все още работят |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `false` | Принудително `Secure` бисквитка за удостоверяване (зад HTTPS обратен прокси) |
-| `CLOUDFLARED_BIN` | деактивирано | Използвайте съществуващ двоичен файл `cloudflared` вместо управлявано изтегляне |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Транспорт за управлявани бързи тунели (`http2`, `quic` или `auto`) |
-| `OMNIROUTE_MEMORY_MB` | „512“ | Ограничение на купчината на Node.js в MB |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | Максимални записи в кеша за подкани |
-| `SEMANTIC_CACHE_MAX_SIZE` | „100“ | Максимални семантични записи в кеша |За пълната справка за променливите на средата вижте [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-<подробности>
-Вижте всички налични модели
+
+View all available models
-**Claude Code (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— БЕЗПЛАТНО: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— $0,6/1M: `glm/glm-4,7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— $0,2/1M: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— БЕЗПЛАТНО: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— БЕЗПЛАТНО: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— БЕЗПЛАТНО: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
@@ -537,9 +580,9 @@ vlicense LICENSE
**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
-**Мистрал (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Обърканост (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
@@ -549,7 +592,9 @@ vlicense LICENSE
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -557,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Добавете всеки ID на модел към всеки доставчик, без да чакате актуализация на приложението:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -565,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Или използвайте таблото за управление:**Доставчици → [Доставчик] → Персонализирани модели**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Бележки:
+Notes:
-- OpenRouter и OpenAI/Anthropic-съвместими доставчици се управляват само от**Налични модели**. Ръчното добавяне, импортиране и автоматично синхронизиране се намира в един и същ списък с налични модели, така че няма отделен раздел за персонализирани модели за тези доставчици.
-- Секцията**Персонализирани модели**е предназначена за доставчици, които не излагат импортиране на управлявани налични модели.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Насочвайте заявките директно към конкретен доставчик с валидиране на модела:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Префиксът на доставчика се добавя автоматично, ако липсва. Несъответстващите модели връщат „400“.### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -595,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Приоритет:**Специфичен за ключ → Специфичен за комбинация → Специфичен за доставчик → Глобален → Среда.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Връща модели, групирани по доставчик с типове („чат“, „вграждане“, „изображение“).### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Синхронизиране на доставчици, комбинации и настройки на всички устройства
-- Автоматична фонова синхронизация с изчакване + бързо отказване
-- Предпочитайте `BASE_URL`/`CLOUD_URL` от страна на сървъра в производството### Cloudflare Quick Tunnel
+### Cloud Sync
-- Предлага се в**Табло за управление → Крайни точки**за Docker и други самостоятелно хоствани внедрявания
-- Създава временен URL адрес `https://*.trycloudflare.com`, който препраща към текущата ви крайна точка `/v1`, съвместима с OpenAI
-- Първо активиране инсталира `cloudflared` само когато е необходимо; по-късно рестартира повторно използване на същия управляван двоичен файл
-- Бързите тунели не се възстановяват автоматично след рестартиране на OmniRoute или контейнер; активирайте ги отново от таблото за управление, когато е необходимо
-- URL адресите на тунелите са ефимерни и се променят всеки път, когато спрете/пуснете тунела
-- Управляваните бързи тунели по подразбиране са HTTP/2 транспорт, за да се избегнат шумни QUIC UDP буферни предупреждения в ограничени контейнери
-- Задайте `CLOUDFLARED_PROTOCOL=quic` или `auto`, ако искате да отмените избора на управляван транспорт
-- Задайте `CLOUDFLARED_BIN`, ако предпочитате да използвате предварително инсталиран двоичен файл `cloudflared` вместо управлявано изтегляне### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Семантичен кеш**— Автоматично кешира не-стрийминг, температура=0 отговори (заобикаляне с `X-OmniRoute-No-Cache: true`) -**Request Idempotency**— Дедупликира заявките в рамките на 5s чрез `Idempotency-Key` или `X-Request-Id` хедър -**Проследяване на напредъка**— Включване на SSE `event: progress` събития чрез `X-OmniRoute-Progress: true` хедър---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Достъп чрез**Табло → Преводач**. Отстранете грешки и визуализирайте как OmniRoute превежда API заявки между доставчици.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Режим | Цел |
-| ------------------- | ---------------------------------------------------------------------------------------------------- |
-| **Детска площадка** | Изберете изходни/целеви формати, поставете заявка и незабавно вижте преведения резултат |
-| **Чат тестер** | Изпращайте чат съобщения на живо през проксито и проверявайте пълния цикъл на заявка/отговор |
-| **Тестова стенда** | Изпълнете групови тестове в множество комбинации от формати, за да проверите правилността на превода |
-| **Монитор на живо** | Гледайте преводи в реално време, докато заявките преминават през проксито |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Случаи на употреба:**
+**Use cases:**
-- Отстраняване на грешки защо конкретна комбинация клиент/доставчик е неуспешна
-- Проверете дали мислещите тагове, извикванията на инструменти и системните подкани се превеждат правилно
-- Сравнете разликите във форматите между форматите OpenAI, Claude, Gemini и Responses API---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Конфигурирайте чрез**Табло → Настройки → Маршрутизация**.
+Configure via **Dashboard → Settings → Routing**.
-| Стратегия | Описание |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Първо попълване** | Използва акаунти в приоритетен ред — основният акаунт обработва всички заявки, докато стане недостъпен |
-| **Round Robin** | Преминава през всички акаунти с конфигурируем лепкав лимит (по подразбиране: 3 обаждания на акаунт) |
-| **P2C (Сила на два избора)** | Избира 2 произволни акаунта и маршрути към по-здравословния — балансира натоварването с осъзнаване на здравето |
-| **Произволно** | Произволно избира акаунт за всяка заявка чрез разбъркване на Fisher-Yates |
-| **Най-малко използвани** | Маршрути към акаунта с най-стария времеви печат `lastUsedAt`, разпределящ трафика равномерно |
-| **Оптимизирани разходи** | Маршрути към акаунта с най-ниска стойност на приоритет, оптимизиране за доставчици с най-ниска цена | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-За афинитет към външна сесия (например агенти на Claude Code/Codex зад обратни прокси сървъри), изпратете:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute също приема `x_session_id` и връща ефективния сесиен ключ в `X-OmniRoute-Session-Id`.
+If you use Nginx and send underscore-form headers, enable:
-Ако използвате Nginx и изпращате заглавки на формуляр с долна черта, активирайте:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Създайте шаблони със заместващи знаци, за да пренасочите имената на моделите:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Заместващите символи поддържат `*` (всякакви знаци) и `?` (единичен знак).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Дефинирайте глобални резервни вериги, които се прилагат за всички заявки:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Конфигурирайте чрез**Табло → Настройки → Устойчивост**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute прилага устойчивост на ниво доставчик с четири компонента:
+OmniRoute implements provider-level resilience with four components:
-1.**Профили на доставчици**— Конфигурация за всеки доставчик за:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Праг на повреда (колко повреда преди отваряне)
-- Продължителност на изчакване
-- Чувствителност на откриване на ограничение на скоростта
-- Параметри на експоненциално отстъпление
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Редактируеми ограничения на скоростта**— Настройки по подразбиране на системно ниво, които могат да се конфигурират в таблото за управление: -**Заявки в минута (RPM)**— Максимален брой заявки в минута за акаунт -**Минимално време между заявките**— Минимална разлика в милисекунди между заявките -**Максимални едновременни заявки**— Максимални едновременни заявки за акаунт
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Щракнете върху**Редактиране**, за да промените, след това върху**Запазване**или**Отказ**. Стойностите се запазват чрез API за устойчивост.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Прекъсвач на веригата**— Проследява повреди на доставчик и автоматично отваря веригата при достигане на праг: -**ЗАТВОРЕНО**(здравословно) — Заявките протичат нормално -**OPEN**— Доставчикът е временно блокиран след повтарящи се повреди -**HALF_OPEN**— Тестване дали доставчикът се е възстановил
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Правила и заключени идентификатори**— Показва състоянието на прекъсвача и заключените идентификатори с възможност за принудително отключване.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Автоматично откриване на лимита на скоростта**— Наблюдава заглавките `429` и `Retry-After`, за да избегне проактивно достигане на лимитите на скоростта на доставчика.
-
-**Професионален съвет:**Използвайте бутона**Нулиране на всички**, за да изчистите всички прекъсвачи и изчаквания, когато доставчикът се възстанови от прекъсване.---
+---
### Database Export / Import
-Управлявайте резервни копия на бази данни в**Табло → Настройки → Система и съхранение**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Действие | Описание |
-| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Експортиране на база данни** | Изтегля текущата база данни SQLite като `.sqlite` файл |
-| **Експортиране на всички (.tar.gz)** | Изтегля пълен резервен архив, включително: база данни, настройки, комбинации, връзки с доставчик (без идентификационни данни), API ключ метаданни |
-| **Импортиране на база данни** | Качете файл `.sqlite`, за да замените текущата база данни. Резервно копие преди импортиране се създава автоматично, освен ако `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Проверка на импортиране:**Импортираният файл се валидира за целостта (проверка на SQLite pragma), необходимите таблици (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) и размер (макс. 100MB).
+**Use Cases:**
-**Случаи на употреба:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Мигрирайте OmniRoute между машини
-- Създаване на външни резервни копия за възстановяване след бедствие
-- Споделяне на конфигурации между членовете на екипа (експортиране на всички → споделяне на архив)---
+---
### Settings Dashboard
-Страницата с настройки е организирана в 6 раздела за лесна навигация:
+The settings page is organized into 6 tabs for easy navigation:
-| Раздел | Съдържание |
+| Tab | Contents |
| -------------- | ---------------------------------------------------------------------------------------------- |
-|**Общи**| Системни инструменти за съхранение, настройки за външен вид, контроли на теми и видимост на страничната лента |
-|**Сигурност**| Настройки за вход/парола, IP контрол на достъпа, API удостоверяване за `/models` и блокиране на доставчик |
-|**Маршрутизиране**| Стратегия за глобално маршрутизиране (6 опции), псевдоними на модели със заместващи символи, резервни вериги, комбинирани настройки по подразбиране |
-|**Устойчивост**| Профили на доставчици, редактируеми лимити на скоростта, състояние на прекъсвача, политики и заключени идентификатори |
-|**AI**| Обмисляне на конфигурация на бюджета, инжектиране на глобална система, статистика на бързия кеш |
-|**Разширено**| Глобална прокси конфигурация (HTTP/SOCKS5) |---
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Достъп чрез**Табло → Разходи**.
+Access via **Dashboard → Costs**.
-| Раздел | Цел |
+| Tab | Purpose |
| ----------- | ---------------------------------------------------------------------------------------- |
-|**Бюджет**| Задайте лимити на разходите за API ключ с дневни/седмични/месечни бюджети и проследяване в реално време |
-|**Цени**| Преглеждайте и редактирайте записи за ценообразуване на модела — цена за 1K входно/изходни токени на доставчик |```bash
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -766,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Проследяване на разходите:**Всяка заявка регистрира използването на токени и изчислява разходите с помощта на ценовата таблица. Вижте разбивки в**Табло за управление → Използване**по доставчик, модел и API ключ.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute поддържа аудио транскрипция чрез OpenAI-съвместима крайна точка:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Налични доставчици:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Поддържани аудио формати: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.---
+---
### Combo Balancing Strategies
-Конфигурирайте балансирането за комбо в**Табло за управление → Комбота → Създаване/Редактиране → Стратегия**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Стратегия | Описание |
+| Strategy | Description |
| ------------------ | ------------------------------------------------------------------------ |
-|**Round-Robin**| Върти се през моделите последователно |
-|**Приоритет**| Винаги пробва първия модел; връща се само при грешка |
-|**Произволно**| Избира произволен модел от комбинацията за всяка заявка |
-|**Претеглено**| Маршрути пропорционално въз основа на зададени тегла за модел |
-|**Най-малко използвани**| Насочва към модела с най-малко скорошни заявки (използва комбинирани показатели) |
-|**Оптимизиран за разходите**| Маршрути до най-евтиния наличен модел (използва ценова таблица) |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Глобалните настройки по подразбиране на комбинацията могат да бъдат зададени в**Табло → Настройки → Маршрут → Настройки по подразбиране на комбинация**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Достъп чрез**Табло → Здраве**. Преглед на здравето на системата в реално време с 6 карти:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Карта | Какво показва |
-| --------------------- | ------------------------------------------------------------ |
-|**Състояние на системата**| Време на работа, версия, използване на паметта, директория с данни |
-|**Здраве на доставчика**| Състояние на прекъсвача за всеки доставчик (затворен/отворен/полуотворен) |
-|**Ограничения на скоростта**| Активен лимит на изчакване за акаунт с оставащо време |
-|**Активни блокировки**| Доставчици, временно блокирани от политиката за блокиране |
-|**Кеш на подписа**| Статистика на кеша за дедупликация (активни ключове, процент на попадения) |
-|**Телеметрия за забавяне**| p50/p95/p99 агрегиране на латентност за доставчик |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Професионален съвет:**Страницата Health се опреснява автоматично на всеки 10 секунди. Използвайте картата на прекъсвача, за да идентифицирате кои доставчици имат проблеми.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute се предлага като родно настолно приложение за Windows, macOS и Linux.### Инсталиране
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Инсталиране
```bash
# From the electron directory:
@@ -834,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -846,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Изход → `electron/dist-electron/`### Key Features
+Output → `electron/dist-electron/`
-| Характеристика | Описание |
-| ---------------------------------------- | ------------------------------------------------------------------- | ------------------------- |
-| **Готовност на сървъра** | Анкета на сървъра преди показване на прозорец (без празен екран) |
-| **Системна област** | Минимизиране в трея, промяна на порта, изход от менюто на трея |
-| **Управление на портове** | Промяна на сървърния порт от трея (автоматично рестартира сървъра) |
-| **Правила за сигурност на съдържанието** | Ограничителен CSP чрез заглавки на сесии |
-| **Единичен екземпляр** | Само един екземпляр на приложение може да се изпълнява едновременно |
-| **Офлайн режим** | Пакетът Next.js сървър работи без интернет | ### Environment Variables |
+### Key Features
-| Променлива | По подразбиране | Описание |
-| --------------------- | --------------- | ------------------------------------------------- |
-| `OMNIROUTE_PORT` | `20128` | Порт на сървъра |
-| `OMNIROUTE_MEMORY_MB` | „512“ | Ограничение на купчината на Node.js (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Пълна документация: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/cs/README.md b/docs/i18n/cs/README.md
index e705c383a2..b303bf4c62 100644
--- a/docs/i18n/cs/README.md
+++ b/docs/i18n/cs/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/cs/docs/USER_GUIDE.md b/docs/i18n/cs/docs/USER_GUIDE.md
index 1cd09b5aab..7f22f69705 100644
--- a/docs/i18n/cs/docs/USER_GUIDE.md
+++ b/docs/i18n/cs/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Kompletní průvodce pro konfiguraci poskytovatelů, vytváření kombinací, integraci nástrojů CLI a nasazení OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Přehled cen](#-pricing-at-a-glance)
-- [Případy použití](#-případů použití)
-- [Nastavení poskytovatele](#-provider-setup)
-- [Integrace CLI](#-cli-integrace)
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
- [Deployment](#-deployment)
-- [Dostupné modely](#-dostupných-modelů)
-- [Pokročilé funkce](#-pokročilých-funkcí)---
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 Pricing at a Glance
-| Úroveň | Poskytovatel | Cena | Obnovení kvóty | Nejlepší pro |
-| ----------------- | ----------------- | ----------------- | --------------------------- | -------------------------- |
-| **💳 PŘEDPLATNÉ** | Claude Code (Pro) | 20 $/měsíc | 5h + týdně | Již přihlášeno |
-| | Codex (Plus/Pro) | 20–200 USD/měsíc | 5h + týdně | Uživatelé OpenAI |
-| | Gemini CLI | **ZDARMA** | 180 tis./měsíc + 1 tis./den | Každý! |
-| | GitHub Copilot | 10–19 USD/měsíc | Měsíčně | Uživatelé GitHubu |
-| **🔑 API KEY** | DeepSeek | Platba za použití | Žádné | Levné uvažování |
-| | Groq | Platba za použití | Žádné | Ultra-rychlé odvození |
-| | xAI (Grok) | Platba za použití | Žádné | Grok 4 zdůvodnění |
-| | Mistral | Platba za použití | Žádné | Modely hostované EU |
-| | Zmatenost | Platba za použití | Žádné | Rozšířené vyhledávání |
-| | Společně AI | Platba za použití | Žádné | Open-source modely |
-| | Ohňostroje AI | Platba za použití | Žádné | Fast FLUX obrázky |
-| | Cerebras | Platba za použití | Žádné | Rychlost waferové stupnice |
-| | Cohere | Platba za použití | Žádné | Příkaz R+ RAG |
-| | NVIDIA NIM | Platba za použití | Žádné | Podnikové modely |
-| **💰 LEVNĚ** | GLM-4.7 | 0,6 $/1 mil. | Denně 10:00 | Záloha rozpočtu |
-| | MiniMax M2.1 | 0,2 $/1 milion | 5hodinové válcování | Nejlevnější varianta |
-| | Kimi K2 | 9 $/měsíc byt | 10 milionů tokenů/měsíc | Předvídatelné náklady |
-| **🆓 ZDARMA** | Qoder | 0 $ | Neomezené | 8 modelů zdarma |
-| | Qwen | 0 $ | Neomezené | 3 modely zdarma |
-| | Kiro | 0 $ | Neomezené | Claude zdarma |
+| 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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Tip pro profesionály:**Začněte s Gemini CLI (180 000 zdarma/měsíc) + kombinace Qoder (bez omezení zdarma) = cena 0 $!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Problém:**Kvóta vyprší nevyužita, rychlostní limity při náročném kódování```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Problém:**Nemohu si dovolit předplatné, potřebujete spolehlivé kódování AI```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Problém:**Termíny, nemohu si dovolit prostoje```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Problém:**Potřebujete asistenta AI v aplikacích pro zasílání zpráv, zcela zdarma```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**Tip pro profesionály:**Používejte Opus pro složité úkoly, Sonnet pro rychlost. OmniRoute sleduje kvótu na model!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Nejlepší hodnota:**Obrovská bezplatná úroveň! Použijte to před placenými úrovněmi.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### GLM-4.7 (Daily reset, $0.6/1M)
-1. Zaregistrujte se: [Zhipu AI](https://open.bigmodel.cn/)
-2. Získejte API klíč z Coding Plan
-3. Panel → Přidat klíč API: Poskytovatel: `glm`, Klíč API: `váš klíč`
+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žití:**`glm/glm-4,7` —**Tip pro profesionály:**Kódovací plán nabízí 3× kvótu za 1/7 cenu! Resetovat denně v 10:00.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Zaregistrujte se: [MiniMax](https://www.minimax.io/)
-2. Získat klíč API → Řídicí panel → Přidat klíč API
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Použití:**`minimax/MiniMax-M2.1` —**Tip pro profesionály:**Nejlevnější možnost pro dlouhý kontext (1 milion tokenů)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Přihlaste se k odběru: [Moonshot AI](https://platform.moonshot.ai/)
-2. Získat klíč API → Řídicí panel → Přidat klíč API
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Použití:**`kimi/kimi-nejnovější` —**Tip pro profesionály:**Pevná cena 9 $ měsíčně za 10 milionů tokenů = 0,90 $ / 1 milion efektivních nákladů!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Upravit `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Upravit `~/.claude/config.json`:```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Upravit `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Nebo použijte Dashboard:**Nástroje CLI → OpenClaw → Auto-config### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI automaticky načte `.env` z `~/.omniroute/.env` nebo `./.env`.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-U serverů s omezenou pamětí RAM použijte možnost omezení paměti:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Vytvořte `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,12 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-Informace o režimu integrovaném do hostitele s binárními soubory CLI naleznete v části Docker v hlavních dokumentech.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Uživatelé Void Linuxu mohou zabalit a nainstalovat OmniRoute nativně pomocí rámce křížové kompilace `xbps-src`. To automatizuje samostatné sestavení Node.js spolu s požadovanými nativními vazbami `better-sqlite3`.
+### Void Linux (xbps-src)
-
-Zobrazit šablonu xbps-src```bash
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -408,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -475,64 +516,67 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Proměnná | Výchozí | Popis |
-| ---------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | Tajemství podpisu JWT (**změna výroby**) |
-| `VÝCHOZÍ_HESLO` | "123456" | První přihlašovací heslo |
-| `DATA_DIR` | `~/.omniroute` | Datový adresář (db, využití, protokoly) |
-| "PORT" | výchozí rámec | Port služby (v příkladech `20128`) |
-| `HOSTNAME` | výchozí rámec | Svázat hostitele (výchozí nastavení Dockeru je `0.0.0.0`) |
-| `NODE_ENV` | výchozí runtime | Nastavte `produkci` pro nasazení |
-| `BASE_URL` | `http://localhost:20128` | Interní základní URL na straně serveru |
-| `CLOUD_URL` | `https://omniroute.dev` | Základní URL koncového bodu synchronizace cloudu |
-| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Tajný klíč HMAC pro generované klíče API |
-| `REQUIRE_API_KEY` | "nepravda" | Vynutit klíč rozhraní API nosiče na `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | "nepravda" | Povolit Api Manager kopírovat úplné klíče API na vyžádání |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | "70" | Obnovovací kadence na straně serveru pro data o limitech poskytovatelů uložená v mezipaměti; Tlačítka pro obnovení uživatelského rozhraní stále spouštějí ruční synchronizaci |
-| `DISABLE_SQLITE_AUTO_BACKUP` | "nepravda" | Zakázat automatické snímky SQLite před zápisem/importem/obnovením; ruční zálohování stále funguje |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | "nepravda" | Vynutit `Secure` auth cookie (za HTTPS reverzní proxy) |
-| `CLOUDFLARED_BIN` | odstaveno | Místo řízeného stahování použijte existující binární soubor `cloudflared` |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Transport pro spravované rychlé tunely (`http2`, `quic` nebo `auto`) |
-| `OMNIROUTE_MEMORY_MB` | "512" | Limit haldy Node.js v MB |
-| `PROMPT_CACHE_MAX_SIZE` | "50" | Max promptní položky mezipaměti |
-| `SEMANTIC_CACHE_MAX_SIZE` | "100" | Maximální počet záznamů sémantické mezipaměti |Úplný odkaz na proměnné prostředí naleznete v [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Zobrazit všechny dostupné modely
+
+View all available models
-**Kód Claude (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— ZDARMA: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4,5-sonnet`
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— 0,6 $/1 milion: `glm/glm-4,7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— 0,2 $/1 milion: `minimax/MiniMax-M2,1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— ZDARMA: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— ZDARMA: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— ZDARMA: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
-**Groq (`groq/`)**: `groq/lama-3.3-70b-versatile`, `groq/lama-4-maverick-17b-128e-instruct`
+**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
@@ -540,15 +584,17 @@ vlicense LICENSE
**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**Together AI (`together/`)**: `together/meta-lama/Llama-3.3-70B-Instruct-Turbo`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**Fireworks AI (`ohňostroje/`)**: `ohňostroje/účty/ohňostroje/modely/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**Cerebras (`cerebras/`)**: `cerebras/lama-3.3-70b`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -556,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Přidejte jakékoli ID modelu k libovolnému poskytovateli bez čekání na aktualizaci aplikace:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -564,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Nebo použijte Dashboard:**Poskytovatelé → [Poskytovatel] → Vlastní modely**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Poznámky:
+Notes:
-- OpenRouter a poskytovatelé kompatibilní s OpenAI/Anthropic jsou spravováni pouze z**Available Models**. Ručně přidávejte, importujte a automaticky synchronizujte všechny pozemky ve stejném seznamu dostupných modelů, takže pro tyto poskytovatele neexistuje žádná samostatná sekce Vlastní modely.
- – Sekce**Vlastní modely**je určena poskytovatelům, kteří nevystavují importy spravovaných dostupných modelů.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Směrujte požadavky přímo ke konkrétnímu poskytovateli s ověřením modelu:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Pokud chybí předpona poskytovatele, je automaticky přidána. Neodpovídající modely vrátí „400“.### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -594,171 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Přednost:**Specifické pro klíč → Specifické pro kombinované → Specifické pro poskytovatele → Globální → Prostředí.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Vrátí modely seskupené podle poskytovatele s typy (`chat`, `embedding`, `image`).### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Synchronizujte poskytovatele, komba a nastavení napříč zařízeními
-- Automatická synchronizace na pozadí s časovým limitem + rychlé selhání
-- V produkci preferujte `BASE_URL`/`CLOUD_URL` na straně serveru### Cloudflare Quick Tunnel
+### Cloud Sync
-- K dispozici v**Dashboard → Endpoints**pro Docker a další samostatně hostovaná nasazení
-- Vytvoří dočasnou adresu URL `https://*.trycloudflare.com`, která přesměruje na váš aktuální koncový bod `/v1` kompatibilní s OpenAI
-- Nejprve povolte instalaci `cloudflared` pouze v případě potřeby; pozdější restartování znovu použije stejný spravovaný binární soubor
-- Rychlé tunely se po restartu OmniRoute nebo kontejneru automaticky neobnoví; v případě potřeby je znovu povolte z palubní desky
-- Adresy URL tunelu jsou pomíjivé a mění se při každém zastavení/spuštění tunelu
-- Spravované rychlé tunely ve výchozím nastavení pro přenos HTTP/2, aby se zabránilo hlučným varováním vyrovnávací paměti QUIC UDP v omezených kontejnerech
-- Pokud chcete volbu řízeného přenosu přepsat, nastavte `CLOUDFLARED_PROTOCOL=quic` nebo `auto`
-- Nastavte `CLOUDFLARED_BIN`, pokud dáváte přednost použití předinstalovaného binárního souboru `cloudflared` namísto spravovaného stahování### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Sémantická mezipaměť**– Automatické ukládání do mezipaměti bez streamování, teplota=0 odpovědí (obejít s `X-OmniRoute-No-Cache: true`)
-–**Request Idempotency**– Deduplikuje požadavky do 5 s pomocí hlavičky „Idempotency-Key“ nebo „X-Request-Id“ -**Sledování pokroku**— Přihlaste se k událostem SSE `event: progress` prostřednictvím záhlaví `X-OmniRoute-Progress: true`---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Přístup přes**Dashboard → Translator**. Laďte a vizualizujte, jak OmniRoute překládá požadavky API mezi poskytovateli.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Režim | Účel |
-| -------------------- | ------------------------------------------------------------------------------------- |
-| **Hřiště** | Vyberte zdrojové/cílové formáty, vložte požadavek a okamžitě uvidíte přeložený výstup |
-| **Chat Tester** | Odesílejte zprávy živého chatu přes proxy a prohlédněte si celý cyklus žádost/odpověď |
-| **Zkušební stolice** | Spusťte dávkové testy ve více kombinacích formátů, abyste ověřili správnost překladu |
-| **Živý monitor** | Sledujte překlady v reálném čase, jak požadavky proudí přes proxy |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Případy použití:**
+**Use cases:**
-- Odlaďte, proč konkrétní kombinace klient/poskytovatel selhává
-- Ověřte, že se značky myšlení, volání nástrojů a systémové výzvy překládají správně
-- Porovnejte rozdíly mezi formáty OpenAI, Claude, Gemini a Responses API---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Konfigurujte přes**Dashboard → Nastavení → Směrování**.
+Configure via **Dashboard → Settings → Routing**.
-| Strategie | Popis |
-| ---------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Vyplňte první** | Používá účty v pořadí priority – primární účet zpracovává všechny požadavky, dokud není dostupný |
-| **Round Robin** | Prochází všechny účty s nastavitelným limitem (výchozí: 3 volání na účet) |
-| **P2C (síla dvou možností)** | Vybere 2 náhodné účty a cesty ke zdravějšímu — vyrovnává zátěž s vědomím zdraví |
-| **Náhodné** | Náhodně vybere účet pro každý požadavek pomocí Fisher-Yates shuffle |
-| **Nejméně používané** | Směrování na účet s nejstarším časovým razítkem `lastUsedAt`, distribuce provozu rovnoměrně |
-| **Costově optimalizované** | Směrování na účet s nejnižší hodnotou priority, optimalizace pro poskytovatele s nejnižšími náklady | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Pro externí afinitu relace (například agenti Claude Code/Codex za reverzními proxy) odešlete:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute také přijímá `x_session_id` a vrací efektivní klíč relace v `X-OmniRoute-Session-Id`.
+If you use Nginx and send underscore-form headers, enable:
-Pokud používáte Nginx a odesíláte záhlaví formuláře podtržení, povolte:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Vytvořte vzory zástupných znaků pro přemapování názvů modelů:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Zástupné znaky podporují `*` (jakékoli znaky) a `?` (jeden znak).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Definujte globální záložní řetězce, které platí pro všechny požadavky:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Konfigurujte pomocí**Dashboard → Settings → Resilience**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute implementuje odolnost na úrovni poskytovatele se čtyřmi komponentami:
+OmniRoute implements provider-level resilience with four components:
-1.**Profily poskytovatelů**— Konfigurace podle poskytovatele pro:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Práh selhání (kolik selhání před otevřením)
-- Doba vychladnutí
-- Citlivost detekce rychlostního limitu
-- Exponenciální backoff parametry
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Upravitelné limity rychlosti**— Výchozí nastavení na úrovni systému konfigurovatelné na řídicím panelu: -**Požadavky za minutu (RPM)**– Maximální počet požadavků za minutu na účet -**Min Time Between Requests**— Minimální prodleva v milisekundách mezi požadavky -**Max Concurrent Requests**– Maximální počet souběžných požadavků na účet
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Klikněte na**Upravit**pro úpravu a poté na**Uložit**nebo**Zrušit**. Hodnoty přetrvávají prostřednictvím rozhraní API pro odolnost.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Circuit Breaker**— Sleduje poruchy na poskytovatele a automaticky otevře okruh, když je dosaženo prahové hodnoty: -**UZAVŘENO**(Zdravé) – Požadavky běží normálně -**OPEN**— Poskytovatel je po opakovaných selháních dočasně zablokován -**HALF_OPEN**— Testování, zda se poskytovatel zotavil
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Policies & Locked Identifiers**– Zobrazuje stav jističe a uzamčené identifikátory s možností vynuceného odemknutí.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Automatická detekce limitu rychlosti**— Monitoruje hlavičky `429` a `Retry-After`, aby se proaktivně zabránilo překročení limitů sazeb poskytovatele.
-
-**Tip pro profesionály:**Když se poskytovatel zotaví z výpadku, použijte tlačítko**Resetovat vše**k vymazání všech jističů a ochlazení.---
+---
### Database Export / Import
-Spravujte zálohy databáze v**Hlavní panel → Nastavení → Systém a úložiště**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Akce | Popis |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Export databáze** | Stáhne aktuální databázi SQLite jako soubor `.sqlite` |
-| **Exportovat vše (.tar.gz)** | Stáhne úplný záložní archiv včetně: databáze, nastavení, kombinací, připojení poskytovatele (bez přihlašovacích údajů), metadat klíče API |
-| **Importovat databázi** | Nahrajte soubor `.sqlite`, který nahradí aktuální databázi. Předimportní záloha se vytvoří automaticky, pokud není `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Ověření importu:**U importovaného souboru je ověřena integrita (kontrola SQLite pragma), požadované tabulky (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) a velikost (max 100 MB).
+**Use Cases:**
-**Případy použití:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Migrujte OmniRoute mezi počítači
-- Vytvářejte externí zálohy pro obnovu po havárii
-- Sdílejte konfigurace mezi členy týmu (exportovat vše → sdílet archiv)---
+---
### Settings Dashboard
-Stránka nastavení je uspořádána do 6 záložek pro snadnou navigaci:
+The settings page is organized into 6 tabs for easy navigation:
-| Tab | Obsah |
-| --------------- | ---------------------------------------------------------------------------------------------- |
-|**Obecné**| Nástroje systémového úložiště, nastavení vzhledu, ovládací prvky motivu a viditelnost postranního panelu pro jednotlivé položky |
-|**Zabezpečení**| Nastavení přihlášení/hesla, řízení přístupu k IP, ověření API pro `/modely` a blokování poskytovatelů |
-|**Směrování**| Globální strategie směrování (6 možností), zástupné modelové aliasy, záložní řetězce, výchozí kombinace |
-|**Odolnost**| Profily poskytovatelů, upravitelné limity sazeb, stav jističe, zásady a uzamčené identifikátory |
-|**AI**| Konfigurace rozpočtu myšlení, okamžité vložení globálního systému, statistiky rychlé vyrovnávací paměti |
-|**Pokročilé**| Globální konfigurace proxy (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Přístup přes**Dashboard → Náklady**.
+Access via **Dashboard → Costs**.
-| Tab | Účel |
+| Tab | Purpose |
| ----------- | ---------------------------------------------------------------------------------------- |
-|**Rozpočet**| Nastavte limity výdajů na klíč API s denními/týdenními/měsíčními rozpočty a sledováním v reálném čase |
-|**Cena**| Prohlížejte a upravujte položky cen modelu – cena za 1 000 vstupních/výstupních tokenů na poskytovatele |```bash
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -766,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Sledování nákladů:**Každý požadavek zaznamenává využití tokenu a vypočítává náklady pomocí cenové tabulky. Prohlédněte si rozdělení v**Hlavním panelu → Využití**podle poskytovatele, modelu a klíče API.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute podporuje přepis zvuku prostřednictvím koncového bodu kompatibilního s OpenAI:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Dostupní poskytovatelé:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Podporované zvukové formáty: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.---
+---
### Combo Balancing Strategies
-Nakonfigurujte vyvážení jednotlivých kombinací v**Dashboard → Combos → Create/Edit → Strategy**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Strategie | Popis |
-| ------------------- | ------------------------------------------------------------------------- |
-|**Round-Robin**| Postupně otáčí modely |
-|**Priorita**| Vždy zkouší první model; vrátí se pouze při chybě |
-|**Náhodné**| Vybere náhodný model z kombinace pro každý požadavek |
-|**Vážený**| Trasy proporcionálně na základě přiřazených vah na model |
-|**Nejméně používané**| Směruje k modelu s nejmenším počtem nedávných požadavků (používá kombinované metriky) |
-|**Nákladově optimalizované**| Trasy k nejlevnějšímu dostupnému modelu (používá cenovou tabulku) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Globální výchozí combo lze nastavit v**Dashboard → Settings → Routing → Combo Defaults**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Přístup přes**Dashboard → Zdraví**. Přehled stavu systému v reálném čase se 6 kartami:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Karta | Co ukazuje |
-| ---------------------- | ----------------------------------------------------------- |
-|**Stav systému**| Uptime, verze, využití paměti, datový adresář |
-|**Zdraví poskytovatele**| Stav jističe podle poskytovatele (zavřeno/otevřeno/polootevřeno) |
-|**Limity sazeb**| Aktivní cooldowny rychlostního limitu na účet se zbývajícím časem |
-|**Aktivní uzamčení**| Poskytovatelé dočasně blokováni zásadou uzamčení |
-|**Signature Cache**| Statistiky deduplikační mezipaměti (aktivní klíče, četnost zásahů) |
-|**Latenční telemetrie**| p50/p95/p99 agregace latence na poskytovatele |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Tip pro profesionály:**Stránka Zdraví se automaticky obnovuje každých 10 sekund. Pomocí karty jističe zjistěte, u kterých poskytovatelů dochází k problémům.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute je k dispozici jako nativní desktopová aplikace pro Windows, macOS a Linux.### Instalace
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Instalace
```bash
# From the electron directory:
@@ -834,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -846,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Výstup → `elektron/dist-elektron/`### Key Features
+Output → `electron/dist-electron/`
-| Funkce | Popis |
-| ----------------------------- | ------------------------------------------------------------------- | ------------------------- |
-| **Připravenost serveru** | Před zobrazením okna dotazuje server (bez prázdné obrazovky) |
-| **Systémová lišta** | Minimalizovat do zásobníku, změnit port, opustit nabídku zásobníku |
-| **Správa portů** | Změňte port serveru ze zásobníku (automatické restartování serveru) |
-| **Zásady zabezpečení obsahu** | Omezující CSP prostřednictvím záhlaví relací |
-| **Jedna instance** | Najednou může běžet pouze jedna instance aplikace |
-| **Režim offline** | Přibalený server Next.js funguje bez internetu | ### Environment Variables |
+### Key Features
-| Proměnná | Výchozí | Popis |
-| --------------------- | ------- | --------------------------------- |
-| `OMNIROUTE_PORT` | "20128" | Port serveru |
-| `OMNIROUTE_MEMORY_MB` | "512" | Limit haldy Node.js (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Úplná dokumentace: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/da/README.md b/docs/i18n/da/README.md
index eab1391fa4..b67ff71fe6 100644
--- a/docs/i18n/da/README.md
+++ b/docs/i18n/da/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/da/docs/USER_GUIDE.md b/docs/i18n/da/docs/USER_GUIDE.md
index 63a424c639..4b94422a93 100644
--- a/docs/i18n/da/docs/USER_GUIDE.md
+++ b/docs/i18n/da/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Komplet guide til konfiguration af udbydere, oprettelse af kombinationer, integration af CLI-værktøjer og implementering af OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Prissætning på et øjeblik](#-pricing-at-a-glance)
+- [Pricing at a Glance](#-pricing-at-a-glance)
- [Use Cases](#-use-cases)
- [Provider Setup](#-provider-setup)
-- [CLI-integration](#-cli-integration)
-- [Implementering](#-implementering)
-- [Tilgængelige modeller](#-tilgængelige-modeller)
-- [Avancerede funktioner](#-avancerede-funktioner)---
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 Pricing at a Glance
-| Tier | Udbyder | Omkostninger | Kvote nulstilling | 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** | DeepSeek | Betal pr. brug | Ingen | Billig ræsonnement |
-| | Groq | Betal pr. brug | Ingen | Ultrahurtig slutning |
-| | xAI (Grok) | Betal pr. brug | Ingen | Grok 4 ræsonnement |
-| | Mistral | Betal pr. brug | Ingen | EU-hostede modeller |
-| | Forvirring | Betal pr. brug | Ingen | Søgeforøget |
-| | Sammen AI | Betal pr. brug | Ingen | Open source-modeller |
-| | Fyrværkeri AI | Betal pr. brug | Ingen | Fast FLUX billeder |
-| | Cerebras | Betal pr. brug | Ingen | Wafer-skala hastighed |
-| | Sammenhæng | Betal pr. brug | Ingen | Kommando R+ RAG |
-| | NVIDIA NIM | Betal pr. brug | Ingen | Virksomhedsmodeller |
-| **💰 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** | Qoder | $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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Pro-tip:**Start med Gemini CLI (180K gratis/måned) + Qoder (ubegrænset gratis) combo = $0 omkostninger!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Problem:**Kvoten udløber ubrugt, satsgrænser under tung kodning```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Problem:**Har ikke råd til abonnementer, har brug for pålidelig AI-kodning```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Problem:**Deadlines, har ikke råd til nedetid```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Problem:**Har brug for AI-assistent i beskedapps, helt gratis```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**Prof tip:**Brug Opus til komplekse opgaver, Sonnet for hurtighed. OmniRoute sporer kvote pr. model!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Bedste værdi:**Kæmpe gratis niveau! Brug dette før betalte niveauer.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### 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: `din-nøgle`
+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` —**Prof tip:**Kodningsplan tilbyder 3× kvote til 1/7 pris! Nulstil dagligt 10:00.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Tilmeld dig: [MiniMax](https://www.minimax.io/)
-2. Hent API-nøgle → Dashboard → Tilføj API-nøgle
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Brug:**`minimax/MiniMax-M2.1` —**Pro-tip:**Billigste mulighed for lang sammenhæng (1M tokens)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Abonner: [Moonshot AI](https://platform.moonshot.ai/)
-2. Hent API-nøgle → Dashboard → Tilføj API-nøgle
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Brug:**`kimi/kimi-nyeste` —**Prof tip:**Fast $9/måned for 10M tokens = $0,90/1M effektive omkostninger!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Rediger `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Rediger `~/.claude/config.json`:```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Rediger `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Eller brug Dashboard:**CLI Tools → OpenClaw → Auto-config### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI'en indlæser automatisk `.env` fra `~/.omniroute/.env` eller `./.env`.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-For servere med begrænset RAM skal du bruge muligheden for hukommelsesbegrænsning:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Opret `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,12 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-For værtsintegreret tilstand med CLI-binære filer, se Docker-sektionen i hoveddokumenterne.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Void Linux-brugere kan pakke og installere OmniRoute naturligt ved hjælp af `xbps-src` krydskompileringsramme. Dette automatiserer Node.js standalone build sammen med de nødvendige "better-sqlite3" native bindinger.
+### Void Linux (xbps-src)
-
-Se xbps-src skabelon```bash
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -408,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -475,60 +516,63 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Variabel | Standard | Beskrivelse |
-| ----------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signeringshemmelighed (**ændring i produktion**) |
-| `INITIAL_PASSWORD` | `123456` | Første login-adgangskode |
-| `DATA_DIR` | `~/.omniroute` | Datamappe (db, forbrug, logfiler) |
-| `PORT` | ramme standard | Serviceport ('20128' i eksempler) |
-| `HOSTNAVN` | ramme standard | Bind vært (Docker er som standard `0.0.0.0`) |
-| `NODE_ENV` | runtime default | Indstil 'produktion' til implementering |
-| `BASE_URL` | `http://localhost:20128` | Intern basis-URL på serversiden |
-| `CLOUD_URL` | `https://omniroute.dev` | Base URL for slutpunkt for skysynkronisering |
-| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC-hemmelighed for genererede API-nøgler |
-| `REQUIRE_API_KEY` | 'falsk' | Gennemtving Bearer API-nøgle på `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | 'falsk' | Tillad Api Manager at kopiere hele API-nøgler efter behov |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side opdateringskadence for cachelagrede Provider Limits-data; UI-opdateringsknapper udløser stadig manuel synkronisering |
-| `DISABLE_SQLITE_AUTO_BACKUP` | 'falsk' | Deaktiver automatiske SQLite-snapshots før skrivning/import/gendannelse; Manuelle sikkerhedskopier virker stadig |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | 'falsk' | Tving 'Sikker' auth-cookie (bag HTTPS omvendt proxy) |
-| `CLOUDFLARED_BIN` | frakoblet | Brug en eksisterende `cloudflared` binær i stedet for administreret download |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Transport til administrerede hurtige tunneler (`http2`, `quic` eller `auto`) |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap-grænse i MB |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | Maks. prompt-cache-indgange |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Maksimal semantisk cache-indgange |For den fulde reference til miljøvariablen, se [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Se alle tilgængelige modeller
+
+View all available models
-**Claude Code (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**– GRATIS: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**– 0,6 USD/1 mio.: `glm/glm-4,7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— 0,2 USD/1 mio.: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— GRATIS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— GRATIS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— GRATIS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
@@ -538,7 +582,7 @@ vlicense LICENSE
**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Forvirring (`pplx/`)**: `pplx/ekkolod-pro`, `pplx/ekkolod`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
@@ -548,7 +592,9 @@ vlicense LICENSE
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -556,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Tilføj ethvert model-id til enhver udbyder uden at vente på en appopdatering:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -564,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Eller brug Dashboard:**Udbydere → [Udbyder] → Brugerdefinerede modeller**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Bemærkninger:
+Notes:
-- OpenRouter og OpenAI/Anthropic-kompatible udbydere administreres kun fra**Tilgængelige modeller**. Manuel tilføjelse, import og automatisk synkronisering lander alle på den samme tilgængelige modelliste, så der er ingen separat sektion med tilpassede modeller for disse udbydere.
-- Sektionen**Tilpassede modeller**er beregnet til udbydere, der ikke eksponerer administrerede tilgængelige modeller-importer.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Rut anmodninger direkte til en specifik udbyder med modelvalidering:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Udbyderpræfikset tilføjes automatisk, hvis det mangler. Umatchede modeller returnerer '400'.### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -594,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Forrang:**Nøglespecifik → Kombinationsspecifik → Udbyderspecifik → Global → Miljø.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Returnerer modeller grupperet efter udbyder med typer ("chat", "indlejring", "billede").### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Synkroniser udbydere, kombinationer og indstillinger på tværs af enheder
-- Automatisk baggrundssynkronisering med timeout + fejl-hurtig
-- Foretrække server-side `BASE_URL`/`CLOUD_URL` i produktion### Cloudflare Quick Tunnel
+### Cloud Sync
-- Tilgængelig i**Dashboard → Endpoints**til Docker og andre selv-hostede implementeringer
-- Opretter en midlertidig `https://*.trycloudflare.com` URL, der videresender til dit nuværende OpenAI-kompatible `/v1` slutpunkt
-- Aktiver først installationer "cloudflared", når det er nødvendigt; senere genstarter genbrug den samme administrerede binære
-- Hurtige tunneler gendannes ikke automatisk efter en OmniRoute- eller containergenstart; genaktiver dem fra dashboardet, når det er nødvendigt
-- Tunnel-URL'er er flygtige og ændres hver gang du stopper/starter tunnelen
-- Managed Quick Tunnels er som standard HTTP/2-transport for at undgå støjende QUIC UDP-bufferadvarsler i begrænsede containere
-- Indstil `CLOUDFLARED_PROTOCOL=quic` eller `auto`, hvis du vil tilsidesætte det administrerede transportvalg
-- Indstil "CLOUDFLARED_BIN", hvis du foretrækker at bruge en forudinstalleret "cloudflared" binær i stedet for den administrerede download### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Semantisk cache**— Automatisk cache, ikke-streaming, temperatur=0 svar (omgå med `X-OmniRoute-No-Cache: true`) -**Request Idempotency**— Deduplikerer anmodninger inden for 5 sekunder via "Idempotency-Key" eller "X-Request-Id" header -**Progress Tracking**— Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Adgang via**Dashboard → Oversætter**. Fejlfind og visualiser, hvordan OmniRoute oversætter API-anmodninger mellem udbydere.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Tilstand | Formål |
-| ---------------- | --------------------------------------------------------------------------------------------- |
-| **Legeplads** | Vælg kilde-/målformater, indsæt en anmodning, og se det oversatte output med det samme |
-| **Chattester** | Send live chatbeskeder gennem proxyen og inspicer den fulde anmodning/svar-cyklus |
-| **Testbænk** | Kør batchtest på tværs af flere formatkombinationer for at bekræfte oversættelsens korrekthed |
-| **Live Monitor** | Se oversættelser i realtid, mens anmodninger strømmer gennem proxyen |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Brugstilfælde:**
+**Use cases:**
-- Fejlfinding af, hvorfor en specifik klient/udbyder-kombination mislykkes
-- Bekræft, at tankemærker, værktøjsopkald og systembeskeder oversættes korrekt
-- Sammenlign formatforskelle mellem OpenAI, Claude, Gemini og Responses API-formater---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Konfigurer via**Dashboard → Indstillinger → Routing**.
+Configure via **Dashboard → Settings → Routing**.
-| Strategi | Beskrivelse |
-| ------------------------------ | --------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Fyld først** | Bruger konti i prioriteret rækkefølge — primær konto håndterer alle anmodninger, indtil de ikke er tilgængelige |
-| **Round Robin** | Går gennem alle konti med en konfigurerbar sticky-grænse (standard: 3 opkald pr. konto) |
-| **P2C (Power of Two Choices)** | Vælger 2 tilfældige konti og ruter til den sundere — balancerer belastning med bevidsthed om sundhed |
-| **Tilfældig** | Vælger tilfældigt en konto for hver anmodning ved hjælp af Fisher-Yates shuffle |
-| **Mindst brugt** | Ruter til kontoen med det ældste `lastUsedAt`-tidsstempel, der fordeler trafikken jævnt |
-| **Omkostningsoptimeret** | Ruter til kontoen med den laveste prioritetsværdi, optimerer til udbydere med laveste omkostninger | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-For ekstern sessionsaffinitet (for eksempel Claude Code/Codex-agenter bag omvendte proxyer), send:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute accepterer også `x_session_id` og returnerer den effektive sessionsnøgle i `X-OmniRoute-Session-Id`.
+If you use Nginx and send underscore-form headers, enable:
-Hvis du bruger Nginx og sender overskrifter i understregningsform, skal du aktivere:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Opret jokertegnsmønstre for at omdanne modelnavne:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Jokertegn understøtter `*` (alle tegn) og `?` (enkelt tegn).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Definer globale reservekæder, der gælder på tværs af alle anmodninger:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Konfigurer via**Dashboard → Indstillinger → Resiliens**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute implementerer modstandsdygtighed på udbyderniveau med fire komponenter:
+OmniRoute implements provider-level resilience with four components:
-1.**Udbyderprofiler**— Konfiguration pr. udbyder for:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Fejltærskel (hvor mange fejl før åbning)
-- Nedkølingsvarighed
-- Følsomhed for registrering af hastighedsgrænse
-- Eksponentielle backoff-parametre
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Redigerbare hastighedsgrænser**— Standardindstillinger på systemniveau, der kan konfigureres i dashboardet: -**Requests Per Minute (RPM)**— Maksimale anmodninger pr. minut pr. konto -**Min Time Between Requests**— Minimumsafstand i millisekunder mellem anmodninger -**Maksimal samtidige anmodninger**— Maksimalt antal samtidige anmodninger pr. konto
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Klik på**Rediger**for at ændre, og klik derefter på**Gem**eller**Annuller**. Værdier bevarer via resilience API.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Circuit Breaker**— Sporer fejl pr. udbyder og åbner automatisk kredsløbet, når en tærskel er nået: -**LUKKET**(Sund) — Anmodninger flyder normalt -**ÅBEN**— Udbyderen er midlertidigt blokeret efter gentagne fejl -**HALF_OPEN**— Tester, om udbyderen er genoprettet
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Politik og låste identifikatorer**— Viser strømafbryderstatus og låste identifikatorer med tvangsoplåsningsfunktion.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Rate Limit Auto-Detection**— Overvåger "429" og "Retry-After"-headere for proaktivt at undgå at ramme udbyderens takstgrænser.
-
-**Prof tip:**Brug knappen**Nulstil alle**til at rydde alle strømafbrydere og nedkøling, når en udbyder kommer sig efter en fejl.---
+---
### Database Export / Import
-Administrer databasesikkerhedskopier i**Dashboard → Indstillinger → System og lager**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Handling | Beskrivelse |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Eksporter database** | Downloader den aktuelle SQLite-database som en `.sqlite`-fil |
-| **Eksporter alle (.tar.gz)** | Downloader et komplet backup-arkiv inklusive: database, indstillinger, kombinationer, udbyderforbindelser (ingen legitimationsoplysninger), API-nøglemetadata |
-| **Importer database** | Upload en `.sqlite`-fil for at erstatte den aktuelle database. En forhåndsimport-sikkerhedskopi oprettes automatisk, medmindre `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Importvalidering:**Den importerede fil er valideret for integritet (SQLite pragmatjek), påkrævede tabeller (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) og størrelse (maks. 100MB).
+**Use Cases:**
-**Brugstilfælde:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Migrer OmniRoute mellem maskiner
-- Opret eksterne sikkerhedskopier til katastrofegendannelse
-- Del konfigurationer mellem teammedlemmer (eksporter alle → del arkiv)---
+---
### Settings Dashboard
-Indstillingssiden er organiseret i 6 faner for nem navigation:
+The settings page is organized into 6 tabs for easy navigation:
-| Faneblad | Indhold |
-| -------------- | ---------------------------------------------------------------------------------------------------- |
-|**Generelt**| Systemlagerværktøjer, udseendeindstillinger, temakontroller og synlighed i sidebjælken pr. element |
-|**Sikkerhed**| Indstillinger for login/adgangskode, IP-adgangskontrol, API-godkendelse for `/modeller` og udbyderblokering |
-|**Routing**| Global routingstrategi (6 muligheder), jokertegn-modelaliaser, reservekæder, combo-standarder |
-|**Resiliens**| Udbyderprofiler, redigerbare hastighedsgrænser, strømafbryderstatus, politikker og låste identifikatorer |
-|**AI**| Tænkende budgetkonfiguration, global systemprompt-injektion, prompt-cache-statistik |
-|**Avanceret**| Global proxy-konfiguration (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Adgang via**Dashboard → Omkostninger**.
+Access via **Dashboard → Costs**.
-| Faneblad | Formål |
-| ----------- | ------------------------------------------------------------------------------------------ |
-|**Budget**| Indstil forbrugsgrænser pr. API-nøgle med daglige/ugentlige/månedlige budgetter og realtidssporing |
-|**Priser**| Se og rediger modelprisangivelser — pris pr. 1K input/output-tokens pr. udbyder |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -765,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Omkostningssporing:**Hver anmodning logger tokenbrug og beregner omkostninger ved hjælp af pristabellen. Se opdelinger i**Dashboard → Brug**efter udbyder, model og API-nøgle.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute understøtter lydtransskription via det OpenAI-kompatible slutpunkt:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Tilgængelige udbydere:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Understøttede lydformater: "mp3", "wav", "m4a", "flac", "ogg", "webm".---
+---
### Combo Balancing Strategies
-Konfigurer balancering pr. kombination i**Dashboard → Combos → Opret/Rediger → Strategi**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Strategi | Beskrivelse |
-| ------------------ | -------------------------------------------------------------------------- |
-|**Round-Robin**| Roterer sekventielt gennem modeller |
-|**Prioritet**| Prøver altid den første model; falder kun tilbage på fejl |
-|**Tilfældig**| Vælger en tilfældig model fra kombinationen for hver anmodning |
-|**Vægtet**| Ruter proportionalt baseret på tildelte vægte pr. model |
-|**Mindst brugt**| Ruter til modellen med de færreste seneste anmodninger (bruger combo-metrics) |
-|**Omkostningsoptimeret**| Ruter til den billigste tilgængelige model (bruger pristabel) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Globale kombinationsstandarder kan indstilles i**Dashboard → Indstillinger → Routing → Combo-standarder**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Adgang via**Dashboard → Health**. Oversigt over systemets tilstand i realtid med 6 kort:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Kort | Hvad det viser |
-| ---------------------- | ------------------------------------------------------------------ |
-|**Systemstatus**| Oppetid, version, hukommelsesforbrug, datakatalog |
-|**Udbydersundhed**| Per-leverandør afbrydertilstand (Lukket/Åben/Halv-Åben) |
-|**Satsgrænser**| Aktive nedkølingsgrænser pr. konto med resterende tid |
-|**Aktive lockouts**| Udbydere midlertidigt blokeret af lockout-politikken |
-|**Signatur Cache**| Deduplikeringscache-statistikker (aktive nøgler, hitrate) |
-|**Latency Telemetri**| p50/p95/p99 latenssammenlægning pr. udbyder |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Prof tip:**Sundhedssiden opdateres automatisk hvert 10. sekund. Brug afbryderkortet til at identificere, hvilke udbydere der oplever problemer.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute er tilgængelig som en indbygget desktopapplikation til Windows, macOS og Linux.### Installer
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Installer
```bash
# From the electron directory:
@@ -833,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -845,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Output → `elektron/dist-elektron/`### Key Features
+Output → `electron/dist-electron/`
-| Funktion | Beskrivelse |
-| ----------------------------- | --------------------------------------------------------- | ------------------------- |
-| **Serverklarhed** | Afstemningsserver før vinduet vises (ingen blank skærm) |
-| **Systembakke** | Minimer til bakke, skift port, luk fra bakkemenu |
-| **Port Management** | Skift serverport fra bakke (automatisk genstarter server) |
-| **Indholdssikkerhedspolitik** | Restriktiv CSP via sessionsoverskrifter |
-| **Enkelt forekomst** | Kun én app-forekomst kan køre ad gangen |
-| **Offlinetilstand** | Bundet Next.js server fungerer uden internet | ### Environment Variables |
+### Key Features
-| Variabel | Standard | Beskrivelse |
-| --------------------- | -------- | --------------------------------- |
-| `OMNIROUTE_PORT` | `20128` | Serverport |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap-grænse (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Fuld dokumentation: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/de/README.md b/docs/i18n/de/README.md
index 0b2818ee98..e57ec0d4c6 100644
--- a/docs/i18n/de/README.md
+++ b/docs/i18n/de/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/de/docs/USER_GUIDE.md b/docs/i18n/de/docs/USER_GUIDE.md
index 45bfe29f67..be4f719ce5 100644
--- a/docs/i18n/de/docs/USER_GUIDE.md
+++ b/docs/i18n/de/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Vollständiger Leitfaden zum Konfigurieren von Anbietern, Erstellen von Kombinationen, Integrieren von CLI-Tools und Bereitstellen von OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Preise auf einen Blick](#-pricing-at-a-glance)
-- [Anwendungsfälle](#-use-cases)
-- [Anbieter-Setup](#-provider-setup)
-- [CLI-Integration](#-cli-integration)
-- [Bereitstellung](#-deployment)
-- [Verfügbare Modelle](#-available-models)
-- [Erweiterte Funktionen](#-advanced-features)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 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** | DeepSeek | Bezahlung pro Nutzung | Keine | Billiges Denken |
-| | Groq | Bezahlung pro Nutzung | Keine | Ultraschnelle Inferenz |
-| | xAI (Grok) | Bezahlung pro Nutzung | Keine | Grok 4 Argumentation |
-| | Mistral | Bezahlung pro Nutzung | Keine | In der EU gehostete Modelle |
-| | Ratlosigkeit | Bezahlung pro Nutzung | Keine | Sucherweitert |
-| | Zusammen KI | Bezahlung pro Nutzung | Keine | Open-Source-Modelle |
-| | Feuerwerk KI | Bezahlung pro Nutzung | Keine | Schnelle FLUX-Bilder |
-| | Großhirn | Bezahlung pro Nutzung | Keine | Geschwindigkeit im Wafermaßstab |
-| | Kohärent | Bezahlung pro Nutzung | Keine | Befehl R+ RAG |
-| | NVIDIA NIM | Bezahlung pro Nutzung | Keine | Unternehmensmodelle |
-| **💰 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** | Qoder | $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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Profi-Tipp:**Beginnen Sie mit der Kombination Gemini CLI (180.000 kostenlos/Monat) + Qoder (unbegrenzt kostenlos) = 0 $ Kosten!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Problem:**Kontingent läuft ungenutzt ab, Ratenbegrenzungen bei intensiver Codierung```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Problem:**Ich kann mir keine Abonnements leisten und brauche zuverlässige KI-Codierung```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Problem:**Fristen, ich kann mir Ausfallzeiten nicht leisten```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Problem:**Benötigen Sie einen KI-Assistenten in Messaging-Apps, völlig kostenlos```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ 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!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Bester Wert:**Riesiges kostenloses Kontingent! Verwenden Sie dies vor kostenpflichtigen Stufen.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### GLM-4.7 (Daily reset, $0.6/1M)
-1. Registrieren Sie sich: [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`
-**Verwenden Sie:**„glm/glm-4.7“ –**Profi-Tipp:**Coding Plan bietet 3× Kontingent zu 1/7 Kosten! Täglich um 10:00 Uhr zurückgesetzt.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Registrieren Sie sich: [MiniMax](https://www.minimax.io/)
-2. API-Schlüssel abrufen → Dashboard → API-Schlüssel hinzufügen
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Verwenden Sie:**„minimax/MiniMax-M2.1“ –**Profi-Tipp:**Günstigste Option für langen Kontext (1 Mio. Token)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Abonnieren: [Moonshot AI](https://platform.moonshot.ai/)
-2. API-Schlüssel abrufen → Dashboard → API-Schlüssel hinzufügen
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Verwenden Sie:**„kimi/kimi-latest“ –**Profi-Tipp:**Feste 9 $/Monat für 10 Mio. Token = 0,90 $/1 Mio. effektive Kosten!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Bearbeiten Sie „~/.claude/config.json“:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Bearbeiten Sie „~/.claude/config.json“:```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Bearbeiten Sie „~/.openclaw/openclaw.json“:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Oder verwenden Sie Dashboard:**CLI-Tools → OpenClaw → Auto-config### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-Die CLI lädt „.env“ automatisch von „~/.omniroute/.env“ oder „./.env“.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-Verwenden Sie für Server mit begrenztem RAM die Option „Speicherlimit“:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Erstellen Sie „ecosystem.config.js“:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,12 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-Informationen zum hostintegrierten Modus mit CLI-Binärdateien finden Sie im Abschnitt „Docker“ in den Hauptdokumenten.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Void-Linux-Benutzer können OmniRoute mithilfe des Cross-Compilation-Frameworks „xbps-src“ nativ verpacken und installieren. Dadurch wird der eigenständige Node.js-Build zusammen mit den erforderlichen nativen „better-sqlite3“-Bindungen automatisiert.
+### Void Linux (xbps-src)
-
-Xbps-src-Vorlage anzeigen
```bash
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -408,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -475,60 +516,63 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Variable | Standard | Beschreibung |
-| --------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT-Signaturgeheimnis (**Änderung in der Produktion**) |
-| `INITIAL_PASSWORD` | `123456` | Erstes Login-Passwort |
-| `DATA_DIR` | `~/.omniroute` | Datenverzeichnis (Datenbank, Nutzung, Protokolle) |
-| „HAFEN“ | Framework-Standard | Service-Port (in Beispielen „20128“) |
-| `HOSTNAME` | Framework-Standard | Host binden (Docker ist standardmäßig „0.0.0.0“) |
-| `NODE_ENV` | Laufzeitstandard | Legen Sie „Produktion“ für die Bereitstellung | fest
-| `BASE_URL` | `http://localhost:20128` | Serverseitige interne Basis-URL |
-| „CLOUD_URL“ | `https://omniroute.dev` | Basis-URL des Cloud-Synchronisierungsendpunkts |
-| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC-Geheimnis für generierte API-Schlüssel |
-| `REQUIRE_API_KEY` | „falsch“ | Bearer-API-Schlüssel auf „/v1/*“ erzwingen |
-| `ALLOW_API_KEY_REVEAL` | „falsch“ | Api Manager erlauben, bei Bedarf vollständige API-Schlüssel zu kopieren |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Serverseitige Aktualisierungsfrequenz für zwischengespeicherte Provider-Limit-Daten; Schaltflächen zum Aktualisieren der Benutzeroberfläche lösen weiterhin eine manuelle Synchronisierung aus |
-| `DISABLE_SQLITE_AUTO_BACKUP` | „falsch“ | Deaktivieren Sie automatische SQLite-Snapshots vor dem Schreiben/Importieren/Wiederherstellen. Manuelle Backups funktionieren weiterhin |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | „falsch“ | „Sicheres“ Authentifizierungs-Cookie erzwingen (hinter HTTPS-Reverse-Proxy) |
-| `CLOUDFLARED_BIN` | nicht gesetzt | Verwenden Sie eine vorhandene „Cloudflared“-Binärdatei anstelle eines verwalteten Downloads |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Transport für verwaltete Quick Tunnels („http2“, „quic“ oder „auto“) |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js-Heap-Limit in MB |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | Maximale Einträge im Eingabeaufforderungscache |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max. Einträge im semantischen Cache |Die vollständige Umgebungsvariablenreferenz finden Sie in der [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Alle verfügbaren Modelle anzeigen
+
+View all available models
-**Claude Code (`cc/`)**– Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**– Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**– KOSTENLOS: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**– 0,6 $/1 Mio.: `glm/glm-4,7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— 0,2 $/1 Mio.: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**– KOSTENLOS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— KOSTENLOS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— KOSTENLOS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
@@ -542,13 +586,15 @@ vlicense LICENSE
**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**Feuerwerks-KI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**Großhirn (`cerebras/`)**: `cerebras/llama-3.3-70b`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -556,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Fügen Sie jedem Anbieter eine beliebige Modell-ID hinzu, ohne auf ein App-Update warten zu müssen:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -564,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Oder verwenden Sie das Dashboard:**Anbieter → [Anbieter] → Benutzerdefinierte Modelle**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Hinweise:
+Notes:
-– OpenRouter- und OpenAI/Anthropic-kompatible Anbieter werden nur über**verfügbare Modelle**verwaltet. Manuelles Hinzufügen, Importieren und automatische Synchronisieren landen alle in derselben Liste verfügbarer Modelle, sodass es für diese Anbieter keinen separaten Abschnitt „Benutzerdefinierte Modelle“ gibt.
-– Der Abschnitt**Benutzerdefinierte Modelle**ist für Anbieter gedacht, die keine verwalteten Importe verfügbarer Modelle verfügbar machen.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Leiten Sie Anfragen mit Modellvalidierung direkt an einen bestimmten Anbieter weiter:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Das Anbieterpräfix wird automatisch hinzugefügt, wenn es fehlt. Nicht übereinstimmende Modelle geben „400“ zurück.### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -594,171 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Vorrang:**Schlüsselspezifisch → Combo-spezifisch → Anbieterspezifisch → Global → Umgebung.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Gibt nach Anbieter gruppierte Modelle mit Typen („chat“, „embedding“, „image“) zurück.### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Synchronisieren Sie Anbieter, Kombinationen und Einstellungen geräteübergreifend
-- Automatische Hintergrundsynchronisierung mit Timeout + Fail-Fast
-- Bevorzugen Sie serverseitige „BASE_URL“/„CLOUD_URL“ in der Produktion### Cloudflare Quick Tunnel
+### Cloud Sync
-– Verfügbar in**Dashboard → Endpoints**für Docker und andere selbstgehostete Bereitstellungen
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
-- Erstellt eine temporäre „https://\*.trycloudflare.com“-URL, die an Ihren aktuellen OpenAI-kompatiblen „/v1“-Endpunkt weiterleitet
-- Zuerst aktivieren, installiert „cloudflared“ nur bei Bedarf; Bei späteren Neustarts wird dieselbe verwaltete Binärdatei wiederverwendet
- – Quick Tunnels werden nach einem OmniRoute- oder Container-Neustart nicht automatisch wiederhergestellt; Aktivieren Sie sie bei Bedarf über das Dashboard erneut
-- Tunnel-URLs sind kurzlebig und ändern sich jedes Mal, wenn Sie den Tunnel stoppen/starten
- – Managed Quick Tunnels verwenden standardmäßig den HTTP/2-Transport, um laute QUIC-UDP-Pufferwarnungen in eingeschränkten Containern zu vermeiden
-- Legen Sie „CLOUDFLARED_PROTOCOL=quic“ oder „auto“ fest, wenn Sie die Auswahl für den verwalteten Transport überschreiben möchten
-- Legen Sie „CLOUDFLARED_BIN“ fest, wenn Sie anstelle des verwalteten Downloads lieber eine vorinstallierte „Cloudflared“-Binärdatei verwenden möchten### LLM Gateway Intelligence (Phase 9)
+### Cloudflare Quick Tunnel
--**Semantischer Cache**– Nicht-Streaming-Antworten mit Temperatur = 0 werden automatisch zwischengespeichert (Umgehung mit „X-OmniRoute-No-Cache: true“) -**Request Idempotency**– Dedupliziert Anfragen innerhalb von 5 Sekunden über den Header „Idempotency-Key“ oder „X-Request-Id“. -**Fortschrittsverfolgung**– Opt-in-SSE-Events „event: progress“ über den Header „X-OmniRoute-Progress: true“.---
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Zugriff über**Dashboard → Übersetzer**. Debuggen und visualisieren Sie, wie OmniRoute API-Anfragen zwischen Anbietern übersetzt.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Modus | Zweck |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
-| **Spielplatz** | Wählen Sie Quell-/Zielformate aus, fügen Sie eine Anfrage ein und sehen Sie sich sofort die übersetzte Ausgabe an |
-| **Chat-Tester** | Senden Sie Live-Chat-Nachrichten über den Proxy und überprüfen Sie den gesamten Anfrage-/Antwortzyklus |
-| **Prüfstand** | Führen Sie Batch-Tests über mehrere Formatkombinationen hinweg durch, um die Übersetzungskorrektheit zu überprüfen |
-| **Live-Monitor** | Beobachten Sie Übersetzungen in Echtzeit, während Anfragen über den Proxy fließen |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Anwendungsfälle:**
+**Use cases:**
-- Debuggen Sie, warum eine bestimmte Client-/Provider-Kombination fehlschlägt
-- Stellen Sie sicher, dass Denktags, Toolaufrufe und Systemaufforderungen korrekt übersetzt werden
-- Vergleichen Sie Formatunterschiede zwischen den API-Formaten OpenAI, Claude, Gemini und Responses---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Konfigurieren Sie über**Dashboard → Einstellungen → Routing**.
+Configure via **Dashboard → Settings → Routing**.
-| Strategie | Beschreibung |
-| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Zuerst füllen** | Verwendet Konten in der Reihenfolge ihrer Priorität – das primäre Konto bearbeitet alle Anfragen, bis es nicht mehr verfügbar ist |
-| **Round Robin** | Durchläuft alle Konten mit einem konfigurierbaren Sticky-Limit (Standard: 3 Anrufe pro Konto) |
-| **P2C (Power of Two Choices)** | Wählt zwei zufällige Konten aus und leitet sie zum gesünderen weiter – gleicht Last mit Gesundheitsbewusstsein aus |
-| **Zufällig** | Wählt für jede Anfrage per Fisher-Yates-Shuffle | zufällig ein Konto aus |
-| **Am wenigsten genutzt** | Leitet zum Konto mit dem ältesten „lastUsedAt“-Zeitstempel weiter und verteilt den Datenverkehr gleichmäßig |
-| **Kostenoptimiert** | Leitet zum Konto mit dem niedrigsten Prioritätswert weiter, optimiert für Anbieter mit den niedrigsten Kosten | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Für externe Sitzungsaffinität (z. B. Claude Code/Codex-Agenten hinter Reverse-Proxys) senden Sie Folgendes:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute akzeptiert auch „x_session_id“ und gibt den effektiven Sitzungsschlüssel in „X-OmniRoute-Session-Id“ zurück.
+If you use Nginx and send underscore-form headers, enable:
-Wenn Sie Nginx verwenden und Unterstrich-Header senden, aktivieren Sie Folgendes:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Erstellen Sie Platzhaltermuster, um Modellnamen neu zuzuordnen:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Platzhalter unterstützen „*“ (beliebige Zeichen) und „?“ (einzelnes Zeichen).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Definieren Sie globale Fallback-Ketten, die für alle Anfragen gelten:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Konfigurieren Sie über**Dashboard → Einstellungen → Resilienz**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute implementiert Resilienz auf Anbieterebene mit vier Komponenten:
+OmniRoute implements provider-level resilience with four components:
-1.**Anbieterprofile**– Konfiguration pro Anbieter für:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Fehlerschwelle (wie viele Fehler vor dem Öffnen)
-- Abklingdauer
-- Empfindlichkeit der Grenzfrequenzerkennung
-- Exponentielle Backoff-Parameter
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Bearbeitbare Ratenbegrenzungen**– Standardeinstellungen auf Systemebene, konfigurierbar im Dashboard: -**Anfragen pro Minute (RPM)**– Maximale Anfragen pro Minute und Konto -**Min. Zeit zwischen Anfragen**– Mindestlücke in Millisekunden zwischen Anfragen -**Max. gleichzeitige Anfragen**– Maximale gleichzeitige Anfragen pro Konto
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Klicken Sie zum Ändern auf**Bearbeiten**und dann auf**Speichern**oder**Abbrechen**. Werte bleiben über die Resilience-API bestehen.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Leistungsschalter**– Verfolgt Ausfälle pro Anbieter und öffnet automatisch den Stromkreis, wenn ein Schwellenwert erreicht wird: -**GESCHLOSSEN**(fehlerfrei) – Anfragen fließen normal -**OFFEN**– Der Anbieter ist nach wiederholten Ausfällen vorübergehend gesperrt -**HALF_OPEN**– Testen, ob sich der Anbieter erholt hat
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Richtlinien und Sperrkennungen**– Zeigt den Status des Leistungsschalters und die Sperrkennungen mit der Möglichkeit zum erzwungenen Entsperren an.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Automatische Erkennung von Ratenbegrenzungen**– Überwacht die Header „429“ und „Retry-After“, um proaktiv zu vermeiden, dass die Ratenbegrenzungen der Anbieter erreicht werden.
-
-**Profi-Tipp:**Verwenden Sie die Schaltfläche**Alle zurücksetzen**, um alle Leistungsschalter und Abklingzeiten zu löschen, wenn ein Anbieter nach einem Ausfall wiederhergestellt wird.---
+---
### Database Export / Import
-Verwalten Sie Datenbanksicherungen unter**Dashboard → Einstellungen → System & Speicher**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Aktion | Beschreibung |
-| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Datenbank exportieren** | Lädt die aktuelle SQLite-Datenbank als „.sqlite“-Datei herunter |
-| **Alle exportieren (.tar.gz)** | Lädt ein vollständiges Backup-Archiv herunter, einschließlich: Datenbank, Einstellungen, Kombinationen, Anbieterverbindungen (keine Anmeldeinformationen), API-Schlüsselmetadaten |
-| **Datenbank importieren** | Laden Sie eine „.sqlite“-Datei hoch, um die aktuelle Datenbank zu ersetzen. Eine Sicherung vor dem Import wird automatisch erstellt, es sei denn, „DISABLE_SQLITE_AUTO_BACKUP=true“ | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Importvalidierung:**Die importierte Datei wird auf Integrität (SQLite-Pragma-Prüfung), erforderliche Tabellen („provider_connections“, „provider_nodes“, „combos“, „api_keys“) und Größe (max. 100 MB) validiert.
+**Use Cases:**
-**Anwendungsfälle:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- OmniRoute zwischen Maschinen migrieren
-- Erstellen Sie externe Backups für die Notfallwiederherstellung
-- Konfigurationen zwischen Teammitgliedern teilen (alle exportieren → Archiv teilen)---
+---
### Settings Dashboard
-Die Einstellungsseite ist zur einfachen Navigation in 6 Registerkarten unterteilt:
+The settings page is organized into 6 tabs for easy navigation:
-| Tab | Inhalt |
-| -------------- | ----------------------------------------------------------------- |
-|**Allgemein**| Systemspeicher-Tools, Darstellungseinstellungen, Design-Steuerelemente und Sichtbarkeit der Seitenleiste pro Element |
-|**Sicherheit**| Anmelde-/Passworteinstellungen, IP-Zugriffskontrolle, API-Authentifizierung für „/models“ und Anbieterblockierung |
-|**Routing**| Globale Routing-Strategie (6 Optionen), Wildcard-Modell-Aliase, Fallback-Ketten, Combo-Standardwerte |
-|**Belastbarkeit**| Anbieterprofile, bearbeitbare Tarifbegrenzungen, Leistungsschalterstatus, Richtlinien und Sperrkennungen |
-|**KI**| Denken Sie an die Budgetkonfiguration, die globale System-Prompt-Injektion, die Prompt-Cache-Statistiken |
-|**Fortgeschritten**| Globale Proxy-Konfiguration (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Zugang über**Dashboard → Kosten**.
+Access via **Dashboard → Costs**.
-| Tab | Zweck |
-| ----------- | ------------------------------------------------------------ |
-|**Budget**| Legen Sie Ausgabenlimits pro API-Schlüssel mit Tages-/Wochen-/Monatsbudgets und Echtzeitverfolgung fest |
-|**Preise**| Modellpreiseinträge anzeigen und bearbeiten – Kosten pro 1.000 Ein-/Ausgabe-Tokens pro Anbieter |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -766,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Kostenverfolgung:**Bei jeder Anfrage wird die Token-Nutzung protokolliert und die Kosten anhand der Preistabelle berechnet. Sehen Sie sich Aufschlüsselungen in**Dashboard → Nutzung**nach Anbieter, Modell und API-Schlüssel an.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute unterstützt die Audiotranskription über den OpenAI-kompatiblen Endpunkt:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Verfügbare Anbieter:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Unterstützte Audioformate: „mp3“, „wav“, „m4a“, „flac“, „ogg“, „webm“.---
+---
### Combo Balancing Strategies
-Konfigurieren Sie die Balance pro Combo unter**Dashboard → Combos → Erstellen/Bearbeiten → Strategie**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Strategie | Beschreibung |
-| ------------------- | ------------------------------------------------------------------------ |
-|**Round-Robin**| Rotiert nacheinander durch die Modelle |
-|**Priorität**| Versucht immer das erste Modell; fällt nur bei Fehler zurück |
-|**Zufällig**| Wählt für jede Anfrage ein zufälliges Modell aus der Kombination aus |
-|**Gewichtet**| Routen proportional basierend auf den zugewiesenen Gewichten pro Modell |
-|**Am wenigsten genutzt**| Leitet zum Modell mit den wenigsten aktuellen Anfragen weiter (verwendet Kombinationsmetriken) |
-|**Kostenoptimiert**| Leitet zum günstigsten verfügbaren Modell (unter Verwendung der Preistabelle) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Globale Combo-Standards können unter**Dashboard → Einstellungen → Routing → Combo-Standards**festgelegt werden.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Zugriff über**Dashboard → Gesundheit**. Echtzeit-Übersicht über den Systemzustand mit 6 Karten:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Karte | Was es zeigt |
+| Card | What It Shows |
| --------------------- | ----------------------------------------------------------- |
-|**Systemstatus**| Betriebszeit, Version, Speichernutzung, Datenverzeichnis |
-|**Anbietergesundheit**| Zustand des Leistungsschalters pro Anbieter (geschlossen/offen/halboffen) |
-|**Ratenbegrenzungen**| Aktive Abklingzeiten pro Konto mit verbleibender Zeit |
-|**Aktive Sperren**| Anbieter, die durch die Sperrrichtlinie vorübergehend gesperrt sind |
-|**Signatur-Cache**| Statistiken zum Deduplizierungs-Cache (aktive Schlüssel, Trefferquote) |
-|**Latenztelemetrie**| p50/p95/p99-Latenzaggregation pro Anbieter |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Profi-Tipp:**Die Gesundheitsseite wird alle 10 Sekunden automatisch aktualisiert. Verwenden Sie die Leistungsschalterkarte, um zu ermitteln, bei welchen Anbietern Probleme auftreten.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute ist als native Desktop-Anwendung für Windows, macOS und Linux verfügbar.### Installieren
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Installieren
```bash
# From the electron directory:
@@ -834,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -846,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Ausgabe → `electron/dist-electron/`### Key Features
+Output → `electron/dist-electron/`
-| Funktion | Beschreibung |
-| ------------------------------------ | ------------------------------------------------------------------------------ | ------------------------- |
-| **Serverbereitschaft** | Fragt den Server ab, bevor das Fenster angezeigt wird (kein leerer Bildschirm) |
-| **Systemablage** | Auf Fach minimieren, Port ändern, Fachmenü verlassen |
-| **Portverwaltung** | Server-Port aus der Taskleiste ändern (Server wird automatisch neu gestartet) |
-| **Richtlinie zur Inhaltssicherheit** | Restriktiver CSP über Sitzungsheader |
-| **Einzelne Instanz** | Es kann jeweils nur eine App-Instanz ausgeführt werden |
-| **Offline-Modus** | Der gebündelte Next.js-Server funktioniert ohne Internet | ### Environment Variables |
+### Key Features
-| Variable | Standard | Beschreibung |
-| --------------------- | -------- | -------------------------------- |
-| `OMNIROUTE_PORT` | `20128` | Server-Port |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js-Heap-Limit (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Vollständige Dokumentation: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/es/README.md b/docs/i18n/es/README.md
index 6ccb053c9a..352b0ab8d3 100644
--- a/docs/i18n/es/README.md
+++ b/docs/i18n/es/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/es/docs/USER_GUIDE.md b/docs/i18n/es/docs/USER_GUIDE.md
index 2fe0718e49..79e262ffc7 100644
--- a/docs/i18n/es/docs/USER_GUIDE.md
+++ b/docs/i18n/es/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Guía completa para configurar proveedores, crear combos, integrar herramientas CLI e implementar OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Precios de un vistazo](#-precios de un vistazo)
-- [Casos de uso](#-casos de uso)
-- [Configuración de proveedor](#-configuración-proveedor)
-- [Integración CLI](#-cli-integración)
-- [Implementación](#-implementación)
-- [Modelos disponibles](#-modelos-disponibles)
-- [Funciones avanzadas](#-funciones-avanzadas)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 Pricing at a Glance
-| Nivel | Proveedor | Costo | Restablecer cuota | Mejor para |
-| ------------------ | ---------------------- | -------------------- | ----------------------------- | --------------------------- |
-| **💳 SUSCRIPCIÓN** | Código Claude (Pro) | $20/mes | 5h + semanales | Ya suscrito |
-| | Códice (Plus/Pro) | $20-200/mes | 5h + semanales | Usuarios de OpenAI |
-| | Géminis CLI | **GRATIS** | 180K/mes + 1K/día | ¡Todos! |
-| | Copiloto de GitHub | $10-19/mes | Mensual | Usuarios de GitHub |
-| **🔑 CLAVE API** | Búsqueda profunda | Pago por uso | Ninguno | Razonamiento barato |
-| | Groq | Pago por uso | Ninguno | Inferencia ultrarrápida |
-| | xAI (Grok) | Pago por uso | Ninguno | Grok 4 razonamiento |
-| | Mistral | Pago por uso | Ninguno | Modelos alojados en la UE |
-| | Perplejidad | Pago por uso | Ninguno | Búsqueda aumentada |
-| | Juntos IA | Pago por uso | Ninguno | Modelos de código abierto |
-| | Fuegos artificiales AI | Pago por uso | Ninguno | Imágenes de flujo rápido |
-| | Cerebras | Pago por uso | Ninguno | Velocidad a escala de oblea |
-| | Coherir | Pago por uso | Ninguno | Comando R+ TRAPO |
-| | NIM de NVIDIA | Pago por uso | Ninguno | Modelos empresariales |
-| **💰 BARATO** | GLM-4.7 | 0,6 dólares/1 millón | Todos los días a las 10 a. m. | Respaldo presupuestario |
-| | MiniMax M2.1 | 0,2 dólares/1 millón | 5 horas rodantes | Opción más barata |
-| | Kimi K2 | $9/mes fijo | 10 millones de tokens/mes | Costo predecible |
-| **🆓 GRATIS** | Qoder | $0 | Ilimitado | 8 modelos gratis |
-| | Qwen | $0 | Ilimitado | 3 modelos gratis |
-| | kiro | $0 | Ilimitado | Claudio 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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Consejo profesional:**Comience con el combo Gemini CLI (180K gratis/mes) + Qoder (ilimitado gratis) = ¡costo de $0!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Problema:**La cuota vence sin usarse, la tasa se limita durante la codificación intensa```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Problema:**No puedo permitirme suscripciones, necesito codificación de IA confiable```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Problema:**Plazos, no puedo permitirme el tiempo de inactividad```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Problema:**Necesita asistente de IA en aplicaciones de mensajería, completamente gratis```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**Consejo profesional:**Utilice Opus para tareas complejas y Sonnet para mayor velocidad. ¡OmniRoute realiza un seguimiento de la cuota por modelo!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Mejor valor:**¡Enorme nivel gratuito! Utilice esto antes de los niveles pagos.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### GLM-4.7 (Daily reset, $0.6/1M)
-1. Regístrate: [Zhipu AI](https://open.bigmodel.cn/)
-2. Obtenga la clave API del plan de codificación
-3. Panel de control → Agregar clave API: Proveedor: `glm`, Clave 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`
-**Uso:**`glm/glm-4.7` —**Consejo profesional:**¡El plan de codificación ofrece 3× cuota a un costo de 1/7! Reiniciar diariamente a las 10:00 a.m.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Regístrate: [MiniMax](https://www.minimax.io/)
-2. Obtener clave API → Panel → Agregar clave API
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Uso:**`minimax/MiniMax-M2.1` —**Consejo profesional:**¡La opción más barata para contexto largo (1 millón de tokens)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Suscríbete: [Moonshot AI](https://platform.moonshot.ai/)
-2. Obtener clave API → Panel → Agregar clave API
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Uso:**`kimi/kimi-latest` —**Consejo profesional:**¡Fijo $9/mes por 10 millones de tokens = $0,90/1 millón de costo efectivo!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Edite `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Edite `~/.claude/config.json`:```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Edite `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**O use el Panel:**Herramientas CLI → OpenClaw → Configuración automática### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-La CLI carga automáticamente `.env` desde `~/.omniroute/.env` o `./.env`.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-Para servidores con RAM limitada, utilice la opción de límite de memoria:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Cree `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,12 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-Para el modo integrado en el host con binarios CLI, consulte la sección Docker en los documentos principales.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Los usuarios de Void Linux pueden empaquetar e instalar OmniRoute de forma nativa utilizando el marco de compilación cruzada `xbps-src`. Esto automatiza la compilación independiente de Node.js junto con los enlaces nativos `better-sqlite3` requeridos.
+### Void Linux (xbps-src)
-
-Ver plantilla xbps-src
```bash
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -408,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -475,80 +516,85 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Variables | Predeterminado | Descripción |
+| Variable | Default | Description |
| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-default-secret-cambiame` | Secreto de firma de JWT (**cambio en producción**) |
-| `CONTRASEÑA_INITIAL` | `123456` | Primera contraseña de inicio de sesión |
-| `DATA_DIR` | `~/.omniruta` | Directorio de datos (db, uso, registros) |
-| `PUERTO` | marco predeterminado | Puerto de servicio (`20128` en ejemplos) |
-| `NOMBRE DE HOST` | marco predeterminado | Vincular host (Docker por defecto es `0.0.0.0`) |
-| `NODO_ENV` | valor predeterminado de tiempo de ejecución | Establecer `producción` para implementación |
-| `BASE_URL` | `http://localhost:20128` | URL base interna del lado del servidor |
-| `NUBE_URL` | `https://omniroute.dev` | URL base del punto final de sincronización en la nube |
-| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Secreto HMAC para claves API generadas |
-| `REQUIRE_API_KEY` | `falso` | Aplicar clave de API de portador en `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `falso` | Permitir que Api Manager copie claves API completas a pedido |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Cadencia de actualización del lado del servidor para datos de límites de proveedor almacenados en caché; Los botones de actualización de la interfaz de usuario aún activan la sincronización manual |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `falso` | Deshabilite las instantáneas automáticas de SQLite antes de escribir/importar/restaurar; las copias de seguridad manuales todavía funcionan |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `falso` | Forzar cookie de autenticación "segura" (detrás del proxy inverso HTTPS) |
-| `CLOUDFLARED_BIN` | desarmado | Utilice un binario `cloudflared` existente en lugar de una descarga administrada |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Transporte para Quick Tunnels administrados (`http2`, `quic` o `auto`) |
-| `OMNIROUTE_MEMORY_MB` | `512` | Límite de montón de Node.js en MB |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | Entradas máximas de caché de avisos |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Entradas máximas de caché semántica |Para obtener la referencia completa de las variables de entorno, consulte [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Ver todos los modelos disponibles
+
+View all available models
-**Código Claude (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— GRATIS: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**Copilot de GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— $0,6/1 millón: `glm/glm-4.7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— $0,2/1 millón: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— GRATIS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— GRATIS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— GRATIS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
-**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-razonamiento-rápido`, `xai/grok-code-mini`
+**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Perplejidad (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**Juntos AI (`juntos/`)**: `juntos/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**Fuegos artificiales AI (`fuegos artificiales/`)**: `fuegos artificiales/cuentas/fuegos artificiales/modelos/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -556,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Agregue cualquier ID de modelo a cualquier proveedor sin esperar una actualización de la aplicación:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -564,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-O utilice el Panel de control:**Proveedores → [Proveedor] → Modelos personalizados**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Notas:
+Notes:
-- Los proveedores compatibles con OpenRouter y OpenAI/Anthropic se administran desde**Modelos disponibles**únicamente. La adición manual, la importación y la sincronización automática se encuentran en la misma lista de modelos disponibles, por lo que no hay una sección de Modelos personalizados separada para esos proveedores.
-- La sección**Modelos personalizados**está destinada a proveedores que no exponen importaciones administradas de modelos disponibles.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Enrutar solicitudes directamente a un proveedor específico con validación de modelo:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-El prefijo del proveedor se agrega automáticamente si falta. Los modelos que no coinciden devuelven "400".### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -594,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Precedencia:**Específico de clave → Específico de combo → Específico de proveedor → Global → Entorno.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Devuelve modelos agrupados por proveedor con tipos (`chat`, `incrustación`, `imagen`).### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Sincronizar proveedores, combos y configuraciones entre dispositivos
-- Sincronización automática en segundo plano con tiempo de espera + falla rápida
-- Prefiere `BASE_URL`/`CLOUD_URL` del lado del servidor en producción### Cloudflare Quick Tunnel
+### Cloud Sync
-- Disponible en**Panel → Puntos finales**para Docker y otras implementaciones autohospedadas
-- Crea una URL temporal `https://*.trycloudflare.com` que reenvía a su punto final actual `/v1` compatible con OpenAI
-- Primero habilite instala `cloudflared` solo cuando sea necesario; más tarde se reinicia y se reutiliza el mismo binario administrado
-- Los túneles rápidos no se restauran automáticamente después de reiniciar OmniRoute o un contenedor; Vuelva a habilitarlos desde el tablero cuando sea necesario.
-- Las URL del túnel son efímeras y cambian cada vez que detienes o inicias el túnel.
-- Los túneles rápidos administrados utilizan de forma predeterminada el transporte HTTP/2 para evitar ruidosas advertencias del buffer QUIC UDP en contenedores restringidos.
-- Establezca `CLOUDFLARED_PROTOCOL=quic` o `auto` si desea anular la opción de transporte administrado
-- Configure `CLOUDFLARED_BIN` si prefiere usar un binario `cloudflared` preinstalado en lugar de la descarga administrada.### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Caché semántica**: caché automático sin transmisión, temperatura = 0 respuestas (omitir con `X-OmniRoute-No-Cache: true`) -**Request Idempotency**: deduplica solicitudes en 5 segundos a través del encabezado `Idempotency-Key` o `X-Request-Id` -**Seguimiento de progreso**: active los eventos `evento: progreso` de SSE a través del encabezado `X-OmniRoute-Progress: verdadero`---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Acceda a través de**Panel → Traductor**. Depure y visualice cómo OmniRoute traduce las solicitudes de API entre proveedores.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Modo | Propósito |
-| -------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| **Parque infantil** | Seleccione formatos de origen/destino, pegue una solicitud y vea el resultado traducido al instante |
-| **Probador de chat** | Envíe mensajes de chat en vivo a través del proxy e inspeccione el ciclo completo de solicitud/respuesta |
-| **Banco de pruebas** | Ejecute pruebas por lotes en múltiples combinaciones de formatos para verificar la corrección de la traducción |
-| **Monitorización en vivo** | Vea traducciones en tiempo real a medida que las solicitudes fluyen a través del proxy |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Casos de uso:**
+**Use cases:**
-- Depurar por qué falla una combinación específica de cliente/proveedor
-- Verificar que las etiquetas de pensamiento, las llamadas a herramientas y las indicaciones del sistema se traduzcan correctamente
-- Compare las diferencias de formato entre los formatos OpenAI, Claude, Gemini y Responses API---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Configure a través de**Panel → Configuración → Enrutamiento**.
+Configure via **Dashboard → Settings → Routing**.
-| Estrategia | Descripción |
-| ------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Llene primero** | Utiliza cuentas en orden de prioridad: la cuenta principal maneja todas las solicitudes hasta que no esté disponible |
-| **Round Robin** | Recorre todas las cuentas con un límite fijo configurable (predeterminado: 3 llamadas por cuenta) |
-| **P2C (Poder de dos opciones)** | Elige 2 cuentas al azar y ruta hacia la más saludable: los saldos se cargan con conciencia de la salud |
-| **Aleatorio** | Selecciona aleatoriamente una cuenta para cada solicitud mediante la reproducción aleatoria de Fisher-Yates |
-| **Menos usado** | Rutas a la cuenta con la marca de tiempo `lastUsedAt` más antigua, distribuyendo el tráfico de manera uniforme |
-| **Costo optimizado** | Rutas a la cuenta con el valor de prioridad más bajo, optimizando para proveedores de menor costo | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Para afinidad de sesión externa (por ejemplo, agentes Claude Code/Codex detrás de servidores proxy inversos), envíe:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute también acepta `x_session_id` y devuelve la clave de sesión efectiva en `X-OmniRoute-Session-Id`.
+If you use Nginx and send underscore-form headers, enable:
-Si usa Nginx y envía encabezados de formato de guión bajo, habilite:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Cree patrones comodín para reasignar nombres de modelos:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Los comodines admiten `*` (cualquier carácter) y `?` (un solo carácter).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Defina cadenas de respaldo globales que se apliquen a todas las solicitudes:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Configure a través de**Panel → Configuración → Resiliencia**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute implementa resiliencia a nivel de proveedor con cuatro componentes:
+OmniRoute implements provider-level resilience with four components:
-1.**Perfiles de proveedor**: configuración por proveedor para:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Umbral de fallas (cuántas fallas antes de abrir)
-- Duración del tiempo de recuperación
-- Sensibilidad de detección de límite de velocidad
-- Parámetros de retroceso exponencial
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Límites de tarifas editables**: valores predeterminados a nivel del sistema configurables en el panel: -**Solicitudes por minuto (RPM)**: solicitudes máximas por minuto por cuenta -**Tiempo mínimo entre solicitudes**: intervalo mínimo en milisegundos entre solicitudes -**Máximo de solicitudes simultáneas**: máximo de solicitudes simultáneas por cuenta
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Haga clic en**Editar**para modificar y luego en**Guardar**o**Cancelar**. Los valores persisten a través de la API de resiliencia.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Disyuntor**: realiza un seguimiento de las fallas por proveedor y abre automáticamente el circuito cuando se alcanza un umbral: -**CERRADO**(En buen estado): las solicitudes fluyen normalmente -**ABIERTO**: el proveedor está bloqueado temporalmente después de fallas repetidas -**HALF_OPEN**— Probando si el proveedor se ha recuperado
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Políticas e identificadores bloqueados**: muestra el estado del disyuntor y los identificadores bloqueados con capacidad de desbloqueo forzado.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Detección automática del límite de tasa**: monitorea los encabezados "429" y "Reintentar después" para evitar de manera proactiva alcanzar los límites de tasa del proveedor.
-
-**Consejo profesional:**Utilice el botón**Restablecer todo**para borrar todos los disyuntores y tiempos de reutilización cuando un proveedor se recupera de una interrupción.---
+---
### Database Export / Import
-Administre las copias de seguridad de la base de datos en**Panel → Configuración → Sistema y almacenamiento**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Acción | Descripción |
-| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Exportar base de datos** | Descarga la base de datos SQLite actual como un archivo `.sqlite` |
-| **Exportar todo (.tar.gz)** | Descarga un archivo de copia de seguridad completo que incluye: base de datos, configuraciones, combinaciones, conexiones de proveedores (sin credenciales), metadatos de clave API |
-| **Importar base de datos** | Cargue un archivo `.sqlite` para reemplazar la base de datos actual. Se crea automáticamente una copia de seguridad previa a la importación a menos que `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Validación de importación:**El archivo importado se valida en cuanto a integridad (verificación de pragma de SQLite), tablas requeridas (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) y tamaño (máximo 100 MB).
+**Use Cases:**
-**Casos de uso:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Migrar OmniRoute entre máquinas
-- Crear copias de seguridad externas para la recuperación de desastres.
-- Compartir configuraciones entre los miembros del equipo (exportar todo → compartir archivo)---
+---
### Settings Dashboard
-La página de configuración está organizada en 6 pestañas para facilitar la navegación:
+The settings page is organized into 6 tabs for easy navigation:
-| Pestaña | Contenidos |
+| Tab | Contents |
| -------------- | ---------------------------------------------------------------------------------------------- |
-|**Generalidades**| Herramientas de almacenamiento del sistema, configuraciones de apariencia, controles de temas y visibilidad de la barra lateral por elemento |
-|**Seguridad**| Configuración de inicio de sesión/contraseña, control de acceso IP, autenticación API para `/models` y bloqueo de proveedores |
-|**Enrutamiento**| Estrategia de enrutamiento global (6 opciones), alias de modelos comodín, cadenas de respaldo, valores predeterminados combinados |
-|**Resiliencia**| Perfiles de proveedores, límites de tarifas editables, estado de los disyuntores, políticas e identificadores bloqueados |
-|**IA**| Pensando en la configuración del presupuesto, inyección de avisos del sistema global, estadísticas de caché de avisos |
-|**Avanzado**| Configuración de proxy global (HTTP/SOCKS5) |---
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Acceso a través de**Panel → Costos**.
+Access via **Dashboard → Costs**.
-| Pestaña | Propósito |
+| Tab | Purpose |
| ----------- | ---------------------------------------------------------------------------------------- |
-|**Presupuesto**| Establezca límites de gasto por clave API con presupuestos diarios/semanales/mensuales y seguimiento en tiempo real |
-|**Precios**| Ver y editar entradas de precios de modelos: costo por 1.000 tokens de entrada/salida por proveedor |```bash
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -765,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Seguimiento de costos:**Cada solicitud registra el uso del token y calcula el costo utilizando la tabla de precios. Vea desgloses en**Panel → Uso**por proveedor, modelo y clave API.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute admite la transcripción de audio a través del punto final compatible con OpenAI:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Proveedores disponibles:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Formatos de audio admitidos: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.---
+---
### Combo Balancing Strategies
-Configure el equilibrio por combo en**Panel → Combos → Crear/Editar → Estrategia**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Estrategia | Descripción |
+| Strategy | Description |
| ------------------ | ------------------------------------------------------------------------ |
-|**Todos contra todos**| Gira a través de modelos secuencialmente |
-|**Prioridad**| Siempre prueba el primer modelo; retrocede sólo en caso de error |
-|**Aleatorio**| Elige un modelo aleatorio del combo para cada solicitud |
-|**Ponderado**| Rutas proporcionalmente en función de los pesos asignados por modelo |
-|**Menos usado**| Rutas al modelo con la menor cantidad de solicitudes recientes (utiliza métricas combinadas) |
-|**Optimización de costos**| Rutas al modelo más barato disponible (utiliza tabla de precios) |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Los valores predeterminados combinados globales se pueden configurar en**Panel → Configuración → Enrutamiento → Valores predeterminados combinados**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Accede a través de**Panel → Salud**. Descripción general del estado del sistema en tiempo real con 6 tarjetas:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Tarjeta | Lo que muestra |
-| --------------------- | ----------------------------------------------------- |
-|**Estado del sistema**| Tiempo de actividad, versión, uso de memoria, directorio de datos |
-|**Salud del proveedor**| Estado del disyuntor por proveedor (cerrado/abierto/medio abierto) |
-|**Límites de tarifas**| Tiempos de reutilización del límite de tasa activa por cuenta con tiempo restante |
-|**Bloqueos activos**| Proveedores bloqueados temporalmente por la política de bloqueo |
-|**Caché de firma**| Estadísticas de caché de deduplicación (claves activas, tasa de aciertos) |
-|**Telemetría de latencia**| Agregación de latencia p50/p95/p99 por proveedor |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Consejo profesional:**La página Salud se actualiza automáticamente cada 10 segundos. Utilice la tarjeta del disyuntor para identificar qué proveedores están experimentando problemas.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute está disponible como aplicación de escritorio nativa para Windows, macOS y Linux.### Instalar
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Instalar
```bash
# From the electron directory:
@@ -833,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -845,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Salida → `electrón/dist-electrón/`### Key Features
+Output → `electron/dist-electron/`
-| Característica | Descripción |
-| -------------------------------------- | --------------------------------------------------------------------------------- | ------------------------- |
-| **Preparación del servidor** | Servidor de encuestas antes de mostrar la ventana (sin pantalla en blanco) |
-| **Bandeja del sistema** | Minimizar a bandeja, cambiar puerto, salir del menú de bandeja |
-| **Gestión Portuaria** | Cambiar el puerto del servidor desde la bandeja (servidor de reinicio automático) |
-| **Política de seguridad de contenido** | CSP restrictivo mediante encabezados de sesión |
-| **Instancia única** | Solo se puede ejecutar una instancia de aplicación a la vez |
-| **Modo sin conexión** | El servidor Next.js incluido funciona sin Internet | ### Environment Variables |
+### Key Features
-| Variables | Predeterminado | Descripción |
-| --------------------- | -------------- | ---------------------------------------------------------- |
-| `OMNIROUTE_PORT` | `20128` | Puerto del servidor |
-| `OMNIROUTE_MEMORY_MB` | `512` | Límite de almacenamiento dinámico de Node.js (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Documentación completa: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/fi/README.md b/docs/i18n/fi/README.md
index 7f476e6045..d2433e8a01 100644
--- a/docs/i18n/fi/README.md
+++ b/docs/i18n/fi/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/fi/docs/USER_GUIDE.md b/docs/i18n/fi/docs/USER_GUIDE.md
index f90f73d7fc..2bad485f4d 100644
--- a/docs/i18n/fi/docs/USER_GUIDE.md
+++ b/docs/i18n/fi/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Täydellinen opas palveluntarjoajien määrittämiseen, yhdistelmien luomiseen, CLI-työkalujen integrointiin ja OmniRouten käyttöönottoon.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Hinnoittelu yhdellä silmäyksellä](#-pricing-at-a-glance)
-- [Käyttötapaukset](#-käyttötapausta)
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
- [Provider Setup](#-provider-setup)
-- [CLI-integrointi](#-cli-integraatio)
-- [Käyttöönotto](#-käyttöönotto)
-- [Saatavilla olevat mallit](#-käytettävissä olevaa-mallia)
-- [Lisäominaisuudet](#-lisäominaisuuksia)---
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 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** | DeepSeek | Maksu per käyttö | Ei yhtään | Halpa perustelu |
-| | Groq | Maksu per käyttö | Ei yhtään | Erittäin nopea johtopäätös |
-| | xAI (Grok) | Maksu per käyttö | Ei yhtään | Grok 4 perustelut |
-| | Mistral | Maksu per käyttö | Ei yhtään | EU:n isännöimät mallit |
-| | Hämmennys | Maksu per käyttö | Ei yhtään | Haku-lisätty |
-| | Yhdessä AI | Maksu per käyttö | Ei yhtään | Avoimen lähdekoodin mallit |
-| | Ilotulitus AI | Maksu per käyttö | Ei yhtään | Nopeat FLUX-kuvat |
-| | Aivot | Maksu per käyttö | Ei yhtään | Kiekon mittakaavanopeus |
-| | Cohere | Maksu per käyttö | Ei yhtään | Komento R+ RAG |
-| | NVIDIA NIM | Maksu per käyttö | Ei yhtään | Yritysmallit |
-| **💰 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** | Qoder | 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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Pro-vinkki:**Aloita Gemini CLI:llä (180 000 ilmaista kuukaudessa) + Qoder (rajoittamaton ilmainen) -yhdistelmä = 0 dollarin hinta!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Ongelma:**Kiintiö vanhenee käyttämättä, nopeusrajoitukset raskaan koodauksen aikana```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Ongelma:**Ei ole varaa tilauksiin, tarvitaan luotettavaa tekoälykoodausta```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Ongelma:**Määräajat, seisokkeihin ei ole varaa```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Ongelma:**Tarvitset AI-avustajan viestisovelluksissa, täysin ilmainen```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**Provinkki:**Käytä Opusta monimutkaisiin tehtäviin ja Sonnetia nopeutta varten. OmniRoute jäljityskiintiö mallia kohti!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Paras hinta-laatusuhde:**Valtava ilmainen taso! Käytä tätä ennen maksettuja tasoja.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### 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: "oma-avain"
+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` —**Provinkki:**Coding Plan tarjoaa 3× kiintiön 1/7 hinnalla! Nollaa päivittäin klo 10.00.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Rekisteröidy: [MiniMax](https://www.minimax.io/)
-2. Hanki API-avain → Dashboard → Add API Key
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Käytä:**`minimax/MiniMax-M2.1` —**Pro-vinkki:**Halvin vaihtoehto pitkälle kontekstille (1 miljoonaa merkkiä)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Tilaa: [Moonshot AI](https://platform.moonshot.ai/)
-2. Hanki API-avain → Dashboard → Add API Key
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Käyttö:**`kimi/kimi-latest` —**Ammattilaisen vinkki:**Kiinteä 9 dollaria kuukaudessa 10 miljoonalle tokenille = 0,90 dollaria / 1 miljoona todellista hintaa!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Muokkaa `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Muokkaa `~/.claude/config.json`:```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Muokkaa `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Tai käytä Dashboardia:**CLI Tools → OpenClaw → Auto-config### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI lataa automaattisesti .env-tiedoston osoitteesta ~/.omniroute/.env tai ./.env.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-Palvelimissa, joissa on rajoitettu RAM-muisti, käytä muistirajoitusvaihtoehtoa:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Luo "ecosystem.config.js":```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,12 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-Katso isäntäintegroitu tila CLI-binaarien kanssa pääasiakirjojen Docker-osiosta.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Void Linux -käyttäjät voivat pakata ja asentaa OmniRouten natiivisti käyttämällä `xbps-src` -ristikäännöskehystä. Tämä automatisoi Node.js:n itsenäisen koontiversion sekä tarvittavat "better-sqlite3" -natiivisidokset.
+### Void Linux (xbps-src)
-
-Näytä xbps-src-malli```bash
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -408,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -475,80 +516,85 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Muuttuja | Oletus | Kuvaus |
-| ---------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| "JWT_SECRET" | `omniroute-default-secret-change-me` | JWT:n allekirjoitussalaisuus (**muutos tuotannossa**) |
-| `ALKU_SALASANA` | "123456" | Ensimmäisen kirjautumisen salasana |
-| `DATA_DIR` | `~/.omniroute` | Tietohakemisto (db, käyttö, lokit) |
-| "PORTTI" | oletuskehys | Huoltoportti (`20128` esimerkeissä) |
-| `HOSTNAME` | oletuskehys | Sido isäntä (Dockerin oletusarvo on `0.0.0.0`) |
-| "NODE_ENV" | ajonaikainen oletus | Aseta "tuotanto" käyttöönotolle |
-| "BASE_URL" | `http://localhost:20128` | Palvelinpuolen sisäinen perus-URL |
-| `CLOUD_URL` | `https://omniroute.dev` | Pilvisynkronoinnin päätepisteen perus-URL |
-| "API_KEY_SECRET" | `endpoint-proxy-api-key-secret` | Luotujen API-avaimien HMAC-salaisuus |
-| `REQUIRE_API_KEY` | "väärä" | Pakota Bearer API-avain `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `väärä` | Salli Api Managerin kopioida täydet API-avaimet pyynnöstä |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES' | "70" | Palvelinpuolen päivitystiheys välimuistissa oleville palveluntarjoajan rajoitustiedoille; Käyttöliittymän päivityspainikkeet käynnistävät edelleen manuaalisen synkronoinnin |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `väärä` | Poista automaattiset SQLite-vedoskuvat käytöstä ennen kirjoitusta/tuontia/palautusta; manuaaliset varmuuskopiot toimivat edelleen |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `väärä` | Pakota "Suojattu" todennuseväste (HTTS:n käänteisen välityspalvelimen takana) |
-| "CLOUDFLARED_BIN" | pois käytöstä | Käytä olemassa olevaa "cloudflared"-binaaria hallitun latauksen sijasta |
-| `CLOUDFLARED_PROTOCOL' | `http2` | Kuljetus hallituille pikatunneleille ("http2", "quic" tai "auto") |
-| `OMNIROUTE_MEMORY_MB` | "512" | Node.js-keon rajoitus megatavuina |
-| `PROMPT_CACHE_MAX_SIZE` | "50" | Enimmäiskehotteet välimuistin merkinnät |
-| `SEMANTIC_CACHE_MAX_SIZE` | "100" | Semanttisen välimuistin enimmäismerkinnät |Täydellinen ympäristömuuttujaviittaus on kohdassa [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Näytä kaikki saatavilla olevat mallit
+
+View all available models
-**Claude Code (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Koodi (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— ILMAISEKSI: "gc/gemini-3-flash-preview", "gc/gemini-2.5-pro"
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**GitHub Copilot (gh/`)**: gh/gpt-5, gh/claude-4.5-sonnet
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**– 0,6 $/1 milj.: "glm/glm-4,7"
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— 0,2 $/1 milj.: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— ILMAISEKSI: "if/kimi-k2-thinking", "if/qwen3-coder-plus", "if/deepseek-r1"
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— ILMAISEKSI: "qw/qwen3-coder-plus", "qw/qwen3-coder-flash"
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— ILMAISEKSI: `kr/claude-sonnet-4,5`, `kr/claude-haiku-4,5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
-**DeepSeek (`ds/`)**: `ds/deepseek-chat, `ds/deepseek-reasoner`
+**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
-**Groq ("groq/")**: "groq/llama-3.3-70b-versatile", "groq/llama-4-maverick-17b-128e-instruct"
+**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
-**xAI (`xai/`)**: "xai/grok-4", "xai/grok-4-0709-fast-reasoning", "xai/grok-code-mini"
+**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Hämmitys ("pplx/")**: "pplx/sonar-pro", "pplx/sonar"
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**Fireworks AI ("fireworks/")**: "fireworks/accounts/fireworks/models/deepseek-v3p1"
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**Cerebras (`cerebras/`)**: `cerebras/laama-3,3-70b`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -556,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Lisää mikä tahansa mallitunnus mille tahansa palveluntarjoajalle odottamatta sovelluspäivitystä:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -564,22 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Tai käytä Dashboardia:**Providers → [Provider] → Custom Models**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Huomautuksia:
+Notes:
-- OpenRouter- ja OpenAI/Anthropic-yhteensopivia palveluntarjoajia hallitaan vain**Saatavilla olevista malleista**. Manuaalinen lisääminen, tuonti ja automaattinen synkronointi ovat kaikki samassa käytettävissä olevien mallien luettelossa, joten näille palveluntarjoajille ei ole erillistä mukautetut mallit -osiota. -**Mukautetut mallit**-osio on tarkoitettu palveluntarjoajille, jotka eivät paljasta hallittujen käytettävissä olevien mallien tuontia.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Reititä pyynnöt suoraan tietylle palveluntarjoajalle mallin validoinnilla:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Palveluntarjoajan etuliite lisätään automaattisesti, jos se puuttuu. Yhteensopimattomat mallit palauttavat "400".### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -593,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Ensisijaisuus:**Avainkohtainen → Yhdistelmäkohtainen → Palveluntarjoajakohtainen → Globaali → Ympäristö.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Palauttaa mallit, jotka on ryhmitelty palveluntarjoajan mukaan tyypeillä ("chat", "embedding", "image").### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Synkronoi palveluntarjoajat, yhdistelmät ja asetukset eri laitteiden välillä
-- Automaattinen taustasynkronointi aikakatkaisulla + Fast Fast
-- Suosi palvelinpuolen BASE_URL-/CLOUD_URL-osoitetta tuotannossa### Cloudflare Quick Tunnel
+### Cloud Sync
-- Saatavilla kohdassa**Dashboard → Endpoints**Dockeria ja muita itseisännöityjä käyttöönottoja varten
-- Luo väliaikaisen https://\*.trycloudflare.com-URL-osoitteen, joka ohjaa edelleen nykyiseen OpenAI-yhteensopivaan `/v1-päätepisteeseesi
-- Salli ensin asennus "cloudflared" vain tarvittaessa; myöhemmin uudelleenkäynnistys käyttää samaa hallittua binaaritiedostoa uudelleen
-- Pikatunneleita ei palauteta automaattisesti OmniRouten tai kontin uudelleenkäynnistyksen jälkeen; ota ne uudelleen käyttöön kojelaudasta tarvittaessa
-- Tunnelin URL-osoitteet ovat lyhytaikaisia ja muuttuvat aina, kun pysäytät/aloitat tunnelin
-- Hallitut pikatunnelit käyttävät oletuksena HTTP/2-siirtoa meluisten QUIC UDP -puskurivaroitusten välttämiseksi rajoitetuissa säilöissä
-- Aseta "CLOUDFLARED_PROTOCOL=quic" tai "auto", jos haluat ohittaa hallitun kuljetusvalinnan
-- Aseta CLOUDFLARED_BIN, jos haluat käyttää esiasennettua 'cloudflared'-binaaria hallitun latauksen sijaan### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Semanttinen välimuisti**— Tallentaa automaattisesti välimuistiin ei-suoratoistoa, lämpötila = 0 vastausta (ohita X-OmniRoute-No-Cache: true') -**Request Idempotency**– Poistaa pyyntöjen kaksoiskappaleet 5 sekunnissa "Idempotency-Key"- tai "X-Request-Id"-otsikon kautta -**Edistyksen seuranta**— Ota SSE:n tapahtuma: edistyminen -tapahtumat käyttöön X-OmniRoute-Progress: true -otsikon kautta---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Pääsy**Dashboard → Kääntäjän**kautta. Tee virheenkorjaus ja visualisoi, kuinka OmniRoute kääntää API-pyynnöt palveluntarjoajien välillä.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Tila | Tarkoitus |
-| ------------------------- | ---------------------------------------------------------------------------------------- |
-| **Leikkikenttä** | Valitse lähde-/kohdemuodot, liitä pyyntö ja näet käännetyn tulosteen välittömästi |
-| **Pikaviestien testaaja** | Lähetä live-chat-viestejä välityspalvelimen kautta ja tarkista koko pyyntö-/vastausjakso |
-| **Testipenkki** | Suorita erätestejä useille muotoyhdistelmille varmistaaksesi käännöksen oikeellisuuden |
-| **Live Monitor** | Katso reaaliaikaisia käännöksiä, kun pyynnöt kulkevat välityspalvelimen kautta |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Käyttötapaukset:**
+**Use cases:**
-- Selvitä, miksi tietty asiakas/toimittaja-yhdistelmä epäonnistuu
-- Varmista, että ajattelutunnisteet, työkalukutsut ja järjestelmäkehotteet käännetään oikein
-- Vertaa muotoeroja OpenAI-, Claude-, Gemini- ja Responses API -muotojen välillä---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Määritä kohdasta**Kojelauta → Asetukset → Reititys**.
+Configure via **Dashboard → Settings → Routing**.
-| Strategia | Kuvaus |
-| ------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Täytä ensin** | Käyttää tilejä tärkeysjärjestyksessä — ensisijainen tili käsittelee kaikki pyynnöt, kunnes ne eivät ole käytettävissä |
-| **Round Robin** | Selaa kaikki tilit, joilla on määritettävissä oleva rajoitus (oletus: 3 puhelua tiliä kohden) |
-| **P2C (Kahden valinnan teho)** | Valitsee 2 satunnaista tiliä ja reitit terveempään tiliin – tasapainottaa kuormituksen terveystietoisuuden kanssa |
-| **Satunnainen** | Valitsee satunnaisesti tilin kullekin pyynnölle käyttämällä Fisher-Yates shuffle |
-| **Vähiten käytetty** | Reitit tilille, jolla on vanhin "lastUsedAt" aikaleima, jakaa liikenteen tasaisesti |
-| **Kustannusoptimoitu** | Reitit tilille, jolla on alhaisin prioriteettiarvo, optimointi edullisimpien palveluntarjoajien mukaan | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Jos kyseessä on ulkoinen istuntosuhde (esimerkiksi Claude Code/Codex-agentit käänteisten välityspalvelinten takana), lähetä:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute hyväksyy myös "x_session_id" ja palauttaa voimassa olevan istuntoavaimen kohdassa "X-OmniRoute-Session-Id".
+If you use Nginx and send underscore-form headers, enable:
-Jos käytät Nginxiä ja lähetät alaviiva-lomakkeen otsikoita, ota käyttöön:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Luo jokerimerkkikuvioita mallien nimien uudelleen yhdistämiseksi:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Jokerimerkit tukevat `*` (kaikki merkit) ja `?` (yksi merkki).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Määritä maailmanlaajuiset varaketjut, jotka koskevat kaikkia pyyntöjä:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Määritä kohdasta**Kojelauta → Asetukset → Resilience**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute toteuttaa toimittajatason joustavuutta neljällä osalla:
+OmniRoute implements provider-level resilience with four components:
-1.**Toimittajan profiilit**— Palveluntarjoajakohtainen määritys:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Vikakynnys (kuinka monta vikaa ennen avaamista)
-- Jäähdytyskesto
-- Nopeusrajan tunnistusherkkyys
-- Eksponentiaaliset peruutusparametrit
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Muokattavat nopeusrajoitukset**— Järjestelmätason oletusasetukset, jotka voidaan määrittää kojelaudassa: -**Pyynnöt minuutissa (RPM)**– Pyyntöjen enimmäismäärä minuutissa per tili -**Pyyntöjen välinen vähimmäisaika**- pyyntöjen välinen vähimmäisero millisekunteina -**Samanaikaisten pyyntöjen enimmäismäärä**— Samanaikaisten pyyntöjen enimmäismäärä tiliä kohden
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Napsauta**Muokkaa**muokataksesi ja sitten**Tallenna**tai**Peruuta**. Arvot säilyvät resilience API:n kautta.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Circuit Breaker**– Seuraa vikoja palveluntarjoajakohtaisesti ja avaa piirin automaattisesti, kun kynnys saavutetaan: -**SULJETTU**(terve) — Pyynnöt kulkevat normaalisti -**AUKI**— Palveluntarjoaja on tilapäisesti estetty toistuvien vikojen jälkeen -**HALF_OPEN**— Testataan, onko palveluntarjoaja palautunut
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Policies & Locked Identifiers**— Näyttää katkaisijan tilan ja lukitut tunnisteet, joissa on pakko-avaaminen.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Automaattinen nopeusrajoituksen tunnistus**— Valvoo "429"- ja "Retry-After"-otsikoita välttääkseen ennakoivasti palveluntarjoajan nopeusrajojen ylittymisen.
-
-**Ammattilaisen vinkki:**Käytä**Nollaa kaikki**-painiketta tyhjentääksesi kaikki katkaisijat ja jäähdytykset, kun palveluntarjoaja toipuu katkosta.---
+---
### Database Export / Import
-Hallitse tietokannan varmuuskopioita kohdassa**Käyttöpaneeli → Asetukset → Järjestelmä ja tallennus**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Toiminta | Kuvaus |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Vie tietokanta** | Lataa nykyisen SQLite-tietokannan .sqlite-tiedostona |
-| **Vie kaikki (.tar.gz)** | Lataa täyden varmuuskopioarkiston, joka sisältää: tietokannan, asetukset, yhdistelmät, palveluntarjoajan yhteydet (ei tunnistetietoja), API-avaimen metatiedot |
-| **Tuo tietokanta** | Lataa .sqlite-tiedosto nykyisen tietokannan tilalle. Tuontia edeltävä varmuuskopio luodaan automaattisesti, ellei `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Tuonnin vahvistus:**Tuodun tiedoston eheys (SQLite pragma check), vaaditut taulukot (provider_connections, provider_nodes, combos, api_keys) ja koko (enintään 100 Mt) tarkistetaan.
+**Use Cases:**
-**Käyttötapaukset:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Siirrä OmniRoute koneiden välillä
-- Luo ulkoisia varmuuskopioita katastrofipalautusta varten
-- Jaa kokoonpanot tiimin jäsenten välillä (vie kaikki → jaa arkisto)---
+---
### Settings Dashboard
-Asetussivu on järjestetty 6 välilehteen navigoinnin helpottamiseksi:
+The settings page is organized into 6 tabs for easy navigation:
-| Välilehti | Sisältö |
-| --------------- | ---------------------------------------------------------------------------------------------- |
-|**Yleinen**| Järjestelmän tallennustyökalut, ulkoasuasetukset, teemaohjaimet ja kohdekohtainen sivupalkin näkyvyys |
-|**Turvallisuus**| Kirjautumis-/salasana-asetukset, IP-käytön valvonta, API-todennus /mallille ja palveluntarjoajan esto |
-|**Reititys**| Globaali reititysstrategia (6 vaihtoehtoa), jokerimerkkimallien aliakset, varaketjut, yhdistelmäoletukset |
-|**Kestävyys**| Palveluntarjoajan profiilit, muokattavat nopeusrajoitukset, katkaisijan tila, käytännöt ja lukitut tunnisteet |
-|**AI**| Ajatteleva budjettimäärittely, globaali järjestelmäkehote, nopea välimuistitilastot |
-|**Lisäasetukset**| Yleiset välityspalvelimen asetukset (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Pääsy kohdasta**Käyttöpaneeli → Kulut**.
+Access via **Dashboard → Costs**.
-| Välilehti | Tarkoitus |
-| ----------- | ----------------------------------------------------------------------------------------- |
-|**Budjetti**| Aseta kulutusrajat API-avaimelle päivä-/viikko-/kuukausibudjeteilla ja reaaliaikaisella seurannalla |
-|**Hinnoittelu**| Tarkastele ja muokkaa mallin hinnoittelumerkintöjä – hinta per 1 000 syöttö-/tulostustunnusta toimittajaa kohti |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -764,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Kustannusten seuranta:**Jokainen pyyntö kirjaa tunnuksen käytön ja laskee kustannukset hinnoittelutaulukon avulla. Näytä erittelyt kohdassa**Käyttöpaneeli → Käyttö**tarjoajan, mallin ja API-avaimen mukaan.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute tukee äänen transkriptiota OpenAI-yhteensopivan päätepisteen kautta:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Saatavilla olevat palveluntarjoajat:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Tuetut äänimuodot: "mp3", "wav", "m4a", "flac", "ogg", "webm".---
+---
### Combo Balancing Strategies
-Määritä yhdistelmäkohtainen tasapainotus kohdassa**Käyttöpaneeli → Yhdistelmät → Luo/muokkaa → Strategia**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Strategia | Kuvaus |
-| ------------------- | ------------------------------------------------------------------------- |
-|**Round-Robin**| Pyörii mallien välillä peräkkäin |
-|**Etusija**| Kokeilee aina ensimmäistä mallia; palautuu vain virheen yhteydessä |
-|**Satunnainen**| Valitsee satunnaisen mallin yhdistelmästä jokaiselle pyynnölle |
-|**Painotettu**| Reitit suhteellisesti mallikohtaisten painojen perusteella |
-|**Vähiten käytetty**| Reitit malliin, jolla on vähiten viimeaikaisia pyyntöjä (käyttää yhdistelmämittareita) |
-|**Kustannusoptimoitu**| Reitit halvimpaan saatavilla olevaan malliin (käyttää hinnoittelutaulukkoa) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Yleiset yhdistelmäoletukset voidaan asettaa kohdassa**Kojelauta → Asetukset → Reititys → Yhdistelmäoletukset**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Pääsy kohdasta**Dashboard → Health**. Reaaliaikainen järjestelmän kunnon yleiskatsaus 6 kortilla:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Kortti | Mitä se näyttää |
-| ---------------------- | ------------------------------------------------------------ |
-|**Järjestelmän tila**| Käyttöaika, versio, muistin käyttö, tietohakemisto |
-|**Tarjoajan terveys**| Palveluntarjoajakohtainen katkaisijan tila (suljettu/auki/puoliauki) |
-|**Rate Limits**| Aktiivisen nopeuden rajan viilennyksiä tiliä kohti jäljellä olevan ajan kanssa |
-|**Aktiiviset lukitukset**| Palveluntarjoajat, jotka on tilapäisesti estetty lukituskäytännön vuoksi |
-|**Allekirjoitusvälimuisti**| Päällekkäisyyden poistamisen välimuistitilastot (aktiiviset avaimet, osumaprosentti) |
-|**Viiveen telemetria**| p50/p95/p99 latenssin yhteenlaskettu palveluntarjoajakohtainen |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Provinkki:**Terveys-sivu päivittyy automaattisesti 10 sekunnin välein. Käytä katkaisijakorttia tunnistaaksesi, millä palveluntarjoajilla on ongelmia.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute on saatavana alkuperäisenä työpöytäsovelluksena Windowsille, macOS:lle ja Linuxille.### Asenna
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Asenna
```bash
# From the electron directory:
@@ -832,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -844,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Tulos → `electron/dist-electron/`### Key Features
+Output → `electron/dist-electron/`
-| Ominaisuus | Kuvaus |
-| ---------------------------- | --------------------------------------------------------------------------------- | ------------------------- |
-| **Palvelimen valmius** | Kyselypalvelin ennen ikkunan näyttämistä (ei tyhjää näyttöä) |
-| **Järjestelmälokero** | Pienennä lokeroon, vaihda porttia, sulje lokerovalikosta |
-| **Satamien hallinta** | Vaihda palvelinportti alustasta (käynnistää palvelimen automaattisesti uudelleen) |
-| **Sisällön suojauskäytäntö** | Rajoittava CSP istunnon otsikoiden kautta |
-| **Yksittäinen esiintymä** | Vain yksi sovellusesiintymä voi toimia kerrallaan |
-| **Offline-tila** | Mukana oleva Next.js-palvelin toimii ilman Internetiä | ### Environment Variables |
+### Key Features
-| Muuttuja | Oletus | Kuvaus |
-| --------------------- | ------- | ------------------------------- |
-| "OMNIROUTE_PORT" | "20128" | Palvelinportti |
-| `OMNIROUTE_MEMORY_MB` | "512" | Node.js-keon raja (64–16384 Mt) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Täydellinen dokumentaatio: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/fr/README.md b/docs/i18n/fr/README.md
index f153cfdd91..203ac40e70 100644
--- a/docs/i18n/fr/README.md
+++ b/docs/i18n/fr/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/fr/docs/USER_GUIDE.md b/docs/i18n/fr/docs/USER_GUIDE.md
index 1bcc3e07c2..efdadb135e 100644
--- a/docs/i18n/fr/docs/USER_GUIDE.md
+++ b/docs/i18n/fr/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Guide complet pour configurer les fournisseurs, créer des combos, intégrer des outils CLI et déployer OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Prix en un coup d'oeil](#-pricing-at-a-glance)
-- [Cas d'utilisation](#-cas d'utilisation)
-- [Configuration du fournisseur](#-provider-setup)
-- [Intégration CLI](#-cli-intégration)
-- [Déploiement](#-déploiement)
-- [Modèles disponibles](#-modèles-disponibles)
-- [Fonctionnalités avancées](#-fonctionnalités-avancées)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 Pricing at a Glance
-| Niveau | Fournisseur | Coût | Réinitialisation des quotas | Idéal pour |
-| ----------------- | ------------------ | ------------------------ | --------------------------- | --------------------------------- |
-| **💳 ABONNEMENT** | Claude Code (Pro) | 20 $/mois | 5h + hebdomadaire | Déjà abonné |
-| | Codex (Plus/Pro) | 20-200 $/mois | 5h + hebdomadaire | Utilisateurs d'OpenAI |
-| | CLI Gémeaux | **GRATUIT** | 180K/mois + 1K/jour | Tout le monde! |
-| | Copilote GitHub | 10-19 $/mois | Mensuel | Utilisateurs GitHub |
-| **🔑 CLÉ API** | Recherche profonde | Paiement à l'utilisation | Aucun | Raisonnement bon marché |
-| | Groq | Paiement à l'utilisation | Aucun | Inférence ultra-rapide |
-| | xAI (Grok) | Paiement à l'utilisation | Aucun | Raisonnement Grok 4 |
-| | Mistral | Paiement à l'utilisation | Aucun | Modèles hébergés dans l'UE |
-| | Perplexité | Paiement à l'utilisation | Aucun | Recherche augmentée |
-| | Ensemble IA | Paiement à l'utilisation | Aucun | Modèles open source |
-| | Fireworks AI | Paiement à l'utilisation | Aucun | Images FLUX rapides |
-| | Cérébraux | Paiement à l'utilisation | Aucun | Vitesse à l'échelle d'une tranche |
-| | Cohérer | Paiement à l'utilisation | Aucun | Commande R+ RAG |
-| | NIM NVIDIA | Paiement à l'utilisation | Aucun | Modèles d'entreprise |
-| **💰 BON MARCHÉ** | GLM-4.7 | 0,6 $/1 M | Tous les jours 10h | Sauvegarde budgétaire |
-| | MiniMax M2.1 | 0,2 $/1 M | 5 heures roulantes | Option la moins chère |
-| | Kimi K2 | 9 $/mois plat | 10 millions de jetons/mois | Coût prévisible |
-| **🆓 GRATUIT** | Qoder | 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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Conseil de pro :**Commencez avec Gemini CLI (180 000 $ gratuits/mois) + combo Qoder (gratuit illimité) = 0 $ de coût !---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Problème :**Le quota expire sans être utilisé, limites de débit lors d'un codage intensif```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Problème :**Je ne peux pas payer les abonnements, j'ai besoin d'un codage IA fiable```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Problème :**Délais, je ne peux pas me permettre de temps d'arrêt```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Problème :**Besoin d'un assistant IA dans les applications de messagerie, entièrement gratuit```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**Conseil de pro :**Utilisez Opus pour les tâches complexes, Sonnet pour la rapidité. OmniRoute suit le quota par modèle !#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Meilleur rapport qualité-prix :**Énorme niveau gratuit ! Utilisez-le avant les niveaux payants.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### GLM-4.7 (Daily reset, $0.6/1M)
-1. Inscrivez-vous : [Zhipu AI](https://open.bigmodel.cn/)
-2. Obtenez la clé API du plan de codage
-3. Tableau de bord → Ajouter une clé API : Fournisseur : `glm`, Clé API : `votre-clé`
+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` —**Conseil de pro :**Le plan de codage offre un quota de 3 × à un coût de 1/7 ! Réinitialisation quotidienne à 10h00.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Inscrivez-vous : [MiniMax](https://www.minimax.io/)
-2. Obtenir la clé API → Tableau de bord → Ajouter une clé API
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Utilisez :**`minimax/MiniMax-M2.1` —**Conseil de pro :**Option la moins chère pour un contexte long (1 million de jetons) !#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Abonnez-vous : [Moonshot AI](https://platform.moonshot.ai/)
-2. Obtenir la clé API → Tableau de bord → Ajouter une clé API
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Utilisez :**`kimi/kimi-latest` —**Conseil de pro :**Fixe 9 $/mois pour 10 millions de jetons = 0,90 $/1 million de coût effectif !### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Modifiez `~/.claude/config.json` :```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Modifiez `~/.claude/config.json` :```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Modifiez `~/.openclaw/openclaw.json` :```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Ou utilisez le tableau de bord :**Outils CLI → OpenClaw → Configuration automatique### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-La CLI charge automatiquement « .env » à partir de « ~/.omniroute/.env » ou « ./.env ».### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-Pour les serveurs avec une RAM limitée, utilisez l'option de limite de mémoire :```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Créez `ecosystem.config.js` :```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,13 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-Pour le mode intégré à l'hôte avec les binaires CLI, consultez la section Docker dans la documentation principale.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Les utilisateurs de Void Linux peuvent empaqueter et installer OmniRoute de manière native à l'aide du framework de compilation croisée « xbps-src ». Cela automatise la construction autonome de Node.js ainsi que les liaisons natives « better-sqlite3 » requises.
+### Void Linux (xbps-src)
-
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
-Afficher le modèle xbps-src```bash
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -409,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -476,80 +516,85 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Variables | Par défaut | Descriptif |
+| Variable | Default | Description |
| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | Secret de signature JWT (**changement de production**) |
-| `INITIAL_PASSWORD` | `123456` | Mot de passe de première connexion |
-| `DONNEES_DIR` | `~/.omniroute` | Répertoire de données (base de données, utilisation, journaux) |
-| `PORT` | cadre par défaut | Port de service (`20128` dans les exemples) |
-| `NOM D'HÔTE` | cadre par défaut | Lier l'hôte (Docker par défaut est « 0.0.0.0 ») |
-| `NODE_ENV` | valeur par défaut d'exécution | Définir `production` pour le déploiement |
-| `BASE_URL` | `http://localhost:20128` | URL de base interne côté serveur |
-| `CLOUD_URL` | `https://omniroute.dev` | URL de base du point de terminaison de synchronisation cloud |
-| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Secret HMAC pour les clés API générées |
-| `REQUIRE_API_KEY` | `faux` | Appliquer la clé API Bearer sur `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `faux` | Autoriser Api Manager à copier des clés API complètes à la demande |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | '70' | Cadence d'actualisation côté serveur pour les données de limites du fournisseur mises en cache ; Les boutons d'actualisation de l'interface utilisateur déclenchent toujours la synchronisation manuelle |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `faux` | Désactivez les instantanés SQLite automatiques avant les écritures/importations/restaurations ; les sauvegardes manuelles fonctionnent toujours |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `faux` | Forcer le cookie d'authentification « sécurisé » (derrière le proxy inverse HTTPS) |
-| `CLOUDFLARED_BIN` | non défini | Utiliser un binaire `cloudflared` existant au lieu d'un téléchargement géré |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Transport pour les tunnels rapides gérés (`http2`, `quic` ou `auto`) |
-| `OMNIROUTE_MEMORY_MB` | '512' | Limite de tas Node.js en Mo |
-| `PROMPT_CACHE_MAX_SIZE` | '50' | Nombre maximal d'entrées dans le cache d'invite |
-| `SEMANTIC_CACHE_MAX_SIZE` | '100' | Nombre maximum d'entrées de cache sémantique |Pour la référence complète des variables d'environnement, consultez le [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Afficher tous les modèles disponibles
+
+View all available models
-**Claude Code (`cc/`)**— Pro/Max : `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro : `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— GRATUIT : `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**Copilote GitHub (`gh/`)** : `gh/gpt-5`, `gh/claude-4.5-sonnet`
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— 0,6 $/1 million : `glm/glm-4.7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— 0,2 $/1 million : `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— GRATUIT : `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— GRATUIT : `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— GRATUIT : `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
-**DeepSeek (`ds/`)** : `ds/deepseek-chat`, `ds/deepseek-reasoner`
+**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
-**Groq (`groq/`)** : `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
+**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
-**xAI (`xai/`)** : `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
+**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
-**Mistral (`mistral/`)** : `mistral/mistral-large-2501`, `mistral/codestral-2501`
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Perplexité (`pplx/`)** : `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**Ensemble AI (`ensemble/`)** : `ensemble/méta-llama/Llama-3.3-70B-Instruct-Turbo`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**Fireworks AI (`fireworks/`)** : `fireworks/accounts/fireworks/models/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**Cérébras (`cerebras/`)** : `cerebras/llama-3.3-70b`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
-**Cohérer (`cohere/`)** : `cohere/command-r-plus-08-2024`
+**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)** : `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -557,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Ajoutez n'importe quel ID de modèle à n'importe quel fournisseur sans attendre une mise à jour de l'application :```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -565,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Ou utilisez le tableau de bord :**Fournisseurs → [Fournisseur] → Modèles personnalisés**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Remarques :
+Notes:
-- Les fournisseurs compatibles OpenRouter et OpenAI/Anthropic sont gérés à partir de**Modèles disponibles**uniquement. L'ajout manuel, l'importation et la synchronisation automatique se retrouvent tous dans la même liste de modèles disponibles, il n'y a donc pas de section Modèles personnalisés distincte pour ces fournisseurs.
-- La section**Modèles personnalisés**est destinée aux fournisseurs qui n'exposent pas les importations de modèles disponibles gérés.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Acheminez les demandes directement vers un fournisseur spécifique avec validation du modèle :```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Le préfixe du fournisseur est ajouté automatiquement s'il est manquant. Les modèles incompatibles renvoient « 400 ».### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -595,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Précédence :**Spécifique à la clé → Spécifique au combo → Spécifique au fournisseur → Global → Environnement.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Renvoie des modèles regroupés par fournisseur avec des types (`chat`, `embedding`, `image`).### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Synchronisez les fournisseurs, les combos et les paramètres sur tous les appareils
-- Synchronisation automatique en arrière-plan avec délai d'attente + échec rapide
-- Préférer `BASE_URL`/`CLOUD_URL` côté serveur en production### Cloudflare Quick Tunnel
+### Cloud Sync
-- Disponible dans**Dashboard → Endpoints**pour Docker et autres déploiements auto-hébergés
-- Crée une URL temporaire `https://*.trycloudflare.com` qui redirige vers votre point de terminaison `/v1` actuel compatible OpenAI
-- Activez d'abord les installations « cloudflared » uniquement lorsque cela est nécessaire ; les redémarrages ultérieurs réutilisent le même binaire géré
-- Les tunnels rapides ne sont pas automatiquement restaurés après un redémarrage d'OmniRoute ou d'un conteneur ; réactivez-les depuis le tableau de bord en cas de besoin
-- Les URL des tunnels sont éphémères et changent à chaque fois que vous arrêtez/démarrez le tunnel
-- Les tunnels rapides gérés utilisent par défaut le transport HTTP/2 pour éviter les avertissements de tampon QUIC UDP bruyants dans les conteneurs contraints
-- Définissez `CLOUDFLARED_PROTOCOL=quic` ou `auto` si vous souhaitez remplacer le choix de transport géré
-- Définissez `CLOUDFLARED_BIN` si vous préférez utiliser un binaire `cloudflared` préinstallé au lieu du téléchargement géré### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Cache sémantique**— Met automatiquement en cache les réponses hors streaming, température = 0 (contourner avec `X-OmniRoute-No-Cache : true`) -**Request Idempotency**— Déduplique les requêtes dans les 5 secondes via l'en-tête `Idempotency-Key` ou `X-Request-Id` -**Suivi des progrès**— Événements SSE `event: progress` opt-in via l'en-tête `X-OmniRoute-Progress: true`---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Accès via**Tableau de bord → Traducteur**. Déboguez et visualisez comment OmniRoute traduit les requêtes API entre les fournisseurs.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Mode | Objectif |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------- |
-| **Aire de jeux** | Sélectionnez les formats source/cible, collez une requête et voyez instantanément le résultat traduit |
-| **Testeur de chat** | Envoyez des messages de chat en direct via le proxy et inspectez le cycle complet de demande/réponse |
-| **Banc d'essai** | Exécutez des tests par lots sur plusieurs combinaisons de formats pour vérifier l'exactitude de la traduction |
-| **Moniteur en direct** | Regardez les traductions en temps réel à mesure que les demandes transitent par le proxy |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Cas d'utilisation :**
+**Use cases:**
-- Déboguer pourquoi une combinaison client/fournisseur spécifique échoue
-- Vérifiez que les balises de réflexion, les appels d'outils et les invites système se traduisent correctement
-- Comparez les différences de format entre les formats API OpenAI, Claude, Gemini et Responses---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Configurez via**Tableau de bord → Paramètres → Routage**.
+Configure via **Dashboard → Settings → Routing**.
-| Stratégie | Descriptif |
-| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Remplir en premier** | Utilise les comptes par ordre de priorité : le compte principal gère toutes les demandes jusqu'à ce qu'il soit indisponible |
-| **Tournoi à la ronde** | Parcourt tous les comptes avec une limite persistante configurable (par défaut : 3 appels par compte) |
-| **P2C (Puissance de deux choix)** | Sélectionne 2 comptes aléatoires et oriente vers le compte le plus sain – équilibre la charge avec la conscience de la santé |
-| **Aléatoire** | Sélectionne au hasard un compte pour chaque demande à l'aide de Fisher-Yates shuffle |
-| **Le moins utilisé** | Routes vers le compte avec l'horodatage `lastUsedAt` le plus ancien, répartissant le trafic de manière uniforme |
-| **Coût optimisé** | Itinéraires vers le compte avec la valeur de priorité la plus faible, optimisation pour les fournisseurs les moins chers | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Pour une affinité de session externe (par exemple, agents Claude Code/Codex derrière des proxys inverses), envoyez :```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute accepte également `x_session_id` et renvoie la clé de session effective dans `X-OmniRoute-Session-Id`.
+If you use Nginx and send underscore-form headers, enable:
-Si vous utilisez Nginx et envoyez des en-têtes de formulaire de soulignement, activez :```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Créez des modèles génériques pour remapper les noms de modèles :```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Les caractères génériques prennent en charge `*` (n'importe quel caractère) et `?` (un seul caractère).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Définissez des chaînes de secours globales qui s'appliquent à toutes les requêtes :```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Configurez via**Tableau de bord → Paramètres → Résilience**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute met en œuvre la résilience au niveau du fournisseur avec quatre composants :
+OmniRoute implements provider-level resilience with four components:
-1.**Profils de fournisseur**— Configuration par fournisseur pour :
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Seuil de défaillance (combien de défaillances avant ouverture)
-- Durée du temps de recharge
-- Sensibilité de détection de limite de débit
-- Paramètres d'intervalle exponentiel
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Limites de débit modifiables**— Paramètres par défaut au niveau du système configurables dans le tableau de bord : -**Requêtes par minute (RPM)**— Nombre maximal de requêtes par minute et par compte -**Min Time Between Requests**— Écart minimum en millisecondes entre les requêtes -**Max Concurrent Requests**— Nombre maximal de requêtes simultanées par compte
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Cliquez sur**Modifier**pour modifier, puis sur**Enregistrer**ou**Annuler**. Les valeurs persistent via l'API de résilience.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Disjoncteur**— Suit les pannes par fournisseur et ouvre automatiquement le circuit lorsqu'un seuil est atteint : -**FERMÉ**(sain) — Les demandes circulent normalement -**OPEN**— Le fournisseur est temporairement bloqué après des échecs répétés -**HALF_OPEN**— Test si le fournisseur a récupéré
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Politiques et identifiants verrouillés**— Affiche l'état du disjoncteur et les identifiants verrouillés avec capacité de déverrouillage forcé.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Détection automatique des limites de débit**— Surveille les en-têtes « 429 » et « Retry-After » pour éviter de manière proactive d'atteindre les limites de débit du fournisseur.
-
-**Conseil de pro :**Utilisez le bouton**Réinitialiser tout**pour effacer tous les disjoncteurs et les temps de recharge lorsqu'un fournisseur se remet d'une panne.---
+---
### Database Export / Import
-Gérez les sauvegardes de base de données dans**Tableau de bord → Paramètres → Système et stockage**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Actions | Descriptif |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
-| **Exporter la base de données** | Télécharge la base de données SQLite actuelle sous forme de fichier `.sqlite` |
-| **Exporter tout (.tar.gz)** | Télécharge une archive de sauvegarde complète comprenant : base de données, paramètres, combos, connexions du fournisseur (pas d'informations d'identification), métadonnées de la clé API |
-| **Importer la base de données** | Téléchargez un fichier `.sqlite` pour remplacer la base de données actuelle. Une sauvegarde de pré-importation est automatiquement créée sauf si `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Validation de l'importation :**Le fichier importé est validé pour son intégrité (vérification pragma SQLite), les tables requises (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) et la taille (max 100 Mo).
+**Use Cases:**
-**Cas d'utilisation :**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Migrer OmniRoute entre machines
-- Créer des sauvegardes externes pour la reprise après sinistre
-- Partager les configurations entre les membres de l'équipe (exporter tout → partager l'archive)---
+---
### Settings Dashboard
-La page des paramètres est organisée en 6 onglets pour une navigation facile :
+The settings page is organized into 6 tabs for easy navigation:
-| Onglet | Contenu |
-| ---------- | ------------------------------------------------------------------------------------------------------------- |
-|**Général**| Outils de stockage système, paramètres d'apparence, commandes de thème et visibilité de la barre latérale par élément |
-|**Sécurité**| Paramètres de connexion/mot de passe, contrôle d'accès IP, authentification API pour `/models` et blocage du fournisseur |
-|**Routage**| Stratégie de routage globale (6 options), alias de modèle générique, chaînes de secours, valeurs par défaut combinées |
-|**Résilience**| Profils de fournisseurs, limites de débit modifiables, état du disjoncteur, politiques et identifiants verrouillés |
-|**IA**| Configuration du budget de réflexion, injection d'invite du système global, statistiques de cache d'invite |
-|**Avancé**| Configuration globale du proxy (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Accès via**Tableau de bord → Coûts**.
+Access via **Dashboard → Costs**.
-| Onglet | Objectif |
-| ----------- | --------------------------------------------------------------------------------------------- |
-|**Budget**| Fixez des limites de dépenses par clé API avec des budgets quotidiens/hebdomadaires/mensuels et un suivi en temps réel |
-|**Tarif**| Afficher et modifier les entrées de tarification du modèle — coût par 1 000 jetons d'entrée/sortie par fournisseur |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -766,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Suivi des coûts :**Chaque demande enregistre l'utilisation du jeton et calcule le coût à l'aide du tableau de tarification. Affichez les répartitions dans**Tableau de bord → Utilisation**par fournisseur, modèle et clé API.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute prend en charge la transcription audio via le point de terminaison compatible OpenAI :```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Fournisseurs disponibles :**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Formats audio pris en charge : `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.---
+---
### Combo Balancing Strategies
-Configurez l'équilibrage par combo dans**Tableau de bord → Combos → Créer/Modifier → Stratégie**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Stratégie | Descriptif |
+| Strategy | Description |
| ------------------ | ------------------------------------------------------------------------ |
-|**Robin à la ronde**| Tourne à travers les modèles de manière séquentielle |
-|**Priorité**| Essaie toujours le premier modèle ; se rabat uniquement sur l'erreur |
-|**Aléatoire**| Sélectionne un modèle aléatoire dans le combo pour chaque demande |
-|**Pondéré**| Itinéraires proportionnellement basés sur les poids attribués par modèle |
-|**Les moins utilisés**| Itinéraires vers le modèle avec le moins de requêtes récentes (utilise des métriques combinées) |
-|**Coût optimisé**| Itinéraires vers le modèle disponible le moins cher (utilise le tableau de prix) |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Les valeurs par défaut des combos globaux peuvent être définies dans**Tableau de bord → Paramètres → Routage → Paramètres par défaut des combos**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Accès via**Tableau de bord → Santé**. Aperçu de l'état du système en temps réel avec 6 cartes :
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Carte | Ce que cela montre |
-| ------------------------------------ | ----------------------------------------------------------- |
-|**État du système**| Disponibilité, version, utilisation de la mémoire, répertoire de données |
-|**Santé du fournisseur**| État du disjoncteur par fournisseur (Fermé/Ouvert/Semi-ouvert) |
-|**Limites de taux**| Temps de recharge de la limite de débit actif par compte avec temps restant |
-|**Verrouillages actifs**| Fournisseurs temporairement bloqués par la politique de verrouillage |
-|**Cache de signatures**| Statistiques du cache de déduplication (clés actives, taux de réussite) |
-|**Télémétrie de latence**| Agrégation de latence p50/p95/p99 par fournisseur |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Conseil de pro :**La page Santé s'actualise automatiquement toutes les 10 secondes. Utilisez la carte disjoncteur pour identifier les fournisseurs qui rencontrent des problèmes.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute est disponible en tant qu'application de bureau native pour Windows, macOS et Linux.### Installer
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Installer
```bash
# From the electron directory:
@@ -834,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -846,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Sortie → `électron/dist-électron/`### Key Features
+Output → `electron/dist-electron/`
-| Fonctionnalité | Descriptif |
-| ------------------------------------ | ----------------------------------------------------------------------------------- | ------------------------- |
-| **Préparation du serveur** | Interroge le serveur avant d'afficher la fenêtre (pas d'écran vide) |
-| **Barre d'état système** | Réduire dans la barre d'état, changer de port, quitter le menu de la barre d'état |
-| **Gestion portuaire** | Changer le port du serveur à partir du plateau (redémarrage automatique du serveur) |
-| **Politique de sécurité du contenu** | CSP restrictif via les en-têtes de session |
-| **Instance unique** | Une seule instance d'application peut être exécutée à la fois |
-| **Mode hors ligne** | Le serveur Next.js fourni fonctionne sans Internet | ### Environment Variables |
+### Key Features
-| Variable | Default | Descriptif |
-| --------------------- | ------- | -------------------------------------- |
-| `OMNIROUTE_PORT` | `20128` | Port du serveur |
-| `OMNIROUTE_MEMORY_MB` | `512` | Limite de tas Node.js (64 à 16 384 Mo) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Documentation complète : [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/he/README.md b/docs/i18n/he/README.md
index 15baf770bf..12067ef4e2 100644
--- a/docs/i18n/he/README.md
+++ b/docs/i18n/he/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/he/docs/USER_GUIDE.md b/docs/i18n/he/docs/USER_GUIDE.md
index af8d74cf5a..31dfc8defd 100644
--- a/docs/i18n/he/docs/USER_GUIDE.md
+++ b/docs/i18n/he/docs/USER_GUIDE.md
@@ -4,6 +4,8 @@
---
+
+
Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
---
@@ -223,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -339,6 +343,17 @@ omniroute --port 3000
The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### VPS Deployment
```bash
diff --git a/docs/i18n/hi/README.md b/docs/i18n/hi/README.md
index ddb8df27a1..c550e21736 100644
--- a/docs/i18n/hi/README.md
+++ b/docs/i18n/hi/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/hi/docs/USER_GUIDE.md b/docs/i18n/hi/docs/USER_GUIDE.md
index 169b832144..9f69b72793 100644
--- a/docs/i18n/hi/docs/USER_GUIDE.md
+++ b/docs/i18n/hi/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-प्रदाताओं को कॉन्फ़िगर करने, कॉम्बो बनाने, सीएलआई टूल को एकीकृत करने और ओमनीरूट को तैनात करने के लिए संपूर्ण मार्गदर्शिका।---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [मूल्य निर्धारण एक नजर में](#-मूल्य निर्धारण एक नजर में)
-- [उपयोग मामले](#-उपयोग मामले)
-- [प्रदाता सेटअप](#-प्रदाता-सेटअप)
-- [सीएलआई एकीकरण](#-सीएलआई-एकीकरण)
-- [तैनाती](#-तैनाती)
-- [उपलब्ध मॉडल](#-उपलब्ध-मॉडल)
-- [उन्नत सुविधाएँ](#-उन्नत-सुविधाएँ)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 Pricing at a Glance
-| टियर | प्रदाता | लागत | कोटा रीसेट | के लिए सर्वश्रेष्ठ |
-| ----------------- | ------------------- | ----------------------- | -------------------- | ---------------------------- |
-| **💳 सदस्यता** | क्लाउड कोड (प्रो) | $20/माह | 5 घंटे + साप्ताहिक | पहले ही सदस्यता ले ली है |
-| | कोडेक्स (प्लस/प्रो) | $20-200/महीना | 5 घंटे + साप्ताहिक | OpenAI उपयोगकर्ता |
-| | जेमिनी सीएलआई | **मुफ़्त** | 180K/माह + 1K/दिन | सब लोग! |
-| | गिटहब कोपायलट | $10-19/माह | मासिक | GitHub users |
-| **🔑एपीआई कुंजी** | डीपसीक | प्रति उपयोग भुगतान करें | कोई नहीं | सस्ता तर्क |
-| | ग्रोक | प्रति उपयोग भुगतान करें | कोई नहीं | अल्ट्रा-फास्ट अनुमान |
-| | एक्सएआई (ग्रोक) | प्रति उपयोग भुगतान करें | कोई नहीं | ग्रोक 4 तर्क |
-| | मिस्ट्रल | प्रति उपयोग भुगतान करें | कोई नहीं | ईयू द्वारा होस्ट किए गए मॉडल |
-| | उलझन | प्रति उपयोग भुगतान करें | कोई नहीं | खोज-संवर्धित |
-| | एक साथ एआई | प्रति उपयोग भुगतान करें | कोई नहीं | ओपन-सोर्स मॉडल |
-| | आतिशबाजी एआई | प्रति उपयोग भुगतान करें | कोई नहीं | फास्ट फ्लक्स छवियां |
-| | सेरेब्रस | प्रति उपयोग भुगतान करें | कोई नहीं | वेफर-स्केल गति |
-| | सहभागी | प्रति उपयोग भुगतान करें | कोई नहीं | कमांड आर+आरएजी |
-| | एनवीडिया एनआईएम | प्रति उपयोग भुगतान करें | कोई नहीं | एंटरप्राइज़ मॉडल |
-| **💰सस्ता** | जीएलएम-4.7 | $0.6/1 मिलियन | प्रतिदिन सुबह 10 बजे | बजट बैकअप |
-| | मिनीमैक्स एम2.1 | $0.2/1 मिलियन | 5 घंटे की रोलिंग | सबसे सस्ता विकल्प |
-| | किमी K2 | $9/महीना फ्लैट | 10एम टोकन/माह | अनुमानित लागत |
-| **🆓 मुफ़्त** | कोडर | $0 | Unlimited | 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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡प्रो टिप:**जेमिनी सीएलआई (180K मुफ़्त/माह) + कोडर (असीमित मुफ़्त) कॉम्बो = $0 लागत से शुरू करें!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**समस्या:**भारी कोडिंग के दौरान कोटा अप्रयुक्त, दर सीमा समाप्त हो जाता है```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**समस्या:**सदस्यताएं वहन नहीं कर सकते, विश्वसनीय एआई कोडिंग की आवश्यकता है```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**समस्या:**समय सीमा, डाउनटाइम बर्दाश्त नहीं कर सकते```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**समस्या:**मैसेजिंग ऐप्स में AI सहायक की आवश्यकता है, पूरी तरह से निःशुल्क```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**प्रो टिप:**जटिल कार्यों के लिए ओपस और गति के लिए सॉनेट का उपयोग करें। ओमनीरूट प्रति मॉडल कोटा ट्रैक करता है!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**सर्वोत्तम मूल्य:**विशाल निःशुल्क स्तर! सशुल्क स्तरों से पहले इसका उपयोग करें।#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### GLM-4.7 (Daily reset, $0.6/1M)
-1. साइन अप करें: [झिपु एआई](https://open.bigmodel.cn/)
-2. कोडिंग योजना से एपीआई कुंजी प्राप्त करें
-3. डैशबोर्ड → एपीआई कुंजी जोड़ें: प्रदाता: `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` -**प्रो टिप:**कोडिंग प्लान 1/7 लागत पर 3× कोटा प्रदान करता है! प्रतिदिन सुबह 10:00 बजे रीसेट करें।#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. साइन अप करें: [मिनीमैक्स](https://www.minimax.io/)
-2. एपीआई कुंजी प्राप्त करें → डैशबोर्ड → एपीआई कुंजी जोड़ें
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**उपयोग करें:**`मिनीमैक्स/मिनीमैक्स-एम2.1` -**प्रो टिप:**लंबे संदर्भ के लिए सबसे सस्ता विकल्प (1एम टोकन)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. सदस्यता लें: [मूनशॉट एआई](https://platform.moonshot.ai/)
-2. एपीआई कुंजी प्राप्त करें → डैशबोर्ड → एपीआई कुंजी जोड़ें
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**उपयोग:**`किमी/किमी-नवीनतम` -**प्रो टिप:**10एम टोकन के लिए निश्चित $9/माह = $0.90/1एम प्रभावी लागत!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-`~/.claude/config.json` संपादित करें:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Settings → Models → Advanced:
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-`~/.openclaw/openclaw.json` संपादित करें:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**या डैशबोर्ड का उपयोग करें:**सीएलआई टूल्स → ओपनक्लॉ → ऑटो-कॉन्फ़िगरेशन### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-सीएलआई स्वचालित रूप से `.env` को `~/.omniroute/.env` या `./.env` से लोड करता है।### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-सीमित रैम वाले सर्वर के लिए, मेमोरी सीमा विकल्प का उपयोग करें:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-`ecosystem.config.js` बनाएं:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,15 +420,17 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-सीएलआई बायनेरिज़ के साथ होस्ट-एकीकृत मोड के लिए, मुख्य दस्तावेज़ में डॉकर अनुभाग देखें।### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-शून्य लिनक्स उपयोगकर्ता `xbps-src` क्रॉस-संकलन ढांचे का उपयोग करके मूल रूप से ओमनीरूट को पैकेज और इंस्टॉल कर सकते हैं। यह आवश्यक `better-sqlite3` मूल बाइंडिंग के साथ Node.js स्टैंडअलोन बिल्ड को स्वचालित करता है।
+### Void Linux (xbps-src)
-<विवरण>
-<सारांश>xbps-src टेम्पलेट देखें```bash
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
-
pkgname=omniroute
version=3.2.4
revision=1
@@ -402,7 +442,7 @@ license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
-system_accounts="\_omniroute"
+system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
@@ -410,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -477,80 +516,85 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| परिवर्तनीय | डिफ़ॉल्ट | विवरण |
-| ------------------------------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `सर्वव्यापी-डिफ़ॉल्ट-गुप्त-परिवर्तन-मुझे` | JWT हस्ताक्षर रहस्य (**उत्पादन में परिवर्तन**) |
-| `प्रारंभिक_पासवर्ड` | `123456` | पहला लॉगिन पासवर्ड |
-| `DATA_DIR` | `~/.omniroute` | डेटा निर्देशिका (डीबी, उपयोग, लॉग) |
-| `पोर्ट` | फ्रेमवर्क डिफ़ॉल्ट | सर्विस पोर्ट (उदाहरणों में `20128`) |
-| `होस्टनाम` | फ्रेमवर्क डिफ़ॉल्ट | बाइंड होस्ट (डॉकर डिफ़ॉल्ट `0.0.0.0`) |
-| `NODE_ENV` | रनटाइम डिफ़ॉल्ट | तैनाती के लिए 'उत्पादन' सेट करें |
-| `बेस_यूआरएल` | `http://localhost:20128` | सर्वर-साइड आंतरिक आधार URL |
-| `CLOUD_URL` | `https://omniroute.dev` | क्लाउड सिंक एंडपॉइंट बेस यूआरएल |
-| `API_KEY_SECRET` | `एंडपॉइंट-प्रॉक्सी-एपीआई-की-सीक्रेट` | जेनरेट की गई एपीआई कुंजियों के लिए एचएमएसी रहस्य |
-| `REQUIRE_API_KEY` | 'झूठा' | `/v1/*` पर बियरर एपीआई कुंजी लागू करें |
-| `अनुमति_एपीआई_कुंजी_प्रकटीकरण` | 'झूठा' | एपीआई प्रबंधक को मांग पर पूर्ण एपीआई कुंजियाँ कॉपी करने की अनुमति दें |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | कैश्ड प्रदाता सीमा डेटा के लिए सर्वर-साइड ताज़ा ताल; यूआई रीफ्रेश बटन अभी भी मैन्युअल सिंक ट्रिगर करते हैं |
-| `DISABLE_SQLITE_AUTO_BACKUP` | 'झूठा' | लिखने/आयात/पुनर्स्थापित करने से पहले स्वचालित SQLite स्नैपशॉट अक्षम करें; मैन्युअल बैकअप अभी भी काम करते हैं |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | 'झूठा' | `सिक्योर` ऑथ कुकी को बाध्य करें (एचटीटीपीएस रिवर्स प्रॉक्सी के पीछे) |
-| `CLOUDFLARED_BIN` | परेशान | प्रबंधित डाउनलोड के बजाय मौजूदा `क्लाउडफ्लेयर्ड` बाइनरी का उपयोग करें
-| `क्लाउडफ्लेयर्ड_प्रोटोकॉल` | `http2` | प्रबंधित त्वरित सुरंगों के लिए परिवहन ('http2', 'त्वरित', या 'ऑटो') |
-| `OMNIROUTE_MEMORY_MB` | `512` | MB में Node.js हीप सीमा |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | अधिकतम शीघ्र कैश प्रविष्टियाँ |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | अधिकतम सिमेंटिक कैश प्रविष्टियाँ |संपूर्ण पर्यावरण चर संदर्भ के लिए, [README](../README.md) देखें।---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-<विवरण>
-<सारांश>सभी उपलब्ध मॉडल देखें
+
+View all available models
-**क्लाउड कोड (`cc/`)**— प्रो/मैक्स: `cc/क्लाउड-ओपस-4-6`, `cc/क्लाउड-सोनेट-4-5-20250929`, `cc/क्लाउड-हाइकु-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**कोडेक्स (`सीएक्स/`)**— प्लस/प्रो: `सीएक्स/जीपीटी-5.2-कोडेक्स`, `सीएक्स/जीपीटी-5.1-कोडेक्स-मैक्स`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**मिथुन सीएलआई (`gc/`)**— मुफ़्त: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**गिटहब कोपायलट (`gh/`)**: `gh/gpt-5`, `gh/क्लाउड-4.5-सॉनेट`
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**जीएलएम (`जीएलएम/`)**— $0.6/1एम: `जीएलएम/जीएलएम-4.7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**मिनीमैक्स (`मिनीमैक्स/`)**— $0.2/1 मिलियन: `मिनीमैक्स/मिनीमैक्स-एम2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— मुफ़्त: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/depseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**क्वेन (`qw/`)**— मुफ़्त: `qw/qwen3-कोडर-प्लस`, `qw/qwen3-कोडर-फ़्लैश`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**किरो (`kr/`)**— मुफ़्त: `kr/क्लाउड-सॉनेट-4.5`, `kr/क्लाउड-हाइकु-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
-**ग्रोक (`ग्रोक/`)**: `ग्रोक/लामा-3.3-70बी-बहुमुखी`, `ग्रोक/लामा-4-मेवरिक-17बी-128ई-इंस्ट्रक्ट`
+**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
-**मिस्ट्रल (`मिस्ट्रल/`)**: `मिस्ट्रल/मिस्ट्रल-लार्ज-2501`, `मिस्ट्रल/कोडेस्ट्रल-2501`
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**व्याकुलता (`पीपीएलएक्स/`)**: `पीपीएलएक्स/सोनार-प्रो`, `पीपीएलएक्स/सोनार`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**टुगेदर एआई (`टुगेदर/`)**: `टुगेदर/मेटा-लामा/लामा-3.3-70बी-इंस्ट्रक्ट-टर्बो`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**आतिशबाज़ी एआई (`आतिशबाज़ी/`)**: `आतिशबाजी/खाते/आतिशबाज़ी/मॉडल/डीपसीक-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**सेरेब्रस (`सेरेब्रस/`)**: `सेरेब्रस/लामा-3.3-70बी`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -558,7 +602,9 @@ vlicense LICENSE
### Custom Models
-ऐप अपडेट की प्रतीक्षा किए बिना किसी भी प्रदाता से कोई भी मॉडल आईडी जोड़ें:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -566,22 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-या डैशबोर्ड का उपयोग करें:**प्रदाता → [प्रदाता] → कस्टम मॉडल**।
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-टिप्पणियाँ:
+Notes:
-- ओपनराउटर और ओपनएआई/एंथ्रोपिक-संगत प्रदाताओं को केवल**उपलब्ध मॉडल**से प्रबंधित किया जाता है। मैन्युअल ऐड, आयात और ऑटो-सिंक सभी एक ही उपलब्ध-मॉडल सूची में आते हैं, इसलिए उन प्रदाताओं के लिए कोई अलग कस्टम मॉडल अनुभाग नहीं है। -**कस्टम मॉडल**अनुभाग उन प्रदाताओं के लिए है जो प्रबंधित उपलब्ध-मॉडल आयात को उजागर नहीं करते हैं।### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-मॉडल सत्यापन के साथ सीधे एक विशिष्ट प्रदाता को रूट अनुरोध:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-गायब होने पर प्रदाता उपसर्ग स्वतः जुड़ जाता है। बेमेल मॉडल `400` लौटाते हैं।### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -595,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**प्राथमिकता:**कुंजी-विशिष्ट → कॉम्बो-विशिष्ट → प्रदाता-विशिष्ट → वैश्विक → पर्यावरण।### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-प्रदाता द्वारा प्रकारों (`चैट`, `एम्बेडिंग`, `छवि`) के साथ समूहीकृत मॉडल लौटाता है।### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- सभी डिवाइसों में सिंक प्रदाता, कॉम्बो और सेटिंग्स
-- टाइमआउट + फेल-फास्ट के साथ स्वचालित पृष्ठभूमि सिंक
-- उत्पादन में सर्वर-साइड `BASE_URL`/`CLOUD_URL` को प्राथमिकता दें### Cloudflare Quick Tunnel
+### Cloud Sync
-- डॉकर और अन्य स्व-होस्टेड परिनियोजन के लिए**डैशबोर्ड → एंडपॉइंट**में उपलब्ध है
-- एक अस्थायी `https://*.trycloudflare.com` URL बनाता है जो आपके वर्तमान OpenAI-संगत `/v1` समापन बिंदु पर अग्रेषित होता है
-- सबसे पहले जरूरत पड़ने पर ही `क्लाउडफ्लेयर` इंस्टॉल सक्षम करें; बाद में पुनरारंभ उसी प्रबंधित बाइनरी का पुन: उपयोग करता है
-- ओम्निरूट या कंटेनर पुनरारंभ के बाद त्वरित सुरंगें स्वतः बहाल नहीं होती हैं; आवश्यकता पड़ने पर उन्हें डैशबोर्ड से पुनः सक्षम करें
-- टनल यूआरएल अल्पकालिक होते हैं और हर बार जब आप टनल रोकते/शुरू करते हैं तो बदल जाते हैं
-- प्रबंधित त्वरित सुरंगें प्रतिबंधित कंटेनरों में शोर वाले QUIC UDP बफर चेतावनियों से बचने के लिए HTTP/2 परिवहन के लिए डिफ़ॉल्ट हैं।
-- यदि आप प्रबंधित परिवहन विकल्प को ओवरराइड करना चाहते हैं तो `CLOUDFLARED_PROTOCOL=quic` या `auto` सेट करें
-- यदि आप प्रबंधित डाउनलोड के बजाय पूर्वस्थापित `क्लाउडफ्लेयर्ड` बाइनरी का उपयोग करना पसंद करते हैं तो `CLOUDFLARED_BIN` सेट करें### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**सिमेंटिक कैश**- ऑटो-कैश नॉन-स्ट्रीमिंग, तापमान = 0 प्रतिक्रियाएँ ('एक्स-ओमनीरूट-नो-कैश: ट्रू' के साथ बायपास) -**अनुरोध Idempotency**- `Idempotency-Key` या `X-Request-Id` हेडर के माध्यम से 5 सेकंड के भीतर अनुरोधों को हटा देता है -**प्रगति ट्रैकिंग**- ऑप्ट-इन एसएसई `इवेंट: प्रगति` इवेंट `X-OmniRoute-Progress: true` हेडर के माध्यम से---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-**डैशबोर्ड → अनुवादक**के माध्यम से पहुंच। डीबग करें और कल्पना करें कि कैसे ओमनीरूट प्रदाताओं के बीच एपीआई अनुरोधों का अनुवाद करता है।
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| मोड | उद्देश्य |
-| ---------------- | -------------------------------------------------------------------------------------------- |
-| **खेल का मैदान** | स्रोत/लक्ष्य प्रारूप चुनें, एक अनुरोध चिपकाएँ, और अनुवादित आउटपुट तुरंत देखें |
-| **चैट परीक्षक** | प्रॉक्सी के माध्यम से लाइव चैट संदेश भेजें और पूर्ण अनुरोध/प्रतिक्रिया चक्र का निरीक्षण करें |
-| **टेस्ट बेंच** | अनुवाद की शुद्धता को सत्यापित करने के लिए कई प्रारूप संयोजनों में बैच परीक्षण चलाएँ |
-| **लाइव मॉनिटर** | प्रॉक्सी के माध्यम से अनुरोध प्रवाहित होने पर वास्तविक समय में अनुवाद देखें |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**उपयोग के मामले:**
+**Use cases:**
-- डीबग करें कि कोई विशिष्ट ग्राहक/प्रदाता संयोजन विफल क्यों होता है
-- सत्यापित करें कि थिंकिंग टैग, टूल कॉल और सिस्टम प्रॉम्प्ट सही ढंग से अनुवाद करते हैं
-- ओपनएआई, क्लाउड, जेमिनी और रिस्पॉन्स एपीआई प्रारूपों के बीच प्रारूप अंतर की तुलना करें---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-**डैशबोर्ड → सेटिंग्स → रूटिंग**के माध्यम से कॉन्फ़िगर करें।
+Configure via **Dashboard → Settings → Routing**.
-| रणनीति | विवरण |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
-| **पहले भरें** | प्राथमिकता क्रम में खातों का उपयोग करता है - प्राथमिक खाता अनुपलब्ध होने तक सभी अनुरोधों को संभालता है |
-| **राउंड रॉबिन** | एक विन्यास योग्य चिपचिपा सीमा के साथ सभी खातों के माध्यम से चक्र (डिफ़ॉल्ट: प्रति खाता 3 कॉल) |
-| **पी2सी (दो विकल्पों की शक्ति)** | 2 यादृच्छिक खाते चुनता है और स्वस्थ खाते की ओर ले जाता है - स्वास्थ्य के प्रति जागरूकता के साथ भार संतुलित करता है |
-| **यादृच्छिक** | फिशर-येट्स शफल | का उपयोग करके प्रत्येक अनुरोध के लिए यादृच्छिक रूप से एक खाता चुनता है |
-| **कम से कम इस्तेमाल** | सबसे पुराने `lastUsedAt` टाइमस्टैम्प के साथ खाते तक रूट, ट्रैफ़िक को समान रूप से वितरित करना |
-| **लागत अनुकूलित** | सबसे कम लागत वाले प्रदाताओं के लिए अनुकूलन, सबसे कम प्राथमिकता मूल्य वाले खाते तक रूट | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-बाहरी सत्र एफ़िनिटी के लिए (उदाहरण के लिए, रिवर्स प्रॉक्सी के पीछे क्लाउड कोड/कोडेक्स एजेंट), भेजें:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-ओमनीरूट `x_session_id` को भी स्वीकार करता है और `X-OmniRoute-Session-Id` में प्रभावी सत्र कुंजी लौटाता है।
+If you use Nginx and send underscore-form headers, enable:
-यदि आप Nginx का उपयोग करते हैं और अंडरस्कोर-फॉर्म हेडर भेजते हैं, तो सक्षम करें:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-मॉडल नामों को रीमैप करने के लिए वाइल्डकार्ड पैटर्न बनाएं:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-वाइल्डकार्ड `*` (कोई भी वर्ण) और `?` (एकल वर्ण) का समर्थन करते हैं।#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-वैश्विक फ़ॉलबैक श्रृंखलाओं को परिभाषित करें जो सभी अनुरोधों पर लागू होती हैं:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-**डैशबोर्ड → सेटिंग्स → लचीलापन**के माध्यम से कॉन्फ़िगर करें।
+Configure via **Dashboard → Settings → Resilience**.
-ओमनीरूट चार घटकों के साथ प्रदाता-स्तरीय लचीलापन लागू करता है:
+OmniRoute implements provider-level resilience with four components:
-1.**प्रदाता प्रोफाइल**- प्रति-प्रदाता कॉन्फ़िगरेशन:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- विफलता सीमा (उद्घाटन से पहले कितनी विफलताएँ)
-- कूलडाउन अवधि
-- दर सीमा का पता लगाने की संवेदनशीलता
-- घातीय बैकऑफ़ पैरामीटर
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**संपादन योग्य दर सीमाएँ**— डैशबोर्ड में कॉन्फ़िगर करने योग्य सिस्टम-स्तरीय डिफ़ॉल्ट: -**प्रति मिनट अनुरोध (आरपीएम)**- प्रति खाता प्रति मिनट अधिकतम अनुरोध -**अनुरोधों के बीच न्यूनतम समय**- अनुरोधों के बीच मिलीसेकंड में न्यूनतम अंतर -**अधिकतम समवर्ती अनुरोध**— प्रति खाता अधिकतम एक साथ अनुरोध
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- संशोधित करने के लिए**संपादित करें**पर क्लिक करें, फिर**सहेजें**या**रद्द करें**पर क्लिक करें। मान लचीलापन एपीआई के माध्यम से बने रहते हैं।
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**सर्किट ब्रेकर**- प्रति प्रदाता विफलताओं को ट्रैक करता है और सीमा तक पहुंचने पर स्वचालित रूप से सर्किट खोलता है: -**बंद**(स्वस्थ) - अनुरोध सामान्य रूप से प्रवाहित होते हैं -**खुला**- बार-बार विफलताओं के बाद प्रदाता अस्थायी रूप से अवरुद्ध हो जाता है -**आधा_खुला**— परीक्षण किया जा रहा है कि प्रदाता ठीक हो गया है या नहीं
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**नीतियाँ और लॉक किए गए पहचानकर्ता**- बल-अनलॉक क्षमता के साथ सर्किट ब्रेकर की स्थिति और लॉक किए गए पहचानकर्ताओं को दिखाता है।
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**दर सीमा ऑटो-डिटेक्शन**- प्रदाता दर सीमा से बचने के लिए सक्रिय रूप से `429` और `पुनः प्रयास करें` हेडर पर नज़र रखता है।
-
-**प्रो टिप:**जब कोई प्रदाता आउटेज से उबरता है तो सभी सर्किट ब्रेकर और कूलडाउन को साफ़ करने के लिए**रीसेट ऑल**बटन का उपयोग करें।---
+---
### Database Export / Import
-**डैशबोर्ड → सेटिंग्स → सिस्टम और स्टोरेज**में डेटाबेस बैकअप प्रबंधित करें।
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| कार्रवाई | विवरण |
-| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **डेटाबेस निर्यात करें** | वर्तमान SQLite डेटाबेस को `.sqlite` फ़ाइल के रूप में डाउनलोड करता है |
-| **सभी निर्यात करें (.tar.gz)** | एक पूर्ण बैकअप संग्रह डाउनलोड करता है जिसमें शामिल हैं: डेटाबेस, सेटिंग्स, कॉम्बो, प्रदाता कनेक्शन (कोई क्रेडेंशियल नहीं), एपीआई कुंजी मेटाडेटा |
-| **डेटाबेस आयात करें** | वर्तमान डेटाबेस को बदलने के लिए `.sqlite` फ़ाइल अपलोड करें। जब तक `DISABLE_SQLITE_AUTO_BACKUP=true` नहीं हो जाता तब तक प्री-इम्पोर्ट बैकअप स्वचालित रूप से बन जाता है | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**आयात सत्यापन:**आयातित फ़ाइल को अखंडता (SQLite प्राग्मा चेक), आवश्यक तालिकाओं (`प्रदाता_कनेक्शन`, `प्रदाता_नोड्स`, `कॉम्बोस`, `एपीआई_कीज़`), और आकार (अधिकतम 100एमबी) के लिए मान्य किया गया है।
+**Use Cases:**
-**उपयोग के मामले:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- मशीनों के बीच ओम्निरूट माइग्रेट करें
-- आपदा पुनर्प्राप्ति के लिए बाहरी बैकअप बनाएं
-- टीम के सदस्यों के बीच कॉन्फ़िगरेशन साझा करें (सभी निर्यात करें → संग्रह साझा करें)---
+---
### Settings Dashboard
-आसान नेविगेशन के लिए सेटिंग पेज को 6 टैब में व्यवस्थित किया गया है:
+The settings page is organized into 6 tabs for easy navigation:
-| टैब | सामग्री |
-| -------------- | -------------------------------------------------------------------------------------------------- |
-|**सामान्य**| सिस्टम भंडारण उपकरण, उपस्थिति सेटिंग्स, थीम नियंत्रण और प्रति-आइटम साइडबार दृश्यता |
-|**सुरक्षा**| लॉगिन/पासवर्ड सेटिंग्स, आईपी एक्सेस कंट्रोल, `/मॉडल` के लिए एपीआई प्रमाणीकरण, और प्रदाता ब्लॉकिंग |
-|**रूटिंग**| वैश्विक रूटिंग रणनीति (6 विकल्प), वाइल्डकार्ड मॉडल उपनाम, फ़ॉलबैक चेन, कॉम्बो डिफ़ॉल्ट |
-|**लचीलापन**| प्रदाता प्रोफाइल, संपादन योग्य दर सीमा, सर्किट ब्रेकर स्थिति, नीतियां और लॉक पहचानकर्ता |
-|**एआई**| बजट कॉन्फ़िगरेशन, ग्लोबल सिस्टम प्रॉम्प्ट इंजेक्शन, प्रॉम्प्ट कैश आँकड़े सोचना |
-|**उन्नत**| वैश्विक प्रॉक्सी कॉन्फ़िगरेशन (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-**डैशबोर्ड → लागत**के माध्यम से पहुंच।
+Access via **Dashboard → Costs**.
-| टैब | उद्देश्य |
-| ----------- | ------------------------------------------------------------------------------------------------ |
-|**बजट**| दैनिक/साप्ताहिक/मासिक बजट और वास्तविक समय ट्रैकिंग के साथ प्रति एपीआई कुंजी खर्च सीमा निर्धारित करें
-|**मूल्य निर्धारण**| मॉडल मूल्य निर्धारण प्रविष्टियाँ देखें और संपादित करें - प्रति प्रदाता प्रति 1K इनपुट/आउटपुट टोकन की लागत |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -766,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**लागत ट्रैकिंग:**प्रत्येक अनुरोध टोकन उपयोग को लॉग करता है और मूल्य निर्धारण तालिका का उपयोग करके लागत की गणना करता है। प्रदाता, मॉडल और एपीआई कुंजी द्वारा**डैशबोर्ड → उपयोग**में विश्लेषण देखें।---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-ओमनीरूट ओपनएआई-संगत एंडपॉइंट के माध्यम से ऑडियो ट्रांसक्रिप्शन का समर्थन करता है:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-उपलब्ध प्रदाता:**डीपग्राम**(`डीपग्राम/`),**असेंबलीएआई**(`असेंबलीएआई/`)।
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-समर्थित ऑडियो प्रारूप: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`।---
+---
### Combo Balancing Strategies
-**डैशबोर्ड → कॉम्बो → बनाएं/संपादित करें → रणनीति**में प्रति-कॉम्बो संतुलन कॉन्फ़िगर करें।
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| रणनीति | विवरण |
-| ------------------ | -------------------------------------------------------------------------------- |
-|**राउंड-रॉबिन**| मॉडलों के माध्यम से क्रमिक रूप से घूमता है |
-|**प्राथमिकता**| हमेशा पहला मॉडल आज़माता है; केवल त्रुटि पर वापस आता है |
-|**यादृच्छिक**| प्रत्येक अनुरोध के लिए कॉम्बो से एक यादृच्छिक मॉडल चुनता है |
-|**भारित**| प्रति मॉडल निर्दिष्ट भार के आधार पर आनुपातिक रूप से मार्ग |
-|**कम से कम इस्तेमाल**| सबसे कम हालिया अनुरोधों के साथ मॉडल पर रूट (कॉम्बो मेट्रिक्स का उपयोग करता है) |
-|**लागत-अनुकूलित**| सबसे सस्ते उपलब्ध मॉडल के लिए मार्ग (मूल्य निर्धारण तालिका का उपयोग करता है) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-ग्लोबल कॉम्बो डिफॉल्ट्स को**डैशबोर्ड → सेटिंग्स → रूटिंग → कॉम्बो डिफॉल्ट्स**में सेट किया जा सकता है।---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-**डैशबोर्ड → स्वास्थ्य**के माध्यम से पहुंच। 6 कार्डों के साथ वास्तविक समय प्रणाली स्वास्थ्य अवलोकन:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| कार्ड | यह क्या दिखाता है |
-| ---------------------- | ---------------------------------------------------------------- |
-|**सिस्टम स्थिति**| अपटाइम, संस्करण, मेमोरी उपयोग, डेटा निर्देशिका |
-|**प्रदाता स्वास्थ्य**| प्रति-प्रदाता सर्किट ब्रेकर स्थिति (बंद/खुला/आधा-खुला) |
-|**दर सीमा**| शेष समय के साथ प्रति खाता सक्रिय दर सीमा को शांत करना |
-|**सक्रिय तालाबंदी**| प्रदाताओं को तालाबंदी नीति द्वारा अस्थायी रूप से अवरुद्ध कर दिया गया है |
-|**हस्ताक्षर कैश**| डिडुप्लीकेशन कैश आँकड़े (सक्रिय कुंजियाँ, हिट दर) |
-|**विलंबता टेलीमेट्री**| प्रति प्रदाता p50/p95/p99 विलंबता एकत्रीकरण |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**प्रो टिप:**स्वास्थ्य पृष्ठ हर 10 सेकंड में स्वतः ताज़ा हो जाता है। यह पहचानने के लिए सर्किट ब्रेकर कार्ड का उपयोग करें कि कौन से प्रदाता समस्याओं का सामना कर रहे हैं।---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-ओमनीरूट विंडोज़, मैकओएस और लिनक्स के लिए एक मूल डेस्कटॉप एप्लिकेशन के रूप में उपलब्ध है।### स्थापित करें
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### स्थापित करें
```bash
# From the electron directory:
@@ -834,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -846,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-आउटपुट → `इलेक्ट्रॉन/डिस्ट-इलेक्ट्रॉन/`### Key Features
+Output → `electron/dist-electron/`
-| फ़ीचर | विवरण |
-| ------------------------ | -------------------------------------------------------- | ------------------------- |
-| **सर्वर की तैयारी** | विंडो दिखाने से पहले पोल सर्वर (कोई खाली स्क्रीन नहीं) |
-| **सिस्टम ट्रे** | ट्रे को छोटा करें, पोर्ट बदलें, ट्रे मेनू से बाहर निकलें |
-| **पोर्ट प्रबंधन** | ट्रे से सर्वर पोर्ट बदलें (ऑटो-रीस्टार्ट सर्वर) |
-| **सामग्री सुरक्षा नीति** | सत्र शीर्षलेखों के माध्यम से प्रतिबंधात्मक सीएसपी |
-| **एकल उदाहरण** | एक समय में केवल एक ऐप इंस्टेंस चल सकता है |
-| **ऑफ़लाइन मोड** | बंडल नेक्स्ट.जेएस सर्वर इंटरनेट के बिना काम करता है | ### Environment Variables |
+### Key Features
-| परिवर्तनीय | डिफ़ॉल्ट | विवरण |
-| --------------------- | -------- | -------------------------------- |
-| `OMNIROUTE_PORT` | `20128` | सर्वर पोर्ट |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js ढेर सीमा (64-16384 एमबी) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 पूर्ण दस्तावेज़: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/hu/README.md b/docs/i18n/hu/README.md
index d8bf7e1042..abdf5c1ced 100644
--- a/docs/i18n/hu/README.md
+++ b/docs/i18n/hu/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/hu/docs/USER_GUIDE.md b/docs/i18n/hu/docs/USER_GUIDE.md
index dfb3212ebe..bf8f59f809 100644
--- a/docs/i18n/hu/docs/USER_GUIDE.md
+++ b/docs/i18n/hu/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Teljes útmutató a szolgáltatók konfigurálásához, kombinációk létrehozásához, a CLI-eszközök integrálásához és az OmniRoute telepítéséhez.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Árképzés egy pillantással](#-pricing-at-a-glance)
-- [Használati esetek](#-használati esetek)
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
- [Provider Setup](#-provider-setup)
-- [CLI-integráció](#-cli-integráció)
-- [Bevezetés](#-bevezetés)
-- [Elérhető modellek](#-elérhető-modell)
-- [Speciális funkciók](#-speciális-szolgáltatás)---
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 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 KEY** | DeepSeek | Fizetés használatonként | Nincs | Olcsó érvelés |
-| | Groq | Fizetés használatonként | Nincs | Ultragyors következtetés |
-| | xAI (Grok) | Fizetés használatonként | Nincs | Grok 4 okfejtés |
-| | Mistral | Fizetés használatonként | Nincs | EU-ban működő modellek |
-| | Zavartság | Fizetés használatonként | Nincs | Keresés-bővített |
-| | Együtt AI | Fizetés használatonként | Nincs | Nyílt forráskódú modellek |
-| | Tűzijáték AI | Fizetés használatonként | Nincs | Gyors FLUX képek |
-| | Cerebrák | Fizetés használatonként | Nincs | Ostya léptékű sebesség |
-| | Cohere | Fizetés használatonként | Nincs | Parancs R+ RAG |
-| | NVIDIA NIM | Fizetés használatonként | Nincs | Vállalati modellek |
-| **💰 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** | Qoder | $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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Pro tipp:**Kezdje a Gemini CLI-vel (180 000 ingyenes/hónap) + Qoder (korlátlan ingyenes) kombináció = 0 USD költség!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Probléma:**A kvóta lejár, kihasználatlanul, sebességkorlátozások erős kódolás közben```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Probléma:**Nem engedheti meg magának az előfizetést, megbízható mesterséges intelligencia kódolásra van szüksége```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Probléma:**Határidők, nem engedheti meg magának az állásidőt```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Probléma:**AI-asszisztens szükséges az üzenetküldő alkalmazásokhoz, teljesen ingyenes```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ 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!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Legjobb érték:**Hatalmas ingyenes szint! Használja ezt a fizetett szintek előtt.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### 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: "saját kulcsa"
+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álat:**`glm/glm-4.7` —**Profi tipp:**A Coding Plan 3× kvótát kínál 1/7 költséggel! Visszaállítás naponta 10:00.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Regisztráljon: [MiniMax](https://www.minimax.io/)
-2. API-kulcs lekérése → Irányítópult → API-kulcs hozzáadása
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Használat:**`minimax/MiniMax-M2.1` —**Profi tipp:**A legolcsóbb lehetőség hosszú kontextushoz (1 millió token)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Feliratkozás: [Moonshot AI](https://platform.moonshot.ai/)
-2. API-kulcs lekérése → Irányítópult → API-kulcs hozzáadása
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Használat:**`kimi/kimi-latest` —**Profi tipp:**Fix 9 USD/hó 10 millió token esetén = 0,90 USD/1 millió tényleges költség!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-"~/.claude/config.json" szerkesztése:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Settings → Models → Advanced:
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-`~/.openclaw/openclaw.json` szerkesztése:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Vagy használja az Irányítópultot:**CLI Tools → OpenClaw → Auto-config### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-A CLI automatikusan betölti az ".env" fájlt a "~/.omniroute/.env" vagy "./.env" állományból.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-Korlátozott RAM-mal rendelkező szerverek esetén használja a memóriakorlátozás opciót:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Hozza létre az `ecosystem.config.js' fájlt:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,13 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-A CLI binárisokkal rendelkező gazdagépbe integrált módhoz lásd a Docker részt a fő dokumentumokban.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-A Void Linux felhasználók natív módon csomagolhatják és telepíthetik az OmniRoute-ot az `xbps-src` keresztfordítási keretrendszer használatával. Ez automatizálja a Node.js önálló felépítését a szükséges "better-sqlite3" natív kötésekkel együtt.
+### Void Linux (xbps-src)
-
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
-Xbps-src sablon megtekintése```bash
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -409,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -476,80 +516,85 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Változó | Alapértelmezett | Leírás |
-| ---------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| "JWT_SECRET" | `omniroute-default-secret-change-me` | JWT aláírási titok (**változás a gyártásban**) |
-| `INITIAL_PASSWORD` | "123456" | Első bejelentkezési jelszó |
-| `DATA_DIR` | `~/.omniroute` | Adatkönyvtár (db, használat, naplók) |
-| "KIKÖTŐ" | keretrendszer alapértelmezett | Service port (`20128` in examples) |
-| `HOSTNAME` | keretrendszer alapértelmezett | Gazda kötése (a Docker alapértelmezett értéke `0.0.0.0`) |
-| "NODE_ENV" | futásidejű alapértelmezett | A "gyártás" beállítása a telepítéshez |
-| `BASE_URL` | `http://localhost:20128` | Szerveroldali belső alap URL |
-| `CLOUD_URL` | `https://omniroute.dev` | Felhőszinkronizálási végpont alap URL-je |
-| "API_KEY_SECRET" | `endpoint-proxy-api-key-secret` | HMAC titkos a generált API-kulcsokhoz |
-| `REQUIRE_API_KEY` | "hamis" | Bearer API kulcs kényszerítése a `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | "hamis" | Engedélyezze az Api Managernek a teljes API-kulcsok igény szerinti másolását |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | "70" | Szerveroldali frissítési ütem a gyorsítótárazott szolgáltatói korlátok adataihoz; A felhasználói felület frissítő gombjai továbbra is kézi szinkronizálást indítanak el |
-| `DISABLE_SQLITE_AUTO_BACKUP` | "hamis" | Az automatikus SQLite pillanatképek letiltása az írás/importálás/visszaállítás előtt; a kézi biztonsági mentések továbbra is működnek |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE' | "hamis" | "Biztonságos" hitelesítési cookie kényszerítése (a HTTPS fordított proxy mögött) |
-| `CLOUDFLARED_BIN` | beállítva | A felügyelt letöltés helyett használjon egy létező 'cloudflared' bináris fájlt |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Felügyelt gyorsalagutak szállítása ("http2", "quic" vagy "auto") |
-| `OMNIROUTE_MEMORY_MB` | "512" | Node.js kupackorlát MB-ban |
-| `PROMPT_CACHE_MAX_SIZE` | "50" | Max prompt gyorsítótár bejegyzések |
-| `SEMANTIC_CACHE_MAX_SIZE` | "100" | Maximális szemantikai gyorsítótár bejegyzések |A teljes környezeti változó hivatkozását a [README](../README.md) részben találja.---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Az összes elérhető modell megtekintése
+
+View all available models
-**Claude Code (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI ("gc/")**– INGYENES: "gc/gemini-3-flash-preview", "gc/gemini-2.5-pro"
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**GitHub másodpilóta ("gh/")**: "gh/gpt-5", "gh/claude-4.5-szonett"
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM ("glm/")**– 0,6 USD/1 millió: "glm/glm-4,7"
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— 0,2 USD/1 millió: `minimax/MiniMax-M2,1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder ("if/")**– INGYENES: "if/kimi-k2-thinking", "if/qwen3-coder-plus", "if/deepseek-r1"
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen ("qw/")**– INGYENES: "qw/qwen3-coder-plus", "qw/qwen3-coder-flash"
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— INGYENES: `kr/claude-szonett-4,5`, `kr/claude-haiku-4,5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
-**DeepSeek (`ds/`)**: "ds/deepseek-chat", "ds/deepseek-reasoner"
+**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
-**Groq ("groq/")**: "groq/llama-3.3-70b-veratile", "groq/llama-4-maverick-17b-128e-instruct"
+**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
-**xAI ("xai/")**: "xai/grok-4", "xai/grok-4-0709-fast-reasoning", "xai/grok-code-mini"
+**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
-**Mistral ("mistral/")**: "mistral/mistral-large-2501", "mistral/codestral-2501"
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Perplexity ("pplx/")**: "pplx/sonar-pro", "pplx/sonar"
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**Together AI ("together/")**: "together/meta-llama/Llama-3.3-70B-Instruct-Turbo"
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**Fireworks AI ("tűzijáték/")**: "fireworks/accounts/fireworks/models/deepseek-v3p1"
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**Agy ("cerebras/")**: "cerebras/láma-3,3-70b"
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
-**Cohere ("cohere/")**: "cohere/command-r-plus-08-2024"
+**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -557,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Adjon hozzá bármilyen modellazonosítót bármely szolgáltatóhoz anélkül, hogy az alkalmazás frissítésére várna:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -565,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Vagy használja az Irányítópultot:**Providers → [Provider] → Custom Models**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Megjegyzések:
+Notes:
-- Az OpenRouter és az OpenAI/Anthropic-kompatibilis szolgáltatók csak az**Elérhető modellekből**kezelhetők. Az összes kézi hozzáadása, importálása és automatikus szinkronizálása ugyanabban az elérhető modelllistában található, így ezeknek a szolgáltatóknak nincs külön egyéni modellek szakasza.
-- Az**Egyéni modellek**szakasz azoknak a szolgáltatóknak szól, akik nem teszik közzé a felügyelt elérhető modellek importálását.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-A kérések közvetlenül egy adott szolgáltatóhoz irányíthatók modellellenőrzéssel:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-A szolgáltató előtagja automatikusan hozzáadódik, ha hiányzik. A nem megfelelő modellek „400”-at adnak vissza.### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -595,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Precencia:**Kulcsspecifikus → Kombinált → Szolgáltató-specifikus → Globális → Környezet.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-A modelleket szolgáltató szerint csoportosítva adja vissza típusokkal ("csevegés", "beágyazás", "kép").### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- 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 időtúllépéssel + hibamentes
-- A szerveroldali "BASE_URL"/"CLOUD_URL" előnyben részesítése éles környezetben### Cloudflare Quick Tunnel
+### Cloud Sync
-- Elérhető a**Irányítópult → Végpontok**menüpontban a Docker és más saját üzemeltetésű telepítésekhez
-- Létrehoz egy ideiglenes „https://\*.trycloudflare.com” URL-t, amely továbbítja a jelenlegi OpenAI-kompatibilis „/v1” végpontot
-- Először csak szükség esetén engedélyezze a `cloudflared` telepítését; a későbbi újraindítások újra felhasználják ugyanazt a felügyelt bináris fájlt
-- A gyors alagutak nem állnak vissza automatikusan az OmniRoute vagy a tároló újraindítása után; szükség esetén újra engedélyezze őket a műszerfalról
-- Az alagút URL-jei rövidek, és minden alkalommal változnak, amikor leállítja/indítja az alagutat
-- A felügyelt gyorsalagutak alapértelmezés szerint a HTTP/2-es szállítást használják, hogy elkerüljék a zajos QUIC UDP puffer figyelmeztetéseket a korlátozott tárolókban
-- Állítsa be a `CLOUDFLARED_PROTOCOL=quic' vagy `automatikus' értéket, ha felül szeretné bírálni a felügyelt szállítási választást
-- Állítsa be a `CLOUDFLARED_BIN' értéket, ha inkább egy előre telepített 'cloudflared' binárist használ a kezelt letöltés helyett### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Szemantikus gyorsítótár**– Automatikus gyorsítótárazás, nem adatfolyam, hőmérséklet = 0 válasz (kihagyás az "X-OmniRoute-No-Cache: true" beállítással) -**Idempotency kérése**– 5 másodpercen belül deduplikálja a kéréseket az "Idempotency-Key" vagy az "X-Request-Id" fejlécen keresztül -**Előrehaladás követése**— SSE "esemény: előrehaladás" események engedélyezése az "X-OmniRoute-Progress: true" fejlécen keresztül---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Hozzáférés az**Irányítópult → Fordító**segítségével. Hibakeresés és vizualizálás, hogy az OmniRoute hogyan fordítja le az API-kéréseket a szolgáltatók között.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| mód | Cél |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| **Játszótér** | Válassza ki a forrás-/célformátumokat, illesszen be egy kérést, és azonnal megtekintheti a lefordított kimenetet |
-| **Csevegés tesztelő** | Küldjön élő csevegési üzeneteket a proxyn keresztül, és ellenőrizze a teljes kérés/válasz ciklust |
-| **Próbapad** | Futtasson kötegelt teszteket több formátumkombinációra a fordítás helyességének ellenőrzéséhez |
-| **Élő monitor** | Nézze meg a valós idejű fordításokat, ahogy a kérések a proxyn keresztül áramlanak |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Használati esetek:**
+**Use cases:**
-- Hibakeresés, miért nem sikerül egy adott ügyfél/szolgáltató kombináció
-- Ellenőrizze, hogy a gondolkodó címkék, az eszközhívások és a rendszerkérések helyesen fordítódnak-e
-- Hasonlítsa össze a formátumbeli különbségeket az OpenAI, Claude, Gemini és Responses API formátumok között---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Konfigurálás a**Irányítópult → Beállítások → Útválasztás**menüpontban.
+Configure via **Dashboard → Settings → Routing**.
-| Stratégia | Leírás |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Először töltse ki** | A fiókokat prioritási sorrendben használja – az elsődleges fiók minden kérést kezel, amíg el nem éri |
-| **Round Robin** | A konfigurálható ragadós korláttal rendelkező összes fiókot végigjárja (alapértelmezett: fiókonként 3 hívás) |
-| **P2C (Power of Two Choices)** | 2 véletlenszerű fiókot választ, és az egészségesebbhez vezet – egyensúlyba hozza a terhelést az egészségtudattal |
-| **Véletlen** | Véletlenszerűen kiválaszt egy fiókot minden egyes kérelemhez a Fisher-Yates shuffle |
-| **Legkevésbé használt** | Útvonalak a legrégebbi "lastUsedAt" időbélyeggel rendelkező fiókhoz, egyenletesen elosztva a forgalmat |
-| **Költségoptimalizált** | Útvonalak a legalacsonyabb prioritású fiókhoz, a legalacsonyabb költségű szolgáltatókra optimalizálva | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Külső munkamenet-affinitás esetén (például Claude Code/Codex ügynökök fordított proxyk mögött) küldje el:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-Az OmniRoute elfogadja az "x_session_id" paramétert is, és az "X-OmniRoute-Session-Id" mezőben visszaadja a tényleges munkamenet kulcsát.
+If you use Nginx and send underscore-form headers, enable:
-Ha az Nginxet használja, és aláhúzás-formájú fejléceket küld, engedélyezze:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Hozzon létre helyettesítő karaktermintákat a modellnevek újratervezéséhez:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-A helyettesítő karakterek támogatják a `*` (bármilyen karakter) és a `?` (egykarakteres) karaktereket.#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Határozzon meg globális tartalék láncokat, amelyek minden kérelemre vonatkoznak:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Konfigurálás a**Irányítópult → Beállítások → Ellenállás**menüpontban.
+Configure via **Dashboard → Settings → Resilience**.
-Az OmniRoute szolgáltatói szintű rugalmasságot valósít meg négy összetevőből:
+OmniRoute implements provider-level resilience with four components:
-1.**Szolgáltatói profilok**— Szolgáltatónkénti konfiguráció a következőkhöz:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Meghibásodási küszöb (hány hiba történt a nyitás előtt)
-- Lehűlés időtartama
-- Sebességkorlát érzékelési érzékenység
-- Exponenciális backoff paraméterek
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Szerkeszthető díjkorlátok**— Az irányítópulton konfigurálható rendszerszintű alapértékek: -**Percenkénti kérések (RPM)**– A percenkénti kérések száma fiókonként -**Minimális idő a kérések között**- Minimális eltérés ezredmásodpercben a kérések között -**Maximális egyidejű kérések**- Maximális egyidejű kérések száma fiókonként
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Kattintson a**Szerkesztés**gombra a módosításhoz, majd a**Mentés**vagy a**Mégse**gombra. Az értékek a rezilience API-n keresztül megmaradnak.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Circuit Breaker**– Nyomon követi a hibákat szolgáltatónként, és automatikusan megnyitja az áramkört egy küszöbérték elérésekor: -**ZÁRVA**(egészséges) – A kérések normálisan futnak -**NYITVA**— A szolgáltató ideiglenesen blokkolva van ismétlődő hibák után -**HALF_OPEN**— Tesztelés, hogy a szolgáltató helyreállt-e
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Policies & Locked Identifiers**— Megjeleníti a megszakító állapotát és a zárolt azonosítókat kényszer-feloldási képességgel.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Automatikus díjkorlát-észlelés**– Figyeli a "429" és az "Újrapróbálkozás után" fejléceket, hogy proaktívan elkerülje a szolgáltatói díjkorlátok átlépését.
-
-**Profi tipp:**Használja a**Reset All**gombot az összes megszakító és leállás törléséhez, amikor a szolgáltató felépül egy kiesésből.---
+---
### Database Export / Import
-Az adatbázis-mentéseket az**Irányítópult → Beállítások → Rendszer és tárhely**menüpontban kezelheti.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Akció | Leírás |
-| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Adatbázis exportálása** | Letölti az aktuális SQLite adatbázist `.sqlite` fájlként |
-| **Az összes exportálása (.tar.gz)** | Letölt egy teljes biztonsági mentési archívumot, beleértve: adatbázist, beállításokat, kombinációkat, szolgáltatói kapcsolatokat (hitelesítő adatok nélkül), API kulcs metaadatait |
-| **Import Database** | Töltsön fel egy ".sqlite" fájlt az aktuális adatbázis lecseréléséhez. Az importálás előtti biztonsági másolat automatikusan létrejön, kivéve, ha `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Importálás ellenőrzése:**Az importált fájl integritását (SQLite pragma ellenőrzés), a szükséges táblákat ("provider_connections", "provider_nodes", "combos", "api_keys") és méretét (maximum 100 MB) ellenőrzik.
+**Use Cases:**
-**Használati esetek:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- OmniRoute migrálása a gépek között
-- Készítsen külső biztonsági másolatot a katasztrófa utáni helyreállításhoz
-- Share configurations between team members (export all → share archive)---
+---
### Settings Dashboard
-A beállítások oldala 6 lapra van rendezve a könnyű navigáció érdekében:
+The settings page is organized into 6 tabs for easy navigation:
-| Tab | Tartalom |
+| Tab | Contents |
| -------------- | ---------------------------------------------------------------------------------------------- |
-|**Általános**| Rendszertároló eszközök, megjelenési beállítások, témavezérlők és elemenkénti oldalsáv láthatósága |
-|**Biztonság**| Bejelentkezési/jelszó-beállítások, IP-hozzáférés-vezérlés, API-hitelesítés a `/models-hez' és Szolgáltató blokkolása |
-|**Útválasztás**| Globális útválasztási stratégia (6 lehetőség), helyettesítő karakteres modellálnevek, tartalék láncok, kombinált alapértelmezések |
-|**rugalmasság**| Szolgáltatói profilok, szerkeszthető sebességkorlátok, megszakító állapota, szabályzatok és zárolt azonosítók |
-|**AI**| Átgondolt költségkeret-konfiguráció, globális rendszerbefecskendezés, gyorsítótár-statisztikák |
-|**Speciális**| Globális proxykonfiguráció (HTTP/SOCKS5) |---
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Hozzáférés az**Irányítópult → Költségek**menüponton keresztül.
+Access via **Dashboard → Costs**.
-| Tab | Cél |
-| ----------- | ----------------------------------------------------------------------------------------- |
-|**Költségvetés**| Költési korlátok beállítása API-kulcsonként napi/heti/havi költségkerettel és valós idejű követéssel |
-|**Árak**| Modellárazási bejegyzések megtekintése és szerkesztése – szolgáltatónként 1 000 bemeneti/kimeneti tokenenkénti költség |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -766,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Költségkövetés:**Minden kérés naplózza a tokenhasználatot, és az ártáblázat segítségével kiszámítja a költségeket. Tekintse meg az**Irányítópult → Használat**szolgáltató, modell és API-kulcs szerinti lebontását.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-Az OmniRoute támogatja a hang átírását az OpenAI-kompatibilis végponton keresztül:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Elérhető szolgáltatók:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Támogatott hangformátumok: "mp3", "wav", "m4a", "flac", "ogg", "webm".---
+---
### Combo Balancing Strategies
-Konfigurálja a kombinált egyensúlyozást az**Irányítópult → Kombók → Létrehozás/Szerkesztés → Stratégia**menüpontban.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Stratégia | Leírás |
-| ------------------- | ------------------------------------------------------------------------ |
-|**Round-Robin**| Sorozatosan forgatja a modelleket |
-|**Prioritás**| Mindig az első modellt próbálja ki; csak hibára esik vissza |
-|**Véletlen**| Véletlenszerű modellt választ a kombinációból minden egyes kéréshez |
-|**Súlyozott**| Útvonalak arányosan a modellenként hozzárendelt súlyok alapján |
-|**Legkevésbé használt**| Útvonalak a legutóbbi legkevesebb kéréssel rendelkező modellhez (kombinált mérőszámokat használ) |
-|**Költségoptimalizált**| Útvonalak a legolcsóbb elérhető modellhez (árazási táblázatot használ) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-A globális kombinált alapértelmezések az**Irányítópult → Beállítások → Útválasztás → Kombinált alapértelmezések**menüpontban állíthatók be.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Hozzáférés az**Irányítópult → Egészség**menüponton keresztül. Valós idejű rendszerállapot-áttekintés 6 kártyával:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Kártya | Mit mutat |
-| ---------------------- | ------------------------------------------------------------ |
-|**Rendszerállapot**| Üzemidő, verzió, memóriahasználat, adatkönyvtár |
-|**Szolgáltatói egészség**| Szolgáltatónkénti megszakító állapota (Zárt/Nyitott/Félig nyitva) |
-|**Díjkorlátok**| Aktív sebességkorlátozások fiókonként a hátralévő idővel |
-|**Aktív kizárások**| A kizárási szabályzat által ideiglenesen letiltott szolgáltatók |
-|**Aláírás-gyorsítótár**| Deduplikációs gyorsítótár statisztikái (aktív kulcsok, találati arány) |
-|**Latencia telemetria**| p50/p95/p99 késleltetési összesítés szolgáltatónként |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Profi tipp:**Az Egészség oldal 10 másodpercenként automatikusan frissül. Használja a megszakító kártyát annak azonosítására, hogy mely szolgáltatók tapasztaltak problémákat.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-Az OmniRoute natív asztali alkalmazásként érhető el Windows, macOS és Linux rendszerekhez.### Telepítés
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Telepítés
```bash
# From the electron directory:
@@ -834,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -846,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Kimenet → `electron/dist-electron/`### Key Features
+Output → `electron/dist-electron/`
-| Funkció | Leírás |
-| --------------------------------- | ------------------------------------------------------------------------- | ------------------------- |
-| **Szerver készenlét** | Szavazási kiszolgáló az ablak megjelenítése előtt (nincs üres képernyő) |
-| **Rendszertálca** | Minimalizálás tálcára, port módosítása, kilépés a tálca menüből |
-| **Kikötők kezelése** | Szerverport módosítása a tálcáról (a kiszolgáló automatikus újraindítása) |
-| **Tartalombiztonsági szabályzat** | Korlátozó CSP munkamenet fejléceken keresztül |
-| **Egyetlen példány** | Egyszerre csak egy alkalmazáspéldány futhat |
-| **Offline mód** | A mellékelt Next.js szerver internet nélkül működik | ### Environment Variables |
+### Key Features
-| Változó | Alapértelmezett | Leírás |
-| --------------------- | --------------- | --------------------------------- |
-| `OMNIROUTE_PORT` | "20128" | Szerver port |
-| `OMNIROUTE_MEMORY_MB` | "512" | Node.js kupackorlát (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Teljes dokumentáció: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/id/README.md b/docs/i18n/id/README.md
index 166a33535f..5114f4ea27 100644
--- a/docs/i18n/id/README.md
+++ b/docs/i18n/id/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/id/docs/USER_GUIDE.md b/docs/i18n/id/docs/USER_GUIDE.md
index 1933bc4446..89febf63ae 100644
--- a/docs/i18n/id/docs/USER_GUIDE.md
+++ b/docs/i18n/id/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Panduan lengkap untuk mengonfigurasi penyedia, membuat kombo, mengintegrasikan alat CLI, dan menerapkan OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Sekilas Harga](#-harga-sekilas)
-- [Kasus Penggunaan](#-kasus penggunaan)
-- [Penyiapan Penyedia](#-penyiapan-penyedia)
-- [Integrasi CLI](#-cli-integrasi)
-- [Penerapan](#-penerapan)
-- [Model yang Tersedia](#-model-tersedia)
-- [Fitur Lanjutan](#-fitur-lanjutan)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 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** | Pencarian Dalam | Bayar per penggunaan | Tidak ada | Alasan murah |
-| | Bagus | Bayar per penggunaan | Tidak ada | Inferensi ultra-cepat |
-| | xAI (Grok) | Bayar per penggunaan | Tidak ada | Alasan Grok 4 |
-| | Mistral | Bayar per penggunaan | Tidak ada | Model yang dihosting di UE |
-| | Kebingungan | Bayar per penggunaan | Tidak ada | Ditambah pencarian |
-| | Bersama AI | Bayar per penggunaan | Tidak ada | Model sumber terbuka |
-| | AI kembang api | Bayar per penggunaan | Tidak ada | Gambar FLUX Cepat |
-| | Otak | Bayar per penggunaan | Tidak ada | Kecepatan skala wafer |
-| | menyatu | Bayar per penggunaan | Tidak ada | Perintah R+ RAG |
-| | NVIDIA NIM | Bayar per penggunaan | Tidak ada | Model perusahaan |
-| **💰 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** | Qoder | $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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Kiat Pro:**Mulai dengan Gemini CLI (gratis 180 ribu/bulan) + kombo Qoder (gratis tanpa batas) = biaya $0!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Masalah:**Kuota habis tanpa terpakai, batas kecepatan selama coding berat```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Masalah:**Tidak mampu berlangganan, memerlukan pengkodean AI yang andal```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Masalah:**Tenggat waktu, tidak mampu membayar downtime```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Masalah:**Membutuhkan asisten AI dalam aplikasi perpesanan, sepenuhnya gratis```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**Kiat Pro:**Gunakan Opus untuk tugas kompleks, Soneta untuk kecepatan. OmniRoute melacak kuota per model!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Nilai Terbaik:**Tingkat gratis yang sangat besar! Gunakan ini sebelum tingkatan berbayar.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### 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: `kunci-Anda`
+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` —**Tips Pro:**Paket Coding menawarkan 3× kuota dengan biaya 1/7! Reset setiap hari pukul 10.00.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Daftar: [MiniMax](https://www.minimax.io/)
-2. Dapatkan kunci API → Dasbor → Tambahkan Kunci API
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Gunakan:**`minimax/MiniMax-M2.1` —**Tips Pro:**Opsi termurah untuk konteks panjang (1 juta token)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Berlangganan: [Moonshot AI](https://platform.moonshot.ai/)
-2. Dapatkan kunci API → Dasbor → Tambahkan Kunci API
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Penggunaan:**`kimi/kimi-latest` —**Tips Pro:**Memperbaiki $9/bulan untuk 10 juta token = biaya efektif $0,90/1 juta!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Sunting `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Sunting `~/.claude/config.json`:```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Sunting `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Atau gunakan Dasbor:**Alat CLI → OpenClaw → Konfigurasi otomatis### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI secara otomatis memuat `.env` dari `~/.omniroute/.env` atau `./.env`.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-Untuk server dengan RAM terbatas, gunakan opsi batas memori:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Buat `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,12 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-Untuk mode terintegrasi host dengan biner CLI, lihat bagian Docker di dokumen utama.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Pengguna Void Linux dapat mengemas dan menginstal OmniRoute secara asli menggunakan kerangka kompilasi silang `xbps-src`. Ini mengotomatiskan build mandiri Node.js bersama dengan binding asli `better-sqlite3` yang diperlukan.
+### Void Linux (xbps-src)
-
-Lihat templat xbps-src```bash
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -408,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -475,80 +516,85 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Variabel | Bawaan | Deskripsi |
-| --------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
-| `JWT_RAHASIA` | `omniroute-default-rahasia-ubah-saya` | Rahasia penandatanganan JWT (**perubahan produksi**) |
-| `INITIAL_PASSWORD` | `123456` | Kata sandi masuk pertama |
-| `DATA_DIR` | `~/.omniroute` | Direktori data (db, penggunaan, log) |
-| `PELABUHAN` | kerangka default | Port layanan (`20128` dalam contoh) |
-| `NAMA HOST` | kerangka default | Ikat host (Docker defaultnya adalah `0.0.0.0`) |
-| `NODE_ENV` | default waktu proses | Setel `produksi` untuk penerapan |
-| `BASE_URL` | `http://localhost:20128` | URL dasar internal sisi server |
-| `CLOUD_URL` | `https://omniroute.dev` | URL dasar titik akhir sinkronisasi cloud |
-| `API_KEY_SECRET` | `titik-akhir-proxy-api-rahasia-kunci` | Rahasia HMAC untuk kunci API yang dihasilkan |
-| `REQUIRE_API_KEY` | `salah` | Terapkan kunci API Pembawa pada `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `salah` | Izinkan Api Manager menyalin kunci API lengkap sesuai permintaan |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Irama penyegaran sisi server untuk data Batas Penyedia yang di-cache; Tombol penyegaran UI masih memicu sinkronisasi manual |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `salah` | Nonaktifkan snapshot SQLite otomatis sebelum menulis/impor/pulihkan; backup manual masih berfungsi |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `salah` | Paksa cookie autentikasi `Aman` (di belakang proksi terbalik HTTPS) |
-| `CLOUDFLARED_BIN` | tidak disetel | Gunakan biner `cloudflared` yang sudah ada alih-alih unduhan terkelola |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Transportasi untuk Terowongan Cepat terkelola (`http2`, `quic`, atau `auto`) |
-| `OMNIROUTE_MEMORY_MB` | `512` | Batas tumpukan Node.js dalam MB |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | Entri cache prompt maks |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Entri cache semantik maksimal |Untuk referensi variabel lingkungan selengkapnya, lihat [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Lihat semua model yang tersedia
+
+View all available models
-**Kode Claude (`cc/`)**— Pro/Maks: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— GRATIS: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**Copilot GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— $0,6/1 juta: `glm/glm-4,7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— $0,2/1 juta: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— GRATIS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— GRATIS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— GRATIS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
-**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-penalaran cepat`, `xai/grok-code-mini`
+**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
-**Mistral (`mistral/`)**: `mistral/mistral-besar-2501`, `mistral/codestral-2501`
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Kebingungan (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**Bersama AI (`bersama/`)**: `bersama/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**Serebral (`otak/`)**: `otak/llama-3.3-70b`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -556,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Tambahkan ID model apa pun ke penyedia mana pun tanpa menunggu pembaruan aplikasi:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -564,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Atau gunakan Dasbor:**Penyedia → [Penyedia] → Model Khusus**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Catatan:
+Notes:
-- Penyedia yang kompatibel dengan OpenRouter dan OpenAI/Anthropic dikelola hanya dari**Model yang Tersedia**. Penambahan, impor, dan sinkronisasi otomatis secara manual semuanya berada dalam daftar model tersedia yang sama, sehingga tidak ada bagian Model Kustom terpisah untuk penyedia tersebut.
-- Bagian**Model Khusus**ditujukan untuk penyedia yang tidak mengekspos impor model tersedia yang dikelola.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Rutekan permintaan langsung ke penyedia tertentu dengan validasi model:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Awalan penyedia ditambahkan secara otomatis jika tidak ada. Model yang tidak cocok menghasilkan `400`.### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -594,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Prioritas:**Khusus kunci → Khusus kombo → Khusus penyedia → Global → Lingkungan.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Mengembalikan model yang dikelompokkan berdasarkan penyedia dengan jenis (`obrolan`, `penyematan`, `gambar`).### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Sinkronisasi penyedia, kombo, dan pengaturan di seluruh perangkat
-- Sinkronisasi latar belakang otomatis dengan batas waktu + cepat gagal
-- Lebih memilih `BASE_URL`/`CLOUD_URL` sisi server dalam produksi### Cloudflare Quick Tunnel
+### Cloud Sync
-- Tersedia di**Dasbor → Titik Akhir**untuk Docker dan penerapan yang dihosting sendiri lainnya
-- Membuat URL `https://*.trycloudflare.com` sementara yang meneruskan ke titik akhir `/v1` yang kompatibel dengan OpenAI saat ini
-- Pertama aktifkan instalasi `cloudflared` hanya bila diperlukan; kemudian restart, gunakan kembali biner terkelola yang sama
-- Terowongan Cepat tidak dipulihkan secara otomatis setelah OmniRoute atau kontainer dimulai ulang; aktifkan kembali dari dasbor bila diperlukan
-- URL terowongan bersifat sementara dan berubah setiap kali Anda menghentikan/memulai terowongan
-- Terkelola Quick Tunnels default ke transportasi HTTP/2 untuk menghindari peringatan buffer UDP QUIC yang berisik dalam wadah yang dibatasi
-- Setel `CLOUDFLARED_PROTOCOL=quic` atau `auto` jika Anda ingin mengganti pilihan transportasi terkelola
-- Setel `CLOUDFLARED_BIN` jika Anda lebih suka menggunakan biner `cloudflared` yang sudah diinstal sebelumnya daripada unduhan terkelola### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Cache Semantik**— Cache otomatis non-streaming, suhu=0 tanggapan (bypass dengan `X-OmniRoute-No-Cache: true`) -**Request Idempoency**— Menghapus duplikat permintaan dalam waktu 5 detik melalui header `Idempotency-Key` atau `X-Request-Id` -**Pelacakan Kemajuan**— Ikut serta dalam acara `acara: kemajuan` SSE melalui header `X-OmniRoute-Progress: true`---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Akses melalui**Dasbor → Penerjemah**. Debug dan visualisasikan bagaimana OmniRoute menerjemahkan permintaan API antar penyedia.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Modus | Tujuan |
-| -------------------- | ------------------------------------------------------------------------------------------------ |
-| **Taman Bermain** | Pilih format sumber/target, tempelkan permintaan, dan lihat keluaran terjemahan secara instan |
-| **Penguji Obrolan** | Kirim pesan obrolan langsung melalui proxy dan periksa siklus permintaan/respons lengkap |
-| **Bangku Tes** | Jalankan pengujian batch pada berbagai kombinasi format untuk memverifikasi kebenaran terjemahan |
-| **Monitor Langsung** | Tonton terjemahan real-time saat permintaan mengalir melalui proxy |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Kasus penggunaan:**
+**Use cases:**
-- Debug mengapa kombinasi klien/penyedia tertentu gagal
-- Verifikasi bahwa tag pemikiran, panggilan alat, dan perintah sistem diterjemahkan dengan benar
-- Bandingkan perbedaan format antara format OpenAI, Claude, Gemini, dan Responses API---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Konfigurasikan melalui**Dasbor → Pengaturan → Perutean**.
+Configure via **Dashboard → Settings → Routing**.
-| Strategi | Deskripsi |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Isi Dulu** | Menggunakan akun dalam urutan prioritas — akun utama menangani semua permintaan hingga tidak tersedia |
-| **Robin Bulat** | Menggilir semua akun dengan batas melekat yang dapat dikonfigurasi (default: 3 panggilan per akun) |
-| **P2C (Kekuatan Dua Pilihan)** | Pilih 2 akun acak dan rute ke akun yang lebih sehat — menyeimbangkan beban dengan kesadaran akan kesehatan |
-| **Acak** | Memilih akun secara acak untuk setiap permintaan menggunakan Fisher-Yates shuffle |
-| **Jarang Digunakan** | Merutekan ke akun dengan stempel waktu `lastUsedAt` terlama, mendistribusikan lalu lintas secara merata |
-| **Pengoptimalan Biaya** | Merutekan ke akun dengan nilai prioritas terendah, mengoptimalkan penyedia berbiaya terendah | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Untuk afinitas sesi eksternal (misalnya, agen Claude Code/Codex di belakang proxy terbalik), kirim:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute juga menerima `x_session_id` dan mengembalikan kunci sesi efektif di `X-OmniRoute-Session-Id`.
+If you use Nginx and send underscore-form headers, enable:
-Jika Anda menggunakan Nginx dan mengirim header berbentuk garis bawah, aktifkan:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Buat pola wildcard untuk memetakan ulang nama model:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Wildcard mendukung `*` (karakter apa saja) dan `?` (karakter tunggal).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Tentukan rantai fallback global yang berlaku di semua permintaan:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Konfigurasikan melalui**Dasbor → Pengaturan → Ketahanan**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute mengimplementasikan ketahanan tingkat penyedia dengan empat komponen:
+OmniRoute implements provider-level resilience with four components:
-1.**Profil Penyedia**— Konfigurasi per penyedia untuk:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Ambang batas kegagalan (berapa banyak kegagalan sebelum dibuka)
-- Durasi pendinginan
-- Sensitivitas deteksi batas kecepatan
-- Parameter backoff eksponensial
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Batas Tarif yang Dapat Diedit**— Default tingkat sistem dapat dikonfigurasi di dasbor: -**Permintaan Per Menit (RPM)**— Permintaan maksimum per menit per akun -**Waktu Minimum Antar Permintaan**— Kesenjangan minimum dalam milidetik antar permintaan -**Permintaan Bersamaan Maksimum**— Permintaan simultan maksimum per akun
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Klik**Edit**untuk mengubah, lalu**Simpan**atau**Batal**. Nilai-nilai bertahan melalui API ketahanan.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Pemutus Sirkuit**— Melacak kegagalan per penyedia dan secara otomatis membuka sirkuit ketika ambang batas tercapai: -**TUTUP**(Sehat) — Permintaan mengalir normal -**BUKA**— Penyedia diblokir sementara setelah kegagalan berulang kali -**HALF_OPEN**— Menguji apakah penyedia telah pulih
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Kebijakan & Pengidentifikasi Terkunci**— Menampilkan status pemutus sirkuit dan pengidentifikasi terkunci dengan kemampuan buka paksa.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Deteksi Otomatis Batas Kecepatan**— Memantau header `429` dan `Coba Ulang-Setelah` untuk secara proaktif menghindari batas kecepatan penyedia.
-
-**Kiat Pro:**Gunakan tombol**Reset Semua**untuk menghapus semua pemutus sirkuit dan cooldown saat penyedia pulih dari pemadaman listrik.---
+---
### Database Export / Import
-Kelola cadangan basis data di**Dasbor → Pengaturan → Sistem & Penyimpanan**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Aksi | Deskripsi |
-| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Ekspor Basis Data** | Mengunduh database SQLite saat ini sebagai file `.sqlite` |
-| **Ekspor Semua (.tar.gz)** | Mengunduh arsip cadangan lengkap termasuk: basis data, pengaturan, kombo, koneksi penyedia (tanpa kredensial), metadata kunci API |
-| **Impor Basis Data** | Unggah file `.sqlite` untuk menggantikan database saat ini. Cadangan pra-impor dibuat secara otomatis kecuali `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Validasi Impor:**File yang diimpor divalidasi untuk integritas (pemeriksaan pragma SQLite), tabel yang diperlukan (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), dan ukuran (maks 100MB).
+**Use Cases:**
-**Kasus Penggunaan:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Migrasi OmniRoute antar mesin
-- Buat cadangan eksternal untuk pemulihan bencana
-- Bagikan konfigurasi antar anggota tim (ekspor semua → bagikan arsip)---
+---
### Settings Dashboard
-Halaman pengaturan disusun menjadi 6 tab untuk memudahkan navigasi:
+The settings page is organized into 6 tabs for easy navigation:
-| Tab | Isi |
+| Tab | Contents |
| -------------- | ---------------------------------------------------------------------------------------------- |
-|**Umum**| Alat penyimpanan sistem, pengaturan tampilan, kontrol tema, dan visibilitas sidebar per item |
-|**Keamanan**| Pengaturan Login/Kata Sandi, Kontrol Akses IP, autentikasi API untuk `/models`, dan Pemblokiran Penyedia |
-|**Perutean**| Strategi perutean global (6 opsi), alias model wildcard, rantai fallback, default kombo |
-|**Ketahanan**| Profil penyedia, batas tarif yang dapat diedit, status pemutus sirkuit, kebijakan & pengidentifikasi terkunci |
-|**AI**| Memikirkan konfigurasi anggaran, injeksi cepat sistem global, statistik cache cepat |
-|**Lanjutan**| Konfigurasi proksi global (HTTP/SOCKS5) |---
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Akses melalui**Dasbor → Biaya**.
+Access via **Dashboard → Costs**.
-| Tab | Tujuan |
-| ----------- | ----------------------------------------------------------------------------------------- |
-|**Anggaran**| Tetapkan batas pengeluaran per kunci API dengan anggaran harian/mingguan/bulanan dan pelacakan waktu nyata |
-|**Harga**| Lihat dan edit entri harga model — biaya per 1K token input/output per penyedia |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -765,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Pelacakan Biaya:**Setiap permintaan mencatat penggunaan token dan menghitung biaya menggunakan tabel harga. Lihat pengelompokan di**Dasbor → Penggunaan**menurut penyedia, model, dan kunci API.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute mendukung transkripsi audio melalui titik akhir yang kompatibel dengan OpenAI:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Penyedia yang tersedia:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Format audio yang didukung: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.---
+---
### Combo Balancing Strategies
-Konfigurasikan penyeimbangan per kombo di**Dasbor → Kombo → Buat/Edit → Strategi**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Strategi | Deskripsi |
-| ---- | ------------------------------------------------------------------------ |
-|**Robin Bulat**| Berputar melalui model secara berurutan |
-|**Prioritas**| Selalu mencoba model pertama; jatuh kembali hanya karena kesalahan |
-|**Acak**| Memilih model acak dari kombo untuk setiap permintaan |
-|**Berbobot**| Rute secara proporsional berdasarkan bobot yang ditetapkan per model |
-|**Jarang Digunakan**| Merutekan ke model dengan permintaan terkini paling sedikit (menggunakan metrik kombo) |
-|**Dioptimalkan Biaya**| Rute ke model termurah yang tersedia (menggunakan tabel harga) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Default kombo global dapat diatur di**Dasbor → Pengaturan → Perutean → Default Kombo**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Akses melalui**Dasbor → Kesehatan**. Ikhtisar kesehatan sistem real-time dengan 6 kartu:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Kartu | Apa yang Ditunjukkannya |
-| --------------------- | -------------------------------------------- |
-|**Status Sistem**| Uptime, versi, penggunaan memori, direktori data |
-|**Kesehatan Penyedia**| Status pemutus sirkuit per penyedia (Tertutup/Terbuka/Setengah Terbuka) |
-|**Batas Tarif**| Cooldown batas tarif aktif per akun dengan sisa waktu |
-|**Penguncian Aktif**| Penyedia diblokir sementara oleh kebijakan lockout |
-|**Cache Tanda Tangan**| Statistik cache deduplikasi (kunci aktif, tingkat hit) |
-|**Telemetri Latensi**| agregasi latensi p50/p95/p99 per penyedia |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Tips Pro:**Halaman Kesehatan disegarkan secara otomatis setiap 10 detik. Gunakan kartu pemutus sirkuit untuk mengidentifikasi penyedia mana yang mengalami masalah.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute tersedia sebagai aplikasi desktop asli untuk Windows, macOS, dan Linux.### Instal
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Instal
```bash
# From the electron directory:
@@ -833,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -845,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Keluaran → `elektron/dist-elektron/`### Key Features
+Output → `electron/dist-electron/`
-| Fitur | Deskripsi |
-| ----------------------------- | -------------------------------------------------------------------------- | ------------------------- |
-| **Kesiapan Server** | Server jajak pendapat sebelum menampilkan jendela (tidak ada layar kosong) |
-| **Baki Sistem** | Minimalkan ke baki, ubah port, keluar dari menu baki |
-| **Manajemen Pelabuhan** | Ubah port server dari baki (server restart otomatis) |
-| **Kebijakan Keamanan Konten** | CSP terbatas melalui header sesi |
-| **Instans Tunggal** | Hanya satu instance aplikasi yang dapat dijalankan dalam satu waktu |
-| **Mode Luring** | Server Next.js yang dibundel berfungsi tanpa internet | ### Environment Variables |
+### Key Features
-| Variabel | Bawaan | Deskripsi |
-| --------------------- | ------- | ------------------------------------ |
-| `OMNIROUTE_PORT` | `20128` | Pelabuhan server |
-| `OMNIROUTE_MEMORY_MB` | `512` | Batas tumpukan Node.js (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Dokumentasi lengkap: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/in/README.md b/docs/i18n/in/README.md
index a993b833b7..580b48cde7 100644
--- a/docs/i18n/in/README.md
+++ b/docs/i18n/in/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/in/docs/USER_GUIDE.md b/docs/i18n/in/docs/USER_GUIDE.md
index 86b3037f4d..b44887b2a7 100644
--- a/docs/i18n/in/docs/USER_GUIDE.md
+++ b/docs/i18n/in/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-प्रदाताओं को कॉन्फ़िगर करने, कॉम्बो बनाने, सीएलआई टूल को एकीकृत करने और ओमनीरूट को तैनात करने के लिए संपूर्ण मार्गदर्शिका।---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [मूल्य निर्धारण एक नजर में](#-मूल्य निर्धारण एक नजर में)
-- [उपयोग मामले](#-उपयोग मामले)
-- [प्रदाता सेटअप](#-प्रदाता-सेटअप)
-- [सीएलआई एकीकरण](#-सीएलआई-एकीकरण)
-- [तैनाती](#-तैनाती)
-- [उपलब्ध मॉडल](#-उपलब्ध-मॉडल)
-- [उन्नत सुविधाएँ](#-उन्नत-सुविधाएँ)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 Pricing at a Glance
-| टियर | प्रदाता | लागत | कोटा रीसेट | के लिए सर्वश्रेष्ठ |
-| ----------------- | ------------------- | ----------------------- | -------------------- | ---------------------------- |
-| **💳 सदस्यता** | क्लाउड कोड (प्रो) | $20/माह | 5 घंटे + साप्ताहिक | पहले ही सदस्यता ले ली है |
-| | कोडेक्स (प्लस/प्रो) | $20-200/महीना | 5 घंटे + साप्ताहिक | OpenAI उपयोगकर्ता |
-| | जेमिनी सीएलआई | **मुफ़्त** | 180K/माह + 1K/दिन | सब लोग! |
-| | गिटहब कोपायलट | $10-19/माह | मासिक | GitHub उपयोगकर्ता |
-| **🔑एपीआई कुंजी** | डीपसीक | प्रति उपयोग भुगतान करें | कोई नहीं | सस्ता तर्क |
-| | ग्रोक | प्रति उपयोग भुगतान करें | कोई नहीं | अल्ट्रा-फास्ट अनुमान |
-| | एक्सएआई (ग्रोक) | प्रति उपयोग भुगतान करें | कोई नहीं | ग्रोक 4 तर्क |
-| | मिस्ट्रल | प्रति उपयोग भुगतान करें | कोई नहीं | ईयू द्वारा होस्ट किए गए मॉडल |
-| | उलझन | प्रति उपयोग भुगतान करें | कोई नहीं | खोज-संवर्धित |
-| | एक साथ एआई | प्रति उपयोग भुगतान करें | कोई नहीं | ओपन-सोर्स मॉडल |
-| | आतिशबाजी एआई | प्रति उपयोग भुगतान करें | कोई नहीं | फास्ट फ्लक्स छवियां |
-| | सेरेब्रस | प्रति उपयोग भुगतान करें | कोई नहीं | वेफर-स्केल गति |
-| | सहभागी | प्रति उपयोग भुगतान करें | कोई नहीं | कमांड आर+आरएजी |
-| | एनवीडिया एनआईएम | प्रति उपयोग भुगतान करें | कोई नहीं | एंटरप्राइज़ मॉडल |
-| **💰सस्ता** | जीएलएम-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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡प्रो टिप:**जेमिनी सीएलआई (180K मुफ़्त/माह) + कोडर (असीमित मुफ़्त) कॉम्बो = $0 लागत से शुरू करें!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**समस्या:**भारी कोडिंग के दौरान कोटा अप्रयुक्त, दर सीमा समाप्त हो जाता है```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**समस्या:**सदस्यताएं वहन नहीं कर सकते, विश्वसनीय एआई कोडिंग की आवश्यकता है```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**समस्या:**समय सीमा, डाउनटाइम बर्दाश्त नहीं कर सकते```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**समस्या:**मैसेजिंग ऐप्स में AI सहायक की आवश्यकता है, पूरी तरह से निःशुल्क```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**प्रो टिप:**जटिल कार्यों के लिए ओपस और गति के लिए सॉनेट का उपयोग करें। ओमनीरूट प्रति मॉडल कोटा ट्रैक करता है!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**सर्वोत्तम मूल्य:**विशाल निःशुल्क स्तर! सशुल्क स्तरों से पहले इसका उपयोग करें।#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### GLM-4.7 (Daily reset, $0.6/1M)
-1. साइन अप करें: [झिपु एआई](https://open.bigmodel.cn/)
-2. कोडिंग योजना से एपीआई कुंजी प्राप्त करें
-3. डैशबोर्ड → एपीआई कुंजी जोड़ें: प्रदाता: `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` -**प्रो टिप:**कोडिंग प्लान 1/7 लागत पर 3× कोटा प्रदान करता है! प्रतिदिन सुबह 10:00 बजे रीसेट करें।#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. साइन अप करें: [मिनीमैक्स](https://www.minimax.io/)
-2. एपीआई कुंजी प्राप्त करें → डैशबोर्ड → एपीआई कुंजी जोड़ें
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**उपयोग करें:**`मिनीमैक्स/मिनीमैक्स-एम2.1` -**प्रो टिप:**लंबे संदर्भ के लिए सबसे सस्ता विकल्प (1एम टोकन)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. सदस्यता लें: [मूनशॉट एआई](https://platform.moonshot.ai/)
-2. एपीआई कुंजी प्राप्त करें → डैशबोर्ड → एपीआई कुंजी जोड़ें
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**उपयोग:**`किमी/किमी-नवीनतम` -**प्रो टिप:**10एम टोकन के लिए निश्चित $9/माह = $0.90/1एम प्रभावी लागत!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-`~/.claude/config.json` संपादित करें:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Settings → Models → Advanced:
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-`~/.openclaw/openclaw.json` संपादित करें:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**या डैशबोर्ड का उपयोग करें:**सीएलआई टूल्स → ओपनक्लॉ → ऑटो-कॉन्फ़िगरेशन### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-सीएलआई स्वचालित रूप से `.env` को `~/.omniroute/.env` या `./.env` से लोड करता है।### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-सीमित रैम वाले सर्वर के लिए, मेमोरी सीमा विकल्प का उपयोग करें:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-`ecosystem.config.js` बनाएं:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,15 +420,17 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-सीएलआई बायनेरिज़ के साथ होस्ट-एकीकृत मोड के लिए, मुख्य दस्तावेज़ में डॉकर अनुभाग देखें।### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-शून्य लिनक्स उपयोगकर्ता `xbps-src` क्रॉस-संकलन ढांचे का उपयोग करके मूल रूप से ओमनीरूट को पैकेज और इंस्टॉल कर सकते हैं। यह आवश्यक `better-sqlite3` मूल बाइंडिंग के साथ Node.js स्टैंडअलोन बिल्ड को स्वचालित करता है।
+### Void Linux (xbps-src)
-<विवरण>
-<सारांश>xbps-src टेम्पलेट देखें```bash
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
-
pkgname=omniroute
version=3.2.4
revision=1
@@ -402,7 +442,7 @@ license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
-system_accounts="\_omniroute"
+system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
@@ -410,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -477,80 +516,85 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| परिवर्तनीय | डिफ़ॉल्ट | विवरण |
-| ------------------------------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `सर्वव्यापी-डिफ़ॉल्ट-गुप्त-परिवर्तन-मुझे` | JWT हस्ताक्षर रहस्य (**उत्पादन में परिवर्तन**) |
-| `प्रारंभिक_पासवर्ड` | `123456` | पहला लॉगिन पासवर्ड |
-| `DATA_DIR` | `~/.omniroute` | डेटा निर्देशिका (डीबी, उपयोग, लॉग) |
-| `पोर्ट` | फ्रेमवर्क डिफ़ॉल्ट | सर्विस पोर्ट (उदाहरणों में `20128`) |
-| `होस्टनाम` | फ्रेमवर्क डिफ़ॉल्ट | बाइंड होस्ट (डॉकर डिफ़ॉल्ट `0.0.0.0`) |
-| `NODE_ENV` | रनटाइम डिफ़ॉल्ट | तैनाती के लिए 'उत्पादन' सेट करें |
-| `बेस_यूआरएल` | `http://localhost:20128` | सर्वर-साइड आंतरिक आधार URL |
-| `CLOUD_URL` | `https://omniroute.dev` | क्लाउड सिंक एंडपॉइंट बेस यूआरएल |
-| `API_KEY_SECRET` | `एंडपॉइंट-प्रॉक्सी-एपीआई-की-सीक्रेट` | जेनरेट की गई एपीआई कुंजियों के लिए एचएमएसी रहस्य |
-| `REQUIRE_API_KEY` | 'झूठा' | `/v1/*` पर बियरर एपीआई कुंजी लागू करें |
-| `अनुमति_एपीआई_कुंजी_प्रकटीकरण` | 'झूठा' | एपीआई प्रबंधक को मांग पर पूर्ण एपीआई कुंजियाँ कॉपी करने की अनुमति दें |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | कैश्ड प्रदाता सीमा डेटा के लिए सर्वर-साइड ताज़ा ताल; यूआई रीफ्रेश बटन अभी भी मैन्युअल सिंक ट्रिगर करते हैं |
-| `DISABLE_SQLITE_AUTO_BACKUP` | 'झूठा' | लिखने/आयात/पुनर्स्थापित करने से पहले स्वचालित SQLite स्नैपशॉट अक्षम करें; मैन्युअल बैकअप अभी भी काम करते हैं |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | 'झूठा' | `सिक्योर` ऑथ कुकी को बाध्य करें (एचटीटीपीएस रिवर्स प्रॉक्सी के पीछे) |
-| `CLOUDFLARED_BIN` | परेशान | प्रबंधित डाउनलोड के बजाय मौजूदा `क्लाउडफ्लेयर्ड` बाइनरी का उपयोग करें
-| `क्लाउडफ्लेयर्ड_प्रोटोकॉल` | `http2` | प्रबंधित त्वरित सुरंगों के लिए परिवहन ('http2', 'त्वरित', या 'ऑटो') |
-| `OMNIROUTE_MEMORY_MB` | `512` | MB में Node.js हीप सीमा |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | अधिकतम शीघ्र कैश प्रविष्टियाँ |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | अधिकतम सिमेंटिक कैश प्रविष्टियाँ |संपूर्ण पर्यावरण चर संदर्भ के लिए, [README](../README.md) देखें।---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-<विवरण>
-<सारांश>सभी उपलब्ध मॉडल देखें
+
+View all available models
-**क्लाउड कोड (`cc/`)**— प्रो/मैक्स: `cc/क्लाउड-ओपस-4-6`, `cc/क्लाउड-सोनेट-4-5-20250929`, `cc/क्लाउड-हाइकु-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**कोडेक्स (`सीएक्स/`)**— प्लस/प्रो: `सीएक्स/जीपीटी-5.2-कोडेक्स`, `सीएक्स/जीपीटी-5.1-कोडेक्स-मैक्स`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**मिथुन सीएलआई (`gc/`)**— मुफ़्त: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**गिटहब कोपायलट (`gh/`)**: `gh/gpt-5`, `gh/क्लाउड-4.5-सॉनेट`
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**जीएलएम (`जीएलएम/`)**— $0.6/1एम: `जीएलएम/जीएलएम-4.7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**मिनीमैक्स (`मिनीमैक्स/`)**— $0.2/1 मिलियन: `मिनीमैक्स/मिनीमैक्स-एम2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— मुफ़्त: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/depseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**क्वेन (`qw/`)**— मुफ़्त: `qw/qwen3-कोडर-प्लस`, `qw/qwen3-कोडर-फ़्लैश`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**किरो (`kr/`)**— मुफ़्त: `kr/क्लाउड-सॉनेट-4.5`, `kr/क्लाउड-हाइकु-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
-**डीपसीक (`डीएस/`)**: `डीएस/डीपसीक-चैट`, `डीएस/डीपसीक-रीज़नर`
+**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
-**ग्रोक (`ग्रोक/`)**: `ग्रोक/लामा-3.3-70बी-बहुमुखी`, `ग्रोक/लामा-4-मेवरिक-17बी-128ई-इंस्ट्रक्ट`
+**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
-**मिस्ट्रल (`मिस्ट्रल/`)**: `मिस्ट्रल/मिस्ट्रल-लार्ज-2501`, `मिस्ट्रल/कोडेस्ट्रल-2501`
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**व्याकुलता (`पीपीएलएक्स/`)**: `पीपीएलएक्स/सोनार-प्रो`, `पीपीएलएक्स/सोनार`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**टुगेदर एआई (`टुगेदर/`)**: `टुगेदर/मेटा-लामा/लामा-3.3-70बी-इंस्ट्रक्ट-टर्बो`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**आतिशबाज़ी एआई (`आतिशबाज़ी/`)**: `आतिशबाजी/खाते/आतिशबाज़ी/मॉडल/डीपसीक-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**सेरेब्रस (`सेरेब्रस/`)**: `सेरेब्रस/लामा-3.3-70बी`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -558,7 +602,9 @@ vlicense LICENSE
### Custom Models
-ऐप अपडेट की प्रतीक्षा किए बिना किसी भी प्रदाता से कोई भी मॉडल आईडी जोड़ें:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -566,22 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-या डैशबोर्ड का उपयोग करें:**प्रदाता → [प्रदाता] → कस्टम मॉडल**।
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-टिप्पणियाँ:
+Notes:
-- ओपनराउटर और ओपनएआई/एंथ्रोपिक-संगत प्रदाताओं को केवल**उपलब्ध मॉडल**से प्रबंधित किया जाता है। मैन्युअल ऐड, आयात और ऑटो-सिंक सभी एक ही उपलब्ध-मॉडल सूची में आते हैं, इसलिए उन प्रदाताओं के लिए कोई अलग कस्टम मॉडल अनुभाग नहीं है। -**कस्टम मॉडल**अनुभाग उन प्रदाताओं के लिए है जो प्रबंधित उपलब्ध-मॉडल आयात को उजागर नहीं करते हैं।### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-मॉडल सत्यापन के साथ सीधे एक विशिष्ट प्रदाता को रूट अनुरोध:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-गायब होने पर प्रदाता उपसर्ग स्वतः जुड़ जाता है। बेमेल मॉडल `400` लौटाते हैं।### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -595,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**प्राथमिकता:**कुंजी-विशिष्ट → कॉम्बो-विशिष्ट → प्रदाता-विशिष्ट → वैश्विक → पर्यावरण।### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-प्रदाता द्वारा प्रकारों (`चैट`, `एम्बेडिंग`, `छवि`) के साथ समूहीकृत मॉडल लौटाता है।### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- सभी डिवाइसों में सिंक प्रदाता, कॉम्बो और सेटिंग्स
-- टाइमआउट + फेल-फास्ट के साथ स्वचालित पृष्ठभूमि सिंक
-- उत्पादन में सर्वर-साइड `BASE_URL`/`CLOUD_URL` को प्राथमिकता दें### Cloudflare Quick Tunnel
+### Cloud Sync
-- डॉकर और अन्य स्व-होस्टेड परिनियोजन के लिए**डैशबोर्ड → एंडपॉइंट**में उपलब्ध है
-- एक अस्थायी `https://*.trycloudflare.com` URL बनाता है जो आपके वर्तमान OpenAI-संगत `/v1` समापन बिंदु पर अग्रेषित होता है
-- सबसे पहले जरूरत पड़ने पर ही `क्लाउडफ्लेयर` इंस्टॉल सक्षम करें; बाद में पुनरारंभ उसी प्रबंधित बाइनरी का पुन: उपयोग करता है
-- ओम्निरूट या कंटेनर पुनरारंभ के बाद त्वरित सुरंगें स्वतः बहाल नहीं होती हैं; आवश्यकता पड़ने पर उन्हें डैशबोर्ड से पुनः सक्षम करें
-- टनल यूआरएल अल्पकालिक होते हैं और हर बार जब आप टनल रोकते/शुरू करते हैं तो बदल जाते हैं
-- प्रबंधित त्वरित सुरंगें प्रतिबंधित कंटेनरों में शोर वाले QUIC UDP बफर चेतावनियों से बचने के लिए HTTP/2 परिवहन के लिए डिफ़ॉल्ट हैं।
-- यदि आप प्रबंधित परिवहन विकल्प को ओवरराइड करना चाहते हैं तो `CLOUDFLARED_PROTOCOL=quic` या `auto` सेट करें
-- यदि आप प्रबंधित डाउनलोड के बजाय पूर्वस्थापित `क्लाउडफ्लेयर्ड` बाइनरी का उपयोग करना पसंद करते हैं तो `CLOUDFLARED_BIN` सेट करें### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**सिमेंटिक कैश**- ऑटो-कैश नॉन-स्ट्रीमिंग, तापमान = 0 प्रतिक्रियाएँ ('एक्स-ओमनीरूट-नो-कैश: ट्रू' के साथ बायपास) -**अनुरोध Idempotency**- `Idempotency-Key` या `X-Request-Id` हेडर के माध्यम से 5 सेकंड के भीतर अनुरोधों को हटा देता है -**प्रगति ट्रैकिंग**- ऑप्ट-इन एसएसई `इवेंट: प्रगति` इवेंट `X-OmniRoute-Progress: true` हेडर के माध्यम से---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-**डैशबोर्ड → अनुवादक**के माध्यम से पहुंच। डीबग करें और कल्पना करें कि कैसे ओमनीरूट प्रदाताओं के बीच एपीआई अनुरोधों का अनुवाद करता है।
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| मोड | उद्देश्य |
-| ---------------- | -------------------------------------------------------------------------------------------- |
-| **खेल का मैदान** | स्रोत/लक्ष्य प्रारूप चुनें, एक अनुरोध चिपकाएँ, और अनुवादित आउटपुट तुरंत देखें |
-| **चैट परीक्षक** | प्रॉक्सी के माध्यम से लाइव चैट संदेश भेजें और पूर्ण अनुरोध/प्रतिक्रिया चक्र का निरीक्षण करें |
-| **टेस्ट बेंच** | अनुवाद की शुद्धता को सत्यापित करने के लिए कई प्रारूप संयोजनों में बैच परीक्षण चलाएँ |
-| **लाइव मॉनिटर** | प्रॉक्सी के माध्यम से अनुरोध प्रवाहित होने पर वास्तविक समय में अनुवाद देखें |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**उपयोग के मामले:**
+**Use cases:**
-- डीबग करें कि कोई विशिष्ट ग्राहक/प्रदाता संयोजन विफल क्यों होता है
-- सत्यापित करें कि थिंकिंग टैग, टूल कॉल और सिस्टम प्रॉम्प्ट सही ढंग से अनुवाद करते हैं
-- ओपनएआई, क्लाउड, जेमिनी और रिस्पॉन्स एपीआई प्रारूपों के बीच प्रारूप अंतर की तुलना करें---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-**डैशबोर्ड → सेटिंग्स → रूटिंग**के माध्यम से कॉन्फ़िगर करें।
+Configure via **Dashboard → Settings → Routing**.
-| रणनीति | विवरण |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
-| **पहले भरें** | प्राथमिकता क्रम में खातों का उपयोग करता है - प्राथमिक खाता अनुपलब्ध होने तक सभी अनुरोधों को संभालता है |
-| **राउंड रॉबिन** | एक विन्यास योग्य चिपचिपा सीमा के साथ सभी खातों के माध्यम से चक्र (डिफ़ॉल्ट: प्रति खाता 3 कॉल) |
-| **पी2सी (दो विकल्पों की शक्ति)** | 2 यादृच्छिक खाते चुनता है और स्वस्थ खाते की ओर ले जाता है - स्वास्थ्य के प्रति जागरूकता के साथ भार संतुलित करता है |
-| **यादृच्छिक** | फिशर-येट्स शफल | का उपयोग करके प्रत्येक अनुरोध के लिए यादृच्छिक रूप से एक खाता चुनता है |
-| **कम से कम इस्तेमाल** | सबसे पुराने `lastUsedAt` टाइमस्टैम्प के साथ खाते तक रूट, ट्रैफ़िक को समान रूप से वितरित करना |
-| **लागत अनुकूलित** | सबसे कम लागत वाले प्रदाताओं के लिए अनुकूलन, सबसे कम प्राथमिकता मूल्य वाले खाते तक रूट | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-बाहरी सत्र एफ़िनिटी के लिए (उदाहरण के लिए, रिवर्स प्रॉक्सी के पीछे क्लाउड कोड/कोडेक्स एजेंट), भेजें:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-ओमनीरूट `x_session_id` को भी स्वीकार करता है और `X-OmniRoute-Session-Id` में प्रभावी सत्र कुंजी लौटाता है।
+If you use Nginx and send underscore-form headers, enable:
-यदि आप Nginx का उपयोग करते हैं और अंडरस्कोर-फॉर्म हेडर भेजते हैं, तो सक्षम करें:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-मॉडल नामों को रीमैप करने के लिए वाइल्डकार्ड पैटर्न बनाएं:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-वाइल्डकार्ड `*` (कोई भी वर्ण) और `?` (एकल वर्ण) का समर्थन करते हैं।#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-वैश्विक फ़ॉलबैक श्रृंखलाओं को परिभाषित करें जो सभी अनुरोधों पर लागू होती हैं:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-**डैशबोर्ड → सेटिंग्स → लचीलापन**के माध्यम से कॉन्फ़िगर करें।
+Configure via **Dashboard → Settings → Resilience**.
-ओमनीरूट चार घटकों के साथ प्रदाता-स्तरीय लचीलापन लागू करता है:
+OmniRoute implements provider-level resilience with four components:
-1.**प्रदाता प्रोफाइल**- प्रति-प्रदाता कॉन्फ़िगरेशन:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- विफलता सीमा (उद्घाटन से पहले कितनी विफलताएँ)
-- कूलडाउन अवधि
-- दर सीमा का पता लगाने की संवेदनशीलता
-- घातीय बैकऑफ़ पैरामीटर
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**संपादन योग्य दर सीमाएँ**— डैशबोर्ड में कॉन्फ़िगर करने योग्य सिस्टम-स्तरीय डिफ़ॉल्ट: -**प्रति मिनट अनुरोध (आरपीएम)**- प्रति खाता प्रति मिनट अधिकतम अनुरोध -**अनुरोधों के बीच न्यूनतम समय**- अनुरोधों के बीच मिलीसेकंड में न्यूनतम अंतर -**अधिकतम समवर्ती अनुरोध**— प्रति खाता अधिकतम एक साथ अनुरोध
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- संशोधित करने के लिए**संपादित करें**पर क्लिक करें, फिर**सहेजें**या**रद्द करें**पर क्लिक करें। मान लचीलापन एपीआई के माध्यम से बने रहते हैं।
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**सर्किट ब्रेकर**- प्रति प्रदाता विफलताओं को ट्रैक करता है और सीमा तक पहुंचने पर स्वचालित रूप से सर्किट खोलता है: -**बंद**(स्वस्थ) - अनुरोध सामान्य रूप से प्रवाहित होते हैं -**खुला**- बार-बार विफलताओं के बाद प्रदाता अस्थायी रूप से अवरुद्ध हो जाता है -**आधा_खुला**— परीक्षण किया जा रहा है कि प्रदाता ठीक हो गया है या नहीं
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**नीतियाँ और लॉक किए गए पहचानकर्ता**- बल-अनलॉक क्षमता के साथ सर्किट ब्रेकर की स्थिति और लॉक किए गए पहचानकर्ताओं को दिखाता है।
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**दर सीमा ऑटो-डिटेक्शन**- प्रदाता दर सीमा से बचने के लिए सक्रिय रूप से `429` और `पुनः प्रयास करें` हेडर पर नज़र रखता है।
-
-**प्रो टिप:**जब कोई प्रदाता आउटेज से उबरता है तो सभी सर्किट ब्रेकर और कूलडाउन को साफ़ करने के लिए**रीसेट ऑल**बटन का उपयोग करें।---
+---
### Database Export / Import
-**डैशबोर्ड → सेटिंग्स → सिस्टम और स्टोरेज**में डेटाबेस बैकअप प्रबंधित करें।
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| कार्रवाई | विवरण |
-| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **डेटाबेस निर्यात करें** | वर्तमान SQLite डेटाबेस को `.sqlite` फ़ाइल के रूप में डाउनलोड करता है |
-| **सभी निर्यात करें (.tar.gz)** | एक पूर्ण बैकअप संग्रह डाउनलोड करता है जिसमें शामिल हैं: डेटाबेस, सेटिंग्स, कॉम्बो, प्रदाता कनेक्शन (कोई क्रेडेंशियल नहीं), एपीआई कुंजी मेटाडेटा |
-| **डेटाबेस आयात करें** | वर्तमान डेटाबेस को बदलने के लिए `.sqlite` फ़ाइल अपलोड करें। जब तक `DISABLE_SQLITE_AUTO_BACKUP=true` नहीं हो जाता तब तक प्री-इम्पोर्ट बैकअप स्वचालित रूप से बन जाता है | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**आयात सत्यापन:**आयातित फ़ाइल को अखंडता (SQLite प्राग्मा चेक), आवश्यक तालिकाओं (`प्रदाता_कनेक्शन`, `प्रदाता_नोड्स`, `कॉम्बोस`, `एपीआई_कीज़`), और आकार (अधिकतम 100एमबी) के लिए मान्य किया गया है।
+**Use Cases:**
-**उपयोग के मामले:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- मशीनों के बीच ओम्निरूट माइग्रेट करें
-- आपदा पुनर्प्राप्ति के लिए बाहरी बैकअप बनाएं
-- टीम के सदस्यों के बीच कॉन्फ़िगरेशन साझा करें (सभी निर्यात करें → संग्रह साझा करें)---
+---
### Settings Dashboard
-आसान नेविगेशन के लिए सेटिंग पेज को 6 टैब में व्यवस्थित किया गया है:
+The settings page is organized into 6 tabs for easy navigation:
-| टैब | सामग्री |
-| -------------- | -------------------------------------------------------------------------------------------------- |
-|**सामान्य**| सिस्टम भंडारण उपकरण, उपस्थिति सेटिंग्स, थीम नियंत्रण और प्रति-आइटम साइडबार दृश्यता |
-|**सुरक्षा**| लॉगिन/पासवर्ड सेटिंग्स, आईपी एक्सेस कंट्रोल, `/मॉडल` के लिए एपीआई प्रमाणीकरण, और प्रदाता ब्लॉकिंग |
-|**रूटिंग**| वैश्विक रूटिंग रणनीति (6 विकल्प), वाइल्डकार्ड मॉडल उपनाम, फ़ॉलबैक चेन, कॉम्बो डिफ़ॉल्ट |
-|**लचीलापन**| प्रदाता प्रोफाइल, संपादन योग्य दर सीमा, सर्किट ब्रेकर स्थिति, नीतियां और लॉक पहचानकर्ता |
-|**एआई**| बजट कॉन्फ़िगरेशन, ग्लोबल सिस्टम प्रॉम्प्ट इंजेक्शन, प्रॉम्प्ट कैश आँकड़े सोचना |
-|**उन्नत**| वैश्विक प्रॉक्सी कॉन्फ़िगरेशन (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-**डैशबोर्ड → लागत**के माध्यम से पहुंच।
+Access via **Dashboard → Costs**.
-| टैब | उद्देश्य |
-| ----------- | ------------------------------------------------------------------------------------------------ |
-|**बजट**| दैनिक/साप्ताहिक/मासिक बजट और वास्तविक समय ट्रैकिंग के साथ प्रति एपीआई कुंजी खर्च सीमा निर्धारित करें
-|**मूल्य निर्धारण**| मॉडल मूल्य निर्धारण प्रविष्टियाँ देखें और संपादित करें - प्रति प्रदाता प्रति 1K इनपुट/आउटपुट टोकन की लागत |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -766,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**लागत ट्रैकिंग:**प्रत्येक अनुरोध टोकन उपयोग को लॉग करता है और मूल्य निर्धारण तालिका का उपयोग करके लागत की गणना करता है। प्रदाता, मॉडल और एपीआई कुंजी द्वारा**डैशबोर्ड → उपयोग**में विश्लेषण देखें।---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-ओमनीरूट ओपनएआई-संगत एंडपॉइंट के माध्यम से ऑडियो ट्रांसक्रिप्शन का समर्थन करता है:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-उपलब्ध प्रदाता:**डीपग्राम**(`डीपग्राम/`),**असेंबलीएआई**(`असेंबलीएआई/`)।
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-समर्थित ऑडियो प्रारूप: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`।---
+---
### Combo Balancing Strategies
-**डैशबोर्ड → कॉम्बो → बनाएं/संपादित करें → रणनीति**में प्रति-कॉम्बो संतुलन कॉन्फ़िगर करें।
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| रणनीति | विवरण |
-| ------------------ | -------------------------------------------------------------------------------- |
-|**राउंड-रॉबिन**| मॉडलों के माध्यम से क्रमिक रूप से घूमता है |
-|**प्राथमिकता**| हमेशा पहला मॉडल आज़माता है; केवल त्रुटि पर वापस आता है |
-|**यादृच्छिक**| प्रत्येक अनुरोध के लिए कॉम्बो से एक यादृच्छिक मॉडल चुनता है |
-|**भारित**| प्रति मॉडल निर्दिष्ट भार के आधार पर आनुपातिक रूप से मार्ग |
-|**कम से कम इस्तेमाल**| सबसे कम हालिया अनुरोधों के साथ मॉडल पर रूट (कॉम्बो मेट्रिक्स का उपयोग करता है) |
-|**लागत-अनुकूलित**| सबसे सस्ते उपलब्ध मॉडल के लिए मार्ग (मूल्य निर्धारण तालिका का उपयोग करता है) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-ग्लोबल कॉम्बो डिफॉल्ट्स को**डैशबोर्ड → सेटिंग्स → रूटिंग → कॉम्बो डिफॉल्ट्स**में सेट किया जा सकता है।---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-**डैशबोर्ड → स्वास्थ्य**के माध्यम से पहुंच। 6 कार्डों के साथ वास्तविक समय प्रणाली स्वास्थ्य अवलोकन:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| कार्ड | यह क्या दिखाता है |
-| ---------------------- | ---------------------------------------------------------------- |
-|**सिस्टम स्थिति**| अपटाइम, संस्करण, मेमोरी उपयोग, डेटा निर्देशिका |
-|**प्रदाता स्वास्थ्य**| प्रति-प्रदाता सर्किट ब्रेकर स्थिति (बंद/खुला/आधा-खुला) |
-|**दर सीमा**| शेष समय के साथ प्रति खाता सक्रिय दर सीमा को शांत करना |
-|**सक्रिय तालाबंदी**| प्रदाताओं को तालाबंदी नीति द्वारा अस्थायी रूप से अवरुद्ध कर दिया गया है |
-|**हस्ताक्षर कैश**| डिडुप्लीकेशन कैश आँकड़े (सक्रिय कुंजियाँ, हिट दर) |
-|**विलंबता टेलीमेट्री**| प्रति प्रदाता p50/p95/p99 विलंबता एकत्रीकरण |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**प्रो टिप:**स्वास्थ्य पृष्ठ हर 10 सेकंड में स्वतः ताज़ा हो जाता है। यह पहचानने के लिए सर्किट ब्रेकर कार्ड का उपयोग करें कि कौन से प्रदाता समस्याओं का सामना कर रहे हैं।---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-ओमनीरूट विंडोज़, मैकओएस और लिनक्स के लिए एक मूल डेस्कटॉप एप्लिकेशन के रूप में उपलब्ध है।### स्थापित करें
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### स्थापित करें
```bash
# From the electron directory:
@@ -834,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -846,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-आउटपुट → `इलेक्ट्रॉन/डिस्ट-इलेक्ट्रॉन/`### Key Features
+Output → `electron/dist-electron/`
-| फ़ीचर | विवरण |
-| ------------------------ | -------------------------------------------------------- | ------------------------- |
-| **सर्वर की तैयारी** | विंडो दिखाने से पहले पोल सर्वर (कोई खाली स्क्रीन नहीं) |
-| **सिस्टम ट्रे** | ट्रे को छोटा करें, पोर्ट बदलें, ट्रे मेनू से बाहर निकलें |
-| **पोर्ट प्रबंधन** | ट्रे से सर्वर पोर्ट बदलें (ऑटो-रीस्टार्ट सर्वर) |
-| **सामग्री सुरक्षा नीति** | सत्र शीर्षलेखों के माध्यम से प्रतिबंधात्मक सीएसपी |
-| **एकल उदाहरण** | एक समय में केवल एक ऐप इंस्टेंस चल सकता है |
-| **ऑफ़लाइन मोड** | बंडल नेक्स्ट.जेएस सर्वर इंटरनेट के बिना काम करता है | ### Environment Variables |
+### Key Features
-| परिवर्तनीय | डिफ़ॉल्ट | विवरण |
-| --------------------- | -------- | -------------------------------- |
-| `OMNIROUTE_PORT` | `20128` | सर्वर पोर्ट |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js ढेर सीमा (64-16384 एमबी) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 पूर्ण दस्तावेज़: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/it/README.md b/docs/i18n/it/README.md
index 89255c560b..e1b7bf90e1 100644
--- a/docs/i18n/it/README.md
+++ b/docs/i18n/it/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/it/docs/USER_GUIDE.md b/docs/i18n/it/docs/USER_GUIDE.md
index aeeb6131f1..610e51ce97 100644
--- a/docs/i18n/it/docs/USER_GUIDE.md
+++ b/docs/i18n/it/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Guida completa per la configurazione dei provider, la creazione di combinazioni, l'integrazione degli strumenti CLI e la distribuzione di OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Prezzi in sintesi](#-prezzi in sintesi)
-- [Casi d'uso](#-casi d'uso)
-- [Configurazione del provider](#-configurazione del provider)
-- [Integrazione CLI](#-integrazione-cli)
-- [Distribuzione](#-distribuzione)
-- [Modelli disponibili](#-modelli-disponibili)
-- [Funzionalità avanzate](#-funzionalità-avanzate)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 Pricing at a Glance
-| Livello | Fornitore | Costo | Reimpostazione quota | Ideale per |
-| ------------------ | --------------------- | ----------------- | ------------------------ | ------------------------ |
-| **💳 ABBONAMENTO** | Codice Claude (Pro) | $20/mese | 5 ore + settimanale | Già iscritto |
-| | Codice (Plus/Pro) | $20-200/mese | 5 ore + settimanale | Utenti OpenAI |
-| | Gemelli CLI | **GRATIS** | 180K/mese + 1K/giorno | Tutti! |
-| | Copilota GitHub | $ 10-19/mese | Mensile | Utenti GitHub |
-| **🔑 CHIAVE API** | Ricerca profonda | Paga per utilizzo | Nessuno | Ragionamento economico |
-| | Groq | Paga per utilizzo | Nessuno | Inferenza ultraveloce |
-| | xAI (Grok) | Paga per utilizzo | Nessuno | Grok 4 ragionamento |
-| | Maestrale | Paga per utilizzo | Nessuno | Modelli ospitati nell'UE |
-| | Perplessità | Paga per utilizzo | Nessuno | Ricerca aumentata |
-| | Insieme AI | Paga per utilizzo | Nessuno | Modelli open source |
-| | Fuochi d'artificio AI | Paga per utilizzo | Nessuno | Immagini FLUX veloci |
-| | Cerebri | Paga per utilizzo | Nessuno | Velocità su scala wafer |
-| | Coerenza | Paga per utilizzo | Nessuno | Comando R+ RAG |
-| | NVIDIA NIM | Paga per utilizzo | Nessuno | Modelli di impresa |
-| **💰 ECONOMICO** | GLM-4.7 | $ 0,6/1 milione | Tutti i giorni 10:00 | Backup del budget |
-| | MiniMax M2.1 | $ 0,2/1 milione | 5 ore di rotazione | Opzione più economica |
-| | Kimi K2 | $ 9/mese fisso | 10 milioni di token/mese | Costo prevedibile |
-| **🆓 GRATUITO** | Qoder | $0 | Illimitato | 8 modelli gratuiti |
-| | Qwen | $0 | Illimitato | 3 modelli gratuiti |
-| | Kiro | $0 | Illimitato | Claude libero |
+| 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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Suggerimento da professionista:**Inizia con la combinazione Gemini CLI (180.000 gratuiti al mese) + Qoder (gratuito illimitato) = costo $ 0!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Problema:**La quota scade inutilizzata, limiti di velocità durante la codifica pesante```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Problema:**non posso permettermi abbonamenti, ho bisogno di una codifica IA affidabile```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Problema:**Scadenze, non posso permettermi tempi di inattività```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Problema:**È necessario un assistente AI nelle app di messaggistica, completamente gratuito```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**Suggerimento professionale:**usa Opus per attività complesse, Sonnet per la velocità. OmniRoute tiene traccia della quota per modello!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Miglior rapporto qualità-prezzo:**Enorme livello gratuito! Utilizzalo prima dei livelli a pagamento.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### GLM-4.7 (Daily reset, $0.6/1M)
-1. Iscriviti: [Zhipu AI](https://open.bigmodel.cn/)
-2. Ottieni la chiave API dal piano di codifica
-3. Dashboard → Aggiungi chiave API: Provider: `glm`, Chiave 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`
-**Utilizza:**`glm/glm-4.7` —**Suggerimento professionale:**Il piano di codifica offre una quota 3× a un costo di 1/7! Resetta ogni giorno alle 10:00.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Iscriviti: [MiniMax](https://www.minimax.io/)
-2. Ottieni chiave API → Dashboard → Aggiungi chiave API
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Utilizza:**`minimax/MiniMax-M2.1` —**Suggerimento professionale:**Opzione più economica per contesti lunghi (token da 1 milione)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Iscriviti: [Moonshot AI](https://platform.moonshot.ai/)
-2. Ottieni chiave API → Dashboard → Aggiungi chiave API
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Utilizza:**`kimi/kimi-latest` —**Suggerimento professionale:**Risolti $ 9/mese per 10 milioni di token = $ 0,90/1 milione di costi effettivi!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Modifica `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Modifica `~/.claude/config.json`:```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Modifica `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Oppure utilizza Dashboard:**Strumenti CLI → OpenClaw → Configurazione automatica### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-La CLI carica automaticamente `.env` da `~/.omniroute/.env` o `./.env`.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-Per i server con RAM limitata, utilizzare l'opzione di limite di memoria:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Crea `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,12 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-Per la modalità integrata nell'host con i file binari della CLI, consulta la sezione Docker nella documentazione principale.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Gli utenti Void Linux possono creare pacchetti e installare OmniRoute in modo nativo utilizzando il framework di compilazione incrociata "xbps-src". Ciò automatizza la compilazione autonoma di Node.js insieme ai collegamenti nativi "better-sqlite3" richiesti.
+### Void Linux (xbps-src)
-
-Visualizza modello xbps-src```bash
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -408,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -475,60 +516,63 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Variabile | Predefinito | Descrizione |
+| Variable | Default | Description |
| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | Segreto firma JWT (**cambio di produzione**) |
-| `PASSWORD_INIZIALE` | `123456` | Prima password di accesso |
-| "DIR_DATI" | `~/.omniroute` | Directory dati (db, utilizzo, log) |
-| "PORTO" | quadro predefinito | Porta di servizio (`20128` negli esempi) |
-| "NOMEHOST" | quadro predefinito | Associa host (Docker ha come impostazione predefinita `0.0.0.0`) |
-| `NODO_ENV` | impostazione predefinita di runtime | Imposta "produzione" per la distribuzione |
-| "URL_BASE" | `http://localhost:20128` | URL di base interno lato server |
-| `URL_CLOUD` | `https://omniroute.dev` | URL di base dell'endpoint di sincronizzazione cloud |
-| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Segreto HMAC per le chiavi API generate |
-| `REQUIRE_API_KEY` | `falso` | Applica la chiave API Bearer su `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `falso` | Consenti al gestore API di copiare le chiavi API complete su richiesta |
-| "PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES" | `70` | Cadenza di aggiornamento lato server per i dati sui limiti del provider memorizzati nella cache; I pulsanti di aggiornamento dell'interfaccia utente attivano ancora la sincronizzazione manuale |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `falso` | Disabilitare gli snapshot SQLite automatici prima delle operazioni di scrittura/importazione/ripristino; i backup manuali funzionano ancora |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `falso` | Forza il cookie di autenticazione `Secure` (dietro il proxy inverso HTTPS) |
-| `CLOUDFLARED_BIN` | non impostato | Utilizza un file binario `cloudflared` esistente invece del download gestito |
-| `CLOUDFLARED_PROTOCOL` | "http2" | Trasporto per tunnel rapidi gestiti (`http2`, `quic` o `auto`) |
-| `OMNIROUTE_MEMORY_MB` | "512" | Limite heap di Node.js in MB |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | Numero massimo di voci nella cache dei prompt |
-| `SEMANTIC_CACHE_MAX_SIZE` | "100" | Numero massimo di voci della cache semantica |Per il riferimento completo alle variabili di ambiente, vedere [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Visualizza tutti i modelli disponibili
+
+View all available models
-**Codice Claude (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codice (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— GRATUITO: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— 0,6 USD/1 milione: `glm/glm-4,7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— 0,2 USD/1 milione: "minimax/MiniMax-M2.1"
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— GRATUITO: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— GRATUITO: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— GRATUITO: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
@@ -538,17 +582,19 @@ vlicense LICENSE
**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Perplessità (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**Insieme AI (`insieme/`)**: `insieme/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**Fuochi d'artificio AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -556,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Aggiungi qualsiasi ID modello a qualsiasi provider senza attendere un aggiornamento dell'app:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -564,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Oppure utilizza la Dashboard:**Provider → [Provider] → Modelli personalizzati**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Note:
+Notes:
-- I provider compatibili con OpenRouter e OpenAI/Anthropic sono gestiti solo da**Modelli disponibili**. L'aggiunta manuale, l'importazione e la sincronizzazione automatica rientrano tutti nello stesso elenco di modelli disponibili, quindi non esiste una sezione Modelli personalizzati separata per tali fornitori.
-- La sezione**Modelli personalizzati**è destinata ai fornitori che non espongono le importazioni gestite di modelli disponibili.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Instrada le richieste direttamente a un fornitore specifico con convalida del modello:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Se mancante, il prefisso del provider viene aggiunto automaticamente. I modelli non corrispondenti restituiscono "400".### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -594,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Precedenza:**Specifico per chiave → Specifico per combo → Specifico per provider → Globale → Ambiente.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Restituisce modelli raggruppati per provider con tipi (`chat`, `embedding`, `image`).### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Sincronizza provider, combo e impostazioni su tutti i dispositivi
-- Sincronizzazione automatica in background con timeout + fail-fast
-- Preferisci `BASE_URL`/`CLOUD_URL` lato server in produzione### Cloudflare Quick Tunnel
+### Cloud Sync
-- Disponibile in**Dashboard → Endpoint**per Docker e altre distribuzioni self-hosted
-- Crea un URL temporaneo `https://*.trycloudflare.com` che inoltra al tuo attuale endpoint `/v1` compatibile con OpenAI
-- Per prima cosa abilita l'installazione di `cloudflared` solo quando necessario; i riavvii successivi riutilizzano lo stesso file binario gestito
-- I tunnel rapidi non vengono ripristinati automaticamente dopo il riavvio di OmniRoute o del contenitore; riattivarli dalla dashboard quando necessario
-- Gli URL dei tunnel sono effimeri e cambiano ogni volta che interrompi/avvii il tunnel
-- I tunnel rapidi gestiti utilizzano per impostazione predefinita il trasporto HTTP/2 per evitare avvisi rumorosi del buffer QUIC UDP nei contenitori vincolati
-- Imposta `CLOUDFLARED_PROTOCOL=quic` o `auto` se desideri sovrascrivere la scelta del trasporto gestito
-- Imposta `CLOUDFLARED_BIN` se preferisci utilizzare un binario `cloudflared` preinstallato invece del download gestito### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Cache semantica**— Memorizza automaticamente nella cache le risposte non-streaming, temperatura=0 (ignora con `X-OmniRoute-No-Cache: true`) -**Request Idempotency**: deduplica le richieste entro 5 secondi tramite l'intestazione "Idempotency-Key" o "X-Request-Id" -**Monitoraggio dei progressi**: attivazione degli eventi SSE "event: progress" tramite l'intestazione "X-OmniRoute-Progress: true"---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Accesso tramite**Dashboard → Traduttore**. Eseguire il debug e visualizzare il modo in cui OmniRoute traduce le richieste API tra provider.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Modalità | Scopo |
-| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| **Parco giochi** | Seleziona i formati di origine/destinazione, incolla una richiesta e visualizza immediatamente l'output tradotto |
-| **Tester della chat** | Invia messaggi di chat dal vivo tramite il proxy e controlla l'intero ciclo di richiesta/risposta |
-| **Banco di prova** | Esegui test batch su più combinazioni di formati per verificare la correttezza della traduzione |
-| **Monitoraggio dal vivo** | Guarda le traduzioni in tempo reale mentre le richieste passano attraverso il proxy |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Casi d'uso:**
+**Use cases:**
-- Debug del motivo per cui una specifica combinazione client/provider non riesce
-- Verificare che i tag pensanti, le chiamate agli strumenti e i prompt di sistema vengano tradotti correttamente
-- Confronta le differenze di formato tra i formati OpenAI, Claude, Gemini e Responses API---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Configura tramite**Dashboard → Impostazioni → Routing**.
+Configure via **Dashboard → Settings → Routing**.
-| Strategia | Descrizione |
-| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Compila prima** | Utilizza gli account in ordine di priorità: l'account principale gestisce tutte le richieste fino a quando non è disponibile |
-| **Round Robin** | Scorre tutti gli account con un limite permanente configurabile (impostazione predefinita: 3 chiamate per account) |
-| **P2C (il potere di due scelte)** | Scegli 2 account casuali e percorsi verso quello più sano: bilancia il carico con la consapevolezza della salute |
-| **Casuale** | Seleziona casualmente un account per ciascuna richiesta utilizzando Fisher-Yates shuffle |
-| **Meno usato** | Instrada all'account con il timestamp "lastUsedAt" più vecchio, distribuendo il traffico in modo uniforme |
-| **Costi ottimizzati** | Instrada all'account con il valore di priorità più basso, ottimizzando per i fornitori a basso costo | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Per l'affinità di sessione esterna (ad esempio, agenti Claude Code/Codex dietro proxy inversi), inviare:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute accetta anche "x_session_id" e restituisce la chiave di sessione effettiva in "X-OmniRoute-Session-Id".
+If you use Nginx and send underscore-form headers, enable:
-Se utilizzi Nginx e invii intestazioni in formato underscore, abilita:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Crea modelli con caratteri jolly per rimappare i nomi dei modelli:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-I caratteri jolly supportano "*" (qualsiasi carattere) e "?" (carattere singolo).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Definisci catene di fallback globali che si applicano a tutte le richieste:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Configura tramite**Dashboard → Impostazioni → Resilienza**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute implementa la resilienza a livello di fornitore con quattro componenti:
+OmniRoute implements provider-level resilience with four components:
-1.**Profili fornitore**: configurazione per fornitore per:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Soglia di guasto (quanti guasti prima dell'apertura)
-- Durata del raffreddamento
-- Sensibilità di rilevamento del limite di velocità
-- Parametri di backoff esponenziale
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Limiti di velocità modificabili**: impostazioni predefinite a livello di sistema configurabili nel dashboard: -**Richieste al minuto (RPM)**: numero massimo di richieste al minuto per account -**Tempo minimo tra le richieste**: intervallo minimo in millisecondi tra le richieste -**Numero massimo di richieste simultanee**: numero massimo di richieste simultanee per account
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Fai clic su**Modifica**per modificare, quindi su**Salva**o**Annulla**. I valori persistono tramite l'API di resilienza.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Interruttore di circuito**: tiene traccia dei guasti per fornitore e apre automaticamente il circuito quando viene raggiunta una soglia: -**CHIUSO**(integro): le richieste fluiscono normalmente -**APERTO**: il provider è temporaneamente bloccato dopo ripetuti errori -**HALF_OPEN**: verifica se il provider è stato ripristinato
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Criteri e identificatori bloccati**: mostra lo stato dell'interruttore automatico e gli identificatori bloccati con funzionalità di sblocco forzato.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Rilevamento automatico del limite di velocità**: monitora le intestazioni "429" e "Retry-After" per evitare in modo proattivo di raggiungere i limiti di velocità del provider.
-
-**Pro Tip:**Use**Reset All**button to clear all circuit breakers and cooldowns when a provider recovers from an outage.---
+---
### Database Export / Import
-Gestisci i backup del database in**Dashboard → Impostazioni → Sistema e archiviazione**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Azione | Descrizione |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
-| **Esporta database** | Scarica il database SQLite corrente come file `.sqlite` |
-| **Esporta tutto (.tar.gz)** | Scarica un archivio di backup completo che include: database, impostazioni, combo, connessioni al provider (nessuna credenziale), metadati della chiave API |
-| **Importa database** | Carica un file `.sqlite` per sostituire il database corrente. Un backup pre-importazione viene creato automaticamente a meno che `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Convalida dell'importazione:**il file importato viene convalidato per l'integrità (controllo pragma SQLite), le tabelle richieste (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) e le dimensioni (max 100 MB).
+**Use Cases:**
-**Casi d'uso:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Migrare OmniRoute tra macchine
-- Creare backup esterni per il ripristino di emergenza
-- Condividi le configurazioni tra i membri del team (esporta tutto → condividi archivio)---
+---
### Settings Dashboard
-La pagina delle impostazioni è organizzata in 6 schede per una facile navigazione:
+The settings page is organized into 6 tabs for easy navigation:
-| Scheda | Contenuto |
-| -------------- | ---------------------------------------------------------------------------------------- |
-|**Generale**| Strumenti di archiviazione del sistema, impostazioni dell'aspetto, controlli del tema e visibilità della barra laterale per elemento |
-|**Sicurezza**| Impostazioni login/password, controllo accesso IP, autenticazione API per `/models` e blocco provider |
-|**Percorso**| Strategia di routing globale (6 opzioni), alias del modello con caratteri jolly, catene di fallback, impostazioni predefinite combinate |
-|**Resilienza**| Profili dei fornitori, limiti di velocità modificabili, stato dell'interruttore automatico, policy e identificatori bloccati |
-|**AI**| Pensare alla configurazione del budget, all'inserimento dei prompt del sistema globale, alle statistiche della cache dei prompt |
-|**Avanzato**| Configurazione proxy globale (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Accesso tramite**Dashboard → Costi**.
+Access via **Dashboard → Costs**.
-| Scheda | Scopo |
-| ----------- | ---------------------------------------------------------------------------------- |
-|**Bilancio**| Imposta limiti di spesa per chiave API con budget giornalieri/settimanali/mensili e monitoraggio in tempo reale |
-|**Prezzi**| Visualizza e modifica le voci dei prezzi dei modelli: costo per token di input/output da 1.000 per fornitore |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -765,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Monitoraggio dei costi:**ogni richiesta registra l'utilizzo del token e calcola il costo utilizzando la tabella dei prezzi. Visualizza i dettagli in**Dashboard → Utilizzo**per provider, modello e chiave API.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute supporta la trascrizione audio tramite l'endpoint compatibile con OpenAI:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Provider disponibili:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Formati audio supportati: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.---
+---
### Combo Balancing Strategies
-Configura il bilanciamento per combo in**Dashboard → Combo → Crea/Modifica → Strategia**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Strategia | Descrizione |
-| ------------------ | ------------------------------------------------------------------------------- |
-|**Round-Robin**| Ruota i modelli in sequenza |
-|**Priorità**| Prova sempre il primo modello; ricorre solo in caso di errore |
-|**Casuale**| Sceglie un modello casuale dalla combo per ogni richiesta |
-|**Ponderato**| Percorsi proporzionali in base ai pesi assegnati per modello |
-|**Meno utilizzato**| Indirizza al modello con il minor numero di richieste recenti (utilizza metriche combinate) |
-|**Ottimizzazione dei costi**| Itinerari verso il modello disponibile più economico (utilizza la tabella dei prezzi) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Le impostazioni predefinite globali della combo possono essere impostate in**Dashboard → Impostazioni → Routing → Impostazioni combo**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Accesso tramite**Dashboard → Salute**. Panoramica sullo stato del sistema in tempo reale con 6 carte:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Carta | Cosa mostra |
-| --------------------- | ------------------------------------------------------------ |
-|**Stato del sistema**| Tempo di attività, versione, utilizzo della memoria, directory dei dati |
-|**Salute del fornitore**| Stato dell'interruttore automatico per provider (chiuso/aperto/semiaperto) |
-|**Limiti di tariffa**| Raffreddamenti del limite di velocità attivi per account con tempo rimanente |
-|**Blocchi attivi**| Provider temporaneamente bloccati dalla politica di blocco |
-|**Cache delle firme**| Statistiche della cache di deduplicazione (chiavi attive, percentuale di successo) |
-|**Telemetria della latenza**| Aggregazione della latenza p50/p95/p99 per provider |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Suggerimento avanzato:**la pagina Salute si aggiorna automaticamente ogni 10 secondi. Utilizza la scheda dell'interruttore per identificare quali fornitori stanno riscontrando problemi.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute è disponibile come applicazione desktop nativa per Windows, macOS e Linux.### Installare
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Installare
```bash
# From the electron directory:
@@ -833,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -845,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Uscita → "elettrone/dist-elettrone/".### Key Features
+Output → `electron/dist-electron/`
-| Caratteristica | Descrizione |
-| --------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------- |
-| **Predisposizione del server** | Esegue il polling del server prima di mostrare la finestra (nessuna schermata vuota) |
-| **Vassoio di sistema** | Riduci a icona nel vassoio, cambia porta, esci dal menu del vassoio |
-| **Gestione del porto** | Cambia la porta del server dal vassoio (server con riavvio automatico) |
-| **Politica di sicurezza dei contenuti** | CSP restrittivo tramite intestazioni di sessione |
-| **Istanza singola** | È possibile eseguire solo un'istanza dell'app alla volta |
-| **Modalità offline** | Il server Next.js in bundle funziona senza Internet | ### Environment Variables |
+### Key Features
-| Variabile | Predefinito | Descrizione |
-| --------------------- | ----------- | ------------------------------------ |
-| `OMNIROUTE_PORT` | `20128` | Porta del server |
-| `OMNIROUTE_MEMORY_MB` | "512" | Limite heap di Node.js (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Documentazione completa: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/ja/README.md b/docs/i18n/ja/README.md
index e314c6cf0e..5bd054814c 100644
--- a/docs/i18n/ja/README.md
+++ b/docs/i18n/ja/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/ja/docs/USER_GUIDE.md b/docs/i18n/ja/docs/USER_GUIDE.md
index 437da7cff9..71bd55b109 100644
--- a/docs/i18n/ja/docs/USER_GUIDE.md
+++ b/docs/i18n/ja/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-プロバイダーの構成、コンボの作成、CLI ツールの統合、OmniRoute の展開に関する完全なガイド。---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [価格の概要](#-価格の概要)
-- [ユースケース](#-use-cases)
-- [プロバイダーのセットアップ](#-provider-setup)
-- [CLI統合](#-cli-integration)
-- [展開](#-展開)
-- [利用可能なモデル](#-available-models)
-- [高度な機能](#-advanced-features)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 Pricing at a Glance
-| 階層 | プロバイダー | コスト | クォータのリセット | 最適な用途 |
-| ------------------------- | -------------------------- | --------------------- | ------------------- | ---------------------- |
-| **💳 サブスクリプション** | クロード・コード (プロ) | $20/月 | 5 時間 + 毎週 | すでに購読済み |
-| | コーデックス (プラス/プロ) | $20-200/月 | 5 時間 + 毎週 | OpenAI ユーザー |
-| | ジェミニ CLI | **無料** | 180K/月 + 1K/日 | みんな！ |
-| | GitHub コパイロット | $10-19/月 | 月刊 | GitHub ユーザー |
-| **🔑 API キー** | ディープシーク | 使用ごとに支払い | なし | 安っぽい推論 |
-| | グロク | 使用ごとに支払い | なし | 超高速推論 |
-| | xAI (グロック) | 使用ごとに支払い | なし | Grok 4 の推論 |
-| | ミストラル | 使用ごとに支払い | なし | EU がホストするモデル |
-| | 困惑 | 使用ごとに支払い | なし | 検索拡張 |
-| | 一緒にAI | 使用ごとに支払い | なし | オープンソース モデル |
-| | 花火AI | 使用ごとに支払い | なし | 高速 FLUX 画像 |
-| | 大脳 | 使用ごとに支払い | なし | ウェーハスケールの速度 |
-| | コヒア | 使用ごとに支払い | なし | コマンド R+ RAG |
-| | NVIDIA NIM | 使用ごとに支払い | なし | エンタープライズモデル |
-| **💰安い** | GLM-4.7 | $0.6/100万 | 毎日午前 10 時 | 予算のバックアップ |
-| | ミニマックス M2.1 | $0.2/100万 | 5時間ローリング | 最も安いオプション |
-| | キミ K2 | 月額 9 ドルのフラット | 1,000 万トークン/月 | 予測可能なコスト |
-| **🆓 無料** | コーダー | $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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 プロのヒント:**Gemini CLI (180K 無料/月) + Qoder (無制限の無料) コンボ = コスト 0 ドルから始めましょう!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**問題:**大量のコーディング中にクォータが使用されずに期限切れになり、レート制限が発生する```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**問題:**サブスクリプションを購入する余裕がないため、信頼性の高い AI コーディングが必要です```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**問題:**締め切りが迫っており、ダウンタイムを許すことができません```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**問題:**メッセージング アプリには AI アシスタントが必要ですが、完全に無料です```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**プロのヒント:**複雑なタスクには Opus を使用し、速度を求める場合は Sonnet を使用します。 OmniRoute はモデルごとの割り当てを追跡します。#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**ベストバリュー:**膨大な無料枠!有料レベルの前にこれを使用してください。#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,20 +175,27 @@ Models:
#### 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` —**プロのヒント:**コーディング プランは 1/7 のコストで 3 倍のクォータを提供します。毎日午前 10 時にリセットされます。#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. サインアップ：[MiniMax](https://www.minimax.io/)
-2. APIキーの取得 → ダッシュボード → APIキーの追加
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**使用方法:**`minimax/MiniMax-M2.1` —**プロのヒント:**長いコンテキスト (100 万トークン) の最も安価なオプション!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. 購読：[ムーンショット AI](https://platform.moonshot.ai/)
-2. APIキーの取得 → ダッシュボード → APIキーの追加
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**使用方法:**`kimi/kimi-latest` —**プロのヒント:**1,000 万トークンの固定 $9/月 = 0.90 ドル/100 万の実効コスト!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -202,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -243,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-`~/.claude/config.json` を編集します。```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -257,41 +283,42 @@ Settings → Models → Advanced:
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-`~/.openclaw/openclaw.json` を編集します。```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**またはダッシュボードを使用します:**CLI ツール → OpenClaw → 自動構成### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -312,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI は、`~/.omniroute/.env` または `./.env` から `.env` を自動的にロードします。### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -335,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-RAM が制限されているサーバーの場合は、メモリ制限オプションを使用します。```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-「ecosystem.config.js」を作成します。```javascript
+```javascript
module.exports = {
apps: [
{
@@ -369,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -381,13 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-CLI バイナリを使用したホスト統合モードについては、メイン ドキュメントの Docker セクションを参照してください。### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Void Linux ユーザーは、「xbps-src」クロスコンパイル フレームワークを使用して、OmniRoute をネイティブにパッケージ化し、インストールできます。これにより、必要な「better-sqlite3」ネイティブ バインディングとともに Node.js スタンドアロン ビルドが自動化されます。
+### Void Linux (xbps-src)
-<詳細>
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
-xbps-src テンプレートの表示```bash
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -408,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -475,80 +516,85 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-|変数 |デフォルト |説明 |
-| -------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT 署名シークレット (**本番環境での変更**) |
-| `初期パスワード` | `123456` |初回ログインパスワード |
-| `DATA_DIR` | `~/.omniroute` |データ ディレクトリ (データベース、使用状況、ログ) |
-| `ポート` |フレームワークのデフォルト |サービスポート (例では「20128」) |
-| `ホスト名` |フレームワークのデフォルト |ホストをバインドします (Docker のデフォルトは「0.0.0.0」です)。
-| `NODE_ENV` |実行時のデフォルト |デプロイ用に「production」を設定 |
-| `BASE_URL` | `http://localhost:20128` |サーバー側の内部ベース URL |
-| `CLOUD_URL` | `https://omniroute.dev` |クラウド同期エンドポイントのベース URL |
-| `API_KEY_SECRET` | `エンドポイント プロキシ API キー シークレット` |生成された API キーの HMAC シークレット |
-| `REQUIRE_API_KEY` | `偽` | Bearer API キーを `/v1/*` に強制する |
-| `ALLOW_API_KEY_REVEAL` | `偽` | API Manager が完全な API キーをオンデマンドでコピーできるようにする |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` |キャッシュされたプロバイダー制限データのサーバー側の更新頻度。 UI 更新ボタンは引き続き手動同期をトリガーします。
-| `DISABLE_SQLITE_AUTO_BACKUP` | `偽` |書き込み/インポート/復元の前に自動 SQLite スナップショットを無効にします。手動バックアップは引き続き機能します。
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `偽` | 「セキュア」認証 Cookie を強制する (HTTPS リバース プロキシの背後で) |
-| `CLOUDFLARED_BIN` |設定を解除する |管理されたダウンロードの代わりに既存の「cloudflared」バイナリを使用します。
-| `CLOUDFLARED_PROTOCOL` | `http2` |管理されたクイック トンネルのトランスポート (`http2`、`quic`、または `auto`) |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js ヒープ制限 (MB) |
-| `PROMPT_CACHE_MAX_SIZE` | `50` |プロンプト キャッシュ エントリの最大数 |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` |セマンティック キャッシュ エントリの最大数 |環境変数の完全なリファレンスについては、[README](../README.md) を参照してください。---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-<詳細>
-利用可能なすべてのモデルを表示する
+
+View all available models
-**クロード コード (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`、`cc/claude-sonnet-4-5-20250929`、`cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**コーデックス (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`、`cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— 無料: `gc/gemini-3-flash-preview`、`gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**GitHub コパイロット (`gh/`)**: `gh/gpt-5`、`gh/claude-4.5-sonnet`
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— $0.6/1M: `glm/glm-4.7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— $0.2/1M: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— 無料: `if/kimi-k2- Thinking`、`if/qwen3-coder-plus`、`if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— 無料: `qw/qwen3-coder-plus`、`qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**キロ (`kr/`)**— 無料: `kr/claude-sonnet-4.5`、`kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
-**ディープシーク (`ds/`)**: `ds/deepseek-chat`、`ds/deepseek-reasoner`
+**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
-**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`、`groq/llama-4-maverick-17b-128e-instruct`
+**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
-**xAI (`xai/`)**: `xai/grok-4`、`xai/grok-4-0709-fast-reasoning`、`xai/grok-code-mini`
+**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
-**ミストラル (`mistral/`)**: `mistral/mistral-large-2501`、`mistral/codestral-2501`
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**混乱 (`pplx/`)**: `pplx/sonar-pro`、`pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**セレブラス (`cerebras/`)**: `cerebras/llama-3.3-70b`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -556,7 +602,9 @@ vlicense LICENSE
### Custom Models
-アプリの更新を待たずに、任意のモデル ID を任意のプロバイダーに追加します。```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -564,22 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-または、ダッシュボードを使用します:**プロバイダー → [プロバイダー] → カスタム モデル**。
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-注:
+Notes:
-- OpenRouter および OpenAI/Anthropic 互換プロバイダーは、**利用可能なモデル**からのみ管理されます。手動による追加、インポート、および自動同期はすべて同じ利用可能なモデルのリストに含まれるため、これらのプロバイダー用の個別のカスタム モデル セクションはありません。-**カスタム モデル**セクションは、管理された利用可能なモデルのインポートを公開しないプロバイダーを対象としています。### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-モデル検証を使用してリクエストを特定のプロバイダーに直接ルーティングします。```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-プロバイダーのプレフィックスが存在しない場合は、自動的に追加されます。モデルが一致しない場合は「400」が返されます。### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -593,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**優先順位:**キー固有 → コンボ固有 → プロバイダー固有 → グローバル → 環境。### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-タイプ (`chat`、`embedding`、`image`) を持つプロバイダーごとにグループ化されたモデルを返します。### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- デバイス間でプロバイダー、コンボ、設定を同期します
-- タイムアウト + フェイルファストによる自動バックグラウンド同期
-- 運用環境ではサーバー側の `BASE_URL`/`CLOUD_URL` を優先します### Cloudflare Quick Tunnel
+### Cloud Sync
-- Docker およびその他のセルフホスト型デプロイメントでは、**ダッシュボード → エンドポイント**で利用可能
-- 現在の OpenAI 互換の `/v1` エンドポイントに転送する一時的な `https://*.trycloudflare.com` URL を作成します
-- まず、必要な場合にのみ「cloudflared」のインストールを有効にします。後で再起動すると同じマネージドバイナリが再利用されます
-- クイック トンネルは、OmniRoute またはコンテナの再起動後に自動復元されません。必要に応じてダッシュボードから再度有効化します
-- トンネル URL は一時的なものであり、トンネルを停止/開始するたびに変更されます。
-- マネージド クイック トンネルはデフォルトで HTTP/2 トランスポートになり、制限されたコンテナ内でのノイズの多い QUIC UDP バッファ警告を回避します
-- マネージドトランスポートの選択をオーバーライドする場合は、「CLOUDFLARED_PROTOCOL=quic」または「auto」を設定します。
-- 管理されたダウンロードの代わりにプレインストールされた `cloudflared` バイナリを使用したい場合は、`CLOUDFLARED_BIN` を設定します。### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**セマンティック キャッシュ**— 非ストリーミング、温度=0 の応答を自動キャッシュします (「X-OmniRoute-No-Cache: true」でバイパス) -**リクエスト冪等性**— `Idempotency-Key` または `X-Request-Id` ヘッダーを介して 5 秒以内にリクエストの重複を排除します。-**進行状況の追跡**— `X-OmniRoute-Progress: true` ヘッダーを介した SSE `event: progress` イベントのオプトイン---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-**ダッシュボード → トランスレーター**からアクセスします。 OmniRoute がプロバイダー間で API リクエストをどのように変換するかをデバッグして視覚化します。
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| モード | 目的 |
-| --------------------- | --------------------------------------------------------------------------------------------- |
-| **遊び場** | ソース/ターゲット形式を選択し、リクエストを貼り付けると、翻訳された出力が即座に表示されます。 |
-| **チャット テスター** | プロキシ経由でライブ チャット メッセージを送信し、完全な要求/応答サイクルを検査します。 |
-| **テストベンチ** | 複数の形式の組み合わせに対してバッチ テストを実行して、翻訳の正確さを検証します。 |
-| **ライブモニター** | リクエストがプロキシを通過するときにリアルタイムの翻訳を監視します。 |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**使用例:**
+**Use cases:**
-- 特定のクライアント/プロバイダーの組み合わせが失敗する理由をデバッグする
-- 思考タグ、ツール呼び出し、システム プロンプトが正しく翻訳されていることを確認します。
-- OpenAI、Claude、Gemini、および Responses API 形式間の形式の違いを比較します。---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-**[ダッシュボード] → [設定] → [ルーティング]**から設定します。
+Configure via **Dashboard → Settings → Routing**.
-| 戦略 | 説明 |
-| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
-| **最初に入力してください** | 優先順位に従ってアカウントを使用します。プライマリ アカウントは利用できなくなるまですべてのリクエストを処理します。 |
-| **ラウンドロビン** | 設定可能なスティッキー制限を使用して、すべてのアカウントを循環します (デフォルト: アカウントごとに 3 コール)。 |
-| **P2C (2 つの選択肢の累乗)** | ランダムな 2 つのアカウントを選択し、より健全なアカウントにルーティングします — 健康を意識しながら負荷のバランスをとります |
-| **ランダム** | Fisher-Yates shuffle | を使用してリクエストごとにアカウントをランダムに選択します。 |
-| **使用頻度が最も低い** | 最も古い「lastusedAt」タイムスタンプを持つアカウントにルーティングし、トラフィックを均等に分散します。 |
-| **コストの最適化** | 最も低い優先順位の値を持つアカウントにルーティングし、最もコストの低いプロバイダー向けに最適化します。#### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-外部セッション アフィニティ (リバース プロキシの背後にある Claude Code/Codex エージェントなど) の場合は、次を送信します。```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute は「x_session_id」も受け入れ、有効なセッション キーを「X-OmniRoute-Session-Id」に返します。
+If you use Nginx and send underscore-form headers, enable:
-Nginx を使用し、アンダースコア形式のヘッダーを送信する場合は、次を有効にします。```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-ワイルドカード パターンを作成してモデル名を再マッピングします。```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-ワイルドカードは「*」（任意の文字）と「?」（単一文字）をサポートします。#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-すべてのリクエストに適用されるグローバル フォールバック チェーンを定義します。```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-**ダッシュボード → 設定 → レジリエンス**から設定します。
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute は、次の 4 つのコンポーネントでプロバイダー レベルの復元力を実装します。
+OmniRoute implements provider-level resilience with four components:
-1.**プロバイダー プロファイル**— 以下のプロバイダーごとの構成:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- 失敗しきい値 (開くまでに何回失敗したか)
-- クールダウン期間
-- レート制限検出感度
-- 指数バックオフパラメータ
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**編集可能なレート制限**— ダッシュボードで構成可能なシステムレベルのデフォルト: -**1 分あたりのリクエスト数 (RPM)**— アカウントごとの 1 分あたりの最大リクエスト数 -**リクエスト間の最小時間**— リクエスト間の最小ギャップ (ミリ秒単位) -**最大同時リクエスト**— アカウントあたりの最大同時リクエスト
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- [**編集**] をクリックして変更し、**保存**または**キャンセル**をクリックします。値は復元 API を介して保持されます。
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**サーキット ブレーカー**— プロバイダーごとに障害を追跡し、しきい値に達すると自動的に回線を開きます。-**クローズ**(正常) — リクエストは正常に流れます -**OPEN**— プロバイダーは失敗が繰り返された後、一時的にブロックされています -**HALF_OPEN**— プロバイダーが回復したかどうかをテストします
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**ポリシーとロックされた識別子**— 強制ロック解除機能を備えたサーキット ブレーカーのステータスとロックされた識別子を表示します。
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**レート制限の自動検出**- 「429」ヘッダーと「Retry-After」ヘッダーを監視して、プロバイダーのレート制限に達することを事前に回避します。
-
-**プロのヒント:**プロバイダーが停止から回復したときに、**すべてリセット**ボタンを使用して、すべてのサーキット ブレーカーとクールダウンをクリアします。---
+---
### Database Export / Import
-**[ダッシュボード] > [設定] > [システムとストレージ]**でデータベースのバックアップを管理します。
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| アクション | 説明 |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **データベースのエクスポート** | 現在の SQLite データベースを `.sqlite` ファイルとしてダウンロードします。 |
-| **すべてエクスポート (.tar.gz)** | データベース、設定、コンボ、プロバイダー接続 (認証情報なし)、API キー メタデータを含む完全なバックアップ アーカイブをダウンロードします。 |
-| **データベースのインポート** | `.sqlite` ファイルをアップロードして現在のデータベースを置き換えます。 `DISABLE_SQLITE_AUTO_BACKUP=true` でない限り、インポート前のバックアップは自動的に作成されます。```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**インポートの検証:**インポートされたファイルは、整合性 (SQLite プラグマ チェック)、必要なテーブル (`provider_connections`、`provider_nodes`、`combos`、`api_keys`)、およびサイズ (最大 100MB) について検証されます。
+**Use Cases:**
-**使用例:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- マシン間で OmniRoute を移行する
-- 災害復旧のために外部バックアップを作成する
-- チームメンバー間で設定を共有（すべてエクスポート→アーカイブを共有）---
+---
### Settings Dashboard
-設定ページは 6 つのタブで構成されており、簡単にナビゲーションできます。
+The settings page is organized into 6 tabs for easy navigation:
-|タブ |目次 |
+| Tab | Contents |
| -------------- | ---------------------------------------------------------------------------------------------- |
-|**一般**|システム ストレージ ツール、外観設定、テーマ コントロール、項目ごとのサイドバーの表示設定 |
-|**セキュリティ**|ログイン/パスワード設定、IP アクセス制御、`/models` の API 認証、およびプロバイダーのブロック |
-|**ルーティング**|グローバル ルーティング戦略 (6 つのオプション)、ワイルドカード モデル エイリアス、フォールバック チェーン、コンボ デフォルト |
-|**回復力**|プロバイダー プロファイル、編集可能なレート制限、サーキット ブレーカーのステータス、ポリシー、ロックされた識別子 |
-|**AI**|予算構成、グローバル システム プロンプト インジェクション、プロンプト キャッシュ統計を考える |
-|**上級**|グローバル プロキシ構成 (HTTP/SOCKS5) |---
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-**[ダッシュボード] → [コスト]**からアクセスします。
+Access via **Dashboard → Costs**.
-|タブ |目的 |
-| ----------- | -------------------------------------------------------------------------------------- |
-|**予算**|日次/週次/月次の予算とリアルタイムの追跡を使用して、API キーごとに支出制限を設定 |
-|**価格**|モデル価格エントリの表示と編集 - プロバイダーごとの 1K 入出力トークンあたりのコスト |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -764,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**コスト追跡:**すべてのリクエストはトークンの使用状況を記録し、価格表を使用してコストを計算します。**[ダッシュボード] → [使用状況]**で、プロバイダー、モデル、API キーごとの内訳を表示します。---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute は、OpenAI 互換エンドポイントを介した音声転写をサポートしています。```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-利用可能なプロバイダー:**Deepgram**(`deepgram/`)、**AssemblyAI**(`assemblyai/`)。
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-サポートされているオーディオ形式: `mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm`。---
+---
### Combo Balancing Strategies
-**ダッシュボード → コンボ → 作成/編集 → 戦略**でコンボごとのバランスを設定します。
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-|戦略 |説明 |
-| ------------------ | ---------------------------------------------------------------------- |
-|**ラウンドロビン**|モデルを順番に回転します。
-|**優先度**|常に最初のモデルを試します。エラーの場合のみフォールバック |
-|**ランダム**|各リクエストのコンボからランダムなモデルを選択します。
-|**加重**|モデルごとに割り当てられた重みに基づいて比例的にルーティングします。
-|**Least-Used** |最近のリクエストが最も少ないモデルにルーティングします (コンボ メトリックを使用) |
-|**コストの最適化**|利用可能な最も安価なモデルへのルート (価格表を使用) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-グローバル コンボ デフォルトは、**[ダッシュボード] → [設定] → [ルーティング] → [コンボ デフォルト]**で設定できます。---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-**「ダッシュボード」→「ヘルス」**からアクセスします。 6 枚のカードによるリアルタイムのシステム状態の概要:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-|カード |それが示すもの |
-| --------------------- | -------------------------------------------------------- |
-|**システムステータス**| Uptime, version, memory usage, data directory |
-|**プロバイダーの状態**|プロバイダーごとのサーキット ブレーカーの状態 (クローズ/オープン/ハーフオープン) |
-|**レート制限**|アカウントごとのアクティブなレート制限クールダウンと残り時間 |
-|**アクティブなロックアウト**|ロックアウト ポリシーによって一時的にブロックされたプロバイダー |
-|**署名キャッシュ**|重複排除キャッシュの統計 (アクティブなキー、ヒット率) |
-|**レイテンシ テレメトリ**|プロバイダーごとの p50/p95/p99 レイテンシの集計 |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**プロのヒント:**[ヘルス] ページは 10 秒ごとに自動更新されます。サーキット ブレーカー カードを使用して、どのプロバイダーで問題が発生しているかを特定します。---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute は、Windows、macOS、および Linux のネイティブ デスクトップ アプリケーションとして利用できます。### インストール
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### インストール
```bash
# From the electron directory:
@@ -832,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -844,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-出力 → `electron/dist-electron/`### Key Features
+Output → `electron/dist-electron/`
-| 特集 | 説明 |
-| ------------------------------------ | --------------------------------------------------------------------------- | ------------------------- |
-| **サーバーの準備状況** | ウィンドウを表示する前にサーバーをポーリングします (空白の画面はありません) |
-| **システム トレイ** | トレイに最小化、ポートを変更、トレイメニューから終了 |
-| **ポート管理** | トレイからサーバー ポートを変更する (サーバーの自動再起動) |
-| **コンテンツ セキュリティ ポリシー** | セッションヘッダーによる制限的な CSP |
-| **単一インスタンス** | 一度に実行できるアプリ インスタンスは 1 つだけです |
-| **オフライン モード** | バンドルされた Next.js サーバーはインターネットなしで動作します | ### Environment Variables |
+### Key Features
-| 変数 | デフォルト | 説明 |
-| --------------------- | ---------- | ----------------------------------- |
-| `オムニルート_ポート` | `20128` | サーバーポート |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js ヒープ制限 (64 ～ 16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 完全なドキュメント: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/ko/README.md b/docs/i18n/ko/README.md
index 8d2206e2f4..32264b4965 100644
--- a/docs/i18n/ko/README.md
+++ b/docs/i18n/ko/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/ko/docs/USER_GUIDE.md b/docs/i18n/ko/docs/USER_GUIDE.md
index 84d2fa7b59..6aa64fed88 100644
--- a/docs/i18n/ko/docs/USER_GUIDE.md
+++ b/docs/i18n/ko/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-공급자 구성, 콤보 생성, CLI 도구 통합 및 OmniRoute 배포에 대한 전체 가이드입니다.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [한눈에 보는 가격](#-한눈에 가격)
-- [사용 사례](#-사용 사례)
-- [공급자 설정](#-provider-setup)
-- [CLI 통합](#-cli-통합)
-- [배포](#-배포)
-- [사용 가능 모델](#-사용 가능-모델)
-- [고급 기능](#-advanced-features)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 Pricing at a Glance
-| 계층 | 공급자 | 비용 | 할당량 재설정 | 최고의 대상 |
-| ------------- | ------------------- | ------------------ | --------------- | ----------------- |
-| **💳 구독** | 클로드 코드 (Pro) | $20/월 | 5시간 + 매주 | 이미 구독 중 |
-| | 코덱스(플러스/프로) | $20-200/월 | 5시간 + 매주 | OpenAI 사용자 |
-| | 제미니 CLI | **무료** | 180K/월 + 1K/일 | 모든 사람! |
-| | GitHub 부조종사 | $10-19/월 | 월간 | GitHub 사용자 |
-| **🔑 API 키** | 딥시크 | 사용량에 따라 지불 | 없음 | 저렴한 추론 |
-| | 그로크 | 사용량에 따라 지불 | 없음 | 초고속 추론 |
-| | xAI(그록) | 사용량에 따라 지불 | 없음 | Grok 4 추론 |
-| | 미스트랄 | 사용량에 따라 지불 | 없음 | EU 주최 모델 |
-| | 당혹감 | 사용량에 따라 지불 | 없음 | 검색 증강 |
-| | 함께하는 AI | 사용량에 따라 지불 | 없음 | 오픈 소스 모델 |
-| | 불꽃놀이 AI | 사용량에 따라 지불 | 없음 | 빠른 FLUX 이미지 |
-| | 대뇌 | 사용량에 따라 지불 | 없음 | 웨이퍼 규모 속도 |
-| | 코히어 | 사용량에 따라 지불 | 없음 | 커맨드 R+ RAG |
-| | 엔비디아 NIM | 사용량에 따라 지불 | 없음 | 엔터프라이즈 모델 |
-| **💰 저렴한** | GLM-4.7 | $0.6/1M | 매일 오전 10시 | 예산 백업 |
-| | 미니맥스 M2.1 | $0.2/1M | 5시간 롤링 | 가장 저렴한 옵션 |
-| | 키미 K2 | $9/월 정액 | 1000만 토큰/월 | 예측 가능한 비용 |
-| **🆓 무료** | Qoder | $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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 전문가 팁:**Gemini CLI(월 180K 무료) + Qoder(무제한 무료) 콤보 = 비용 $0로 시작하세요!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**문제:**할당량은 사용되지 않은 상태로 만료되며, 코딩을 많이 하는 동안 속도 제한이 발생합니다.```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**문제:**구독료를 감당할 수 없고 안정적인 AI 코딩이 필요함```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**문제:**마감일, 가동 중지 시간을 감당할 수 없음```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**문제:**메시징 앱에 AI 도우미가 필요하며 완전 무료입니다.```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**프로 팁:**복잡한 작업에는 Opus를 사용하고, 속도를 높이려면 Sonnet을 사용하세요. OmniRoute는 모델당 할당량을 추적합니다!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**최고의 가치:**엄청난 무료 등급! 유료 등급 이전에 사용하세요.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### 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` —**프로 팁:**코딩 계획은 1/7 비용으로 3배 할당량을 제공합니다! 매일 오전 10시에 초기화됩니다.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. 회원가입: [미니맥스](https://www.minimax.io/)
-2. API 키 받기 → 대시보드 → API 키 추가
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**사용:**`minimax/MiniMax-M2.1` —**프로 팁:**긴 컨텍스트(1M 토큰)를 위한 가장 저렴한 옵션!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. 구독: [문샷 AI](https://platform.moonshot.ai/)
-2. API 키 받기 → 대시보드 → API 키 추가
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**사용:**`kimi/kimi-latest` —**프로 팁:**1,000만 토큰에 대해 월 $9 고정 = 유효 비용 $0.90/1M!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-`~/.claude/config.json`을 편집합니다.```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Settings → Models → Advanced:
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-`~/.openclaw/openclaw.json`을 편집합니다.```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**또는 대시보드 사용:**CLI 도구 → OpenClaw → 자동 구성### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI는 `~/.omniroute/.env` 또는 `./.env`에서 `.env`를 자동으로 로드합니다.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-RAM이 제한된 서버의 경우 메모리 제한 옵션을 사용하십시오.```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-`ecosystem.config.js`를 생성합니다:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,13 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-CLI 바이너리를 사용한 호스트 통합 모드의 경우 기본 문서의 Docker 섹션을 참조하세요.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Void Linux 사용자는 'xbps-src' 크로스 컴파일 프레임워크를 사용하여 기본적으로 OmniRoute를 패키징하고 설치할 수 있습니다. 이는 필수 `better-sqlite3` 네이티브 바인딩과 함께 Node.js 독립 실행형 빌드를 자동화합니다.
+### Void Linux (xbps-src)
-<상세>
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
-xbps-src 템플릿 보기```bash
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -409,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -476,80 +516,85 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| 변수 | 기본값 | 설명 |
-| -------------------------- | ----------------------- | ------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT 서명 비밀(**프로덕션 변경**) |
-| `초기_비밀번호` | `123456` | 첫 번째 로그인 비밀번호 |
-| `DATA_DIR` | `~/.omniroute` | 데이터 디렉터리(db, 사용량, 로그) |
-| '포트' | 프레임워크 기본값 | 서비스 포트(예제에서는 `20128`) |
-| `호스트 이름` | 프레임워크 기본값 | 호스트 바인딩(Docker 기본값은 `0.0.0.0`) |
-| `NODE_ENV` | 런타임 기본값 | 배포를 위해 '프로덕션' 설정 |
-| `BASE_URL` | `http://localhost:20128` | 서버측 내부 기본 URL |
-| `CLOUD_URL` | `https://omniroute.dev` | 클라우드 동기화 엔드포인트 기본 URL |
-| `API_KEY_SECRET` | `엔드포인트-프록시-API-키-비밀` | 생성된 API 키에 대한 HMAC 비밀 |
-| `REQUIRE_API_KEY` | '거짓' | `/v1/*`에 Bearer API 키 적용 |
-| `ALLOW_API_KEY_REVEAL` | '거짓' | Api Manager가 요청 시 전체 API 키를 복사하도록 허용 |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | 캐시된 공급자 제한 데이터에 대한 서버측 새로 고침 주기. UI 새로 고침 버튼이 여전히 수동 동기화를 트리거합니다 |
-| DISABLE_SQLITE_AUTO_BACKUP` | '거짓' | 쓰기/가져오기/복원 전에 자동 SQLite 스냅샷을 비활성화합니다. 수동 백업은 여전히 작동합니다 |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | '거짓' | '보안' 인증 쿠키 강제 적용(HTTPS 역방향 프록시 뒤) |
-| `CLOUDFLARED_BIN` | 설정되지 않음 | 관리형 다운로드 대신 기존 `cloudflared` 바이너리 사용 |
-| `CLOUDFLARED_PROTOCOL` | `http2` | 관리형 빠른 터널을 위한 전송(`http2`, `quic` 또는 `auto`) |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js 힙 제한(MB) |
-| 'PROMPT_CACHE_MAX_SIZE' | `50` | 최대 프롬프트 캐시 항목 |
-| `SEMANTIC_CACHE_MAX_SIZE` | '100' | 최대 의미 캐시 항목 |전체 환경 변수 참조는 [README](../README.md)를 참조하세요.---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-<상세>
-사용 가능한 모든 모델 보기
+
+View all available models
-**Claude 코드(`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex(`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI(`gc/`)**— 무료: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**GitHub Copilot(`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— $0.6/1M: `glm/glm-4.7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax(`minimax/`)**— $0.2/1M: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder(`if/`)**— 무료: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen(`qw/`)**— 무료: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro(`kr/`)**— 무료: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
-**DeepSeek(`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
+**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
-**Groq(`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
+**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
-**미스트랄(`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Perplexity(`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**함께 AI(`함께/`)**: `함께/메타-라마/Llama-3.3-70B-Instruct-Turbo`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**Fireworks AI(`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**대뇌(`cerebras/`)**: `cerebras/llama-3.3-70b`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
-**Cohere(`cohere/`)**: `cohere/command-r-plus-08-2024`
+**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM(`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -557,7 +602,9 @@ vlicense LICENSE
### Custom Models
-앱 업데이트를 기다리지 않고 공급자에 모델 ID를 추가하세요.```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -565,22 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-또는 대시보드를 사용하십시오:**공급자 → [공급자] → 사용자 정의 모델**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-참고:
+Notes:
-- OpenRouter 및 OpenAI/Anthropic 호환 공급자는**사용 가능한 모델**에서만 관리됩니다. 수동 추가, 가져오기 및 자동 동기화는 모두 동일한 사용 가능한 모델 목록에 있으므로 해당 공급자에 대한 별도의 사용자 정의 모델 섹션이 없습니다. -**사용자 정의 모델**섹션은 관리 가능한 모델 가져오기를 노출하지 않는 공급자를 위한 것입니다.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-모델 검증을 통해 요청을 특정 공급자에게 직접 라우팅합니다.```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-공급자 접두사가 누락된 경우 자동으로 추가됩니다. 일치하지 않는 모델이 '400'을 반환합니다.### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -594,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**우선순위:**키별 → 콤보별 → 공급자별 → 글로벌 → 환경.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-유형(`chat`, `embedding`, `image`)을 사용하여 공급자별로 그룹화된 모델을 반환합니다.### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- 여러 장치에서 공급자, 콤보 및 설정을 동기화합니다.
-- 시간 초과 + 빠른 실패를 통한 자동 백그라운드 동기화
-- 프로덕션에서는 서버 측 `BASE_URL`/`CLOUD_URL`을 선호합니다.### Cloudflare Quick Tunnel
+### Cloud Sync
-- Docker 및 기타 자체 호스팅 배포를 위해**대시보드 → 엔드포인트**에서 사용 가능
-- 현재 OpenAI 호환 `/v1` 엔드포인트로 전달되는 임시 `https://*.trycloudflare.com` URL을 생성합니다.
-- 먼저 활성화하면 필요할 때만 'cloudflared'를 설치합니다. 나중에 다시 시작하면 동일한 관리 바이너리를 재사용합니다.
-- OmniRoute 또는 컨테이너를 다시 시작한 후에 빠른 터널이 자동으로 복원되지 않습니다. 필요할 때 대시보드에서 다시 활성화하세요.
-- 터널 URL은 일시적이며 터널을 중지/시작할 때마다 변경됩니다.
-- 제한된 컨테이너에서 시끄러운 QUIC UDP 버퍼 경고를 방지하기 위해 관리형 빠른 터널은 기본적으로 HTTP/2 전송으로 설정됩니다.
-- 관리형 전송 선택을 재정의하려면 `CLOUDFLARED_PROTOCOL=quic` 또는 `auto`를 설정하세요.
-- 관리형 다운로드 대신 사전 설치된 `cloudflared` 바이너리를 사용하려는 경우 `CLOUDFLARED_BIN`을 설정하세요.### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**의미론적 캐시**— 비스트리밍, 온도=0 응답을 자동 캐시합니다(`X-OmniRoute-No-Cache: true`로 우회). -**Idempotency 요청**— 'Idempotency-Key' 또는 'X-Request-Id' 헤더를 통해 5초 이내에 요청을 중복 제거합니다. -**진행 상황 추적**— `X-OmniRoute-Progress: true` 헤더를 통한 옵트인 SSE `event: Progress` 이벤트---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-**대시보드 → 번역기**를 통해 액세스합니다. OmniRoute가 공급자 간 API 요청을 변환하는 방법을 디버깅하고 시각화합니다.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| 모드 | 목적 |
-| ----------------- | ------------------------------------------------------------------------- |
-| **놀이터** | 소스/타겟 형식을 선택하고, 요청을 붙여넣고, 번역된 결과를 즉시 확인하세요 |
-| **채팅 테스터** | 프록시를 통해 실시간 채팅 메시지를 보내고 전체 요청/응답 주기 검사 |
-| **테스트 벤치** | 여러 형식 조합에 걸쳐 일괄 테스트를 실행하여 번역 정확성 확인 |
-| **라이브 모니터** | 프록시를 통한 요청 흐름에 따라 실시간 번역 보기 |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**사용 사례:**
+**Use cases:**
-- 특정 클라이언트/공급자 조합이 실패하는 이유 디버그
-- 생각 태그, 도구 호출 및 시스템 프롬프트가 올바르게 번역되는지 확인합니다.
-- OpenAI, Claude, Gemini 및 Responses API 형식 간의 형식 차이 비교---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-**대시보드 → 설정 → 라우팅**을 통해 구성합니다.
+Configure via **Dashboard → Settings → Routing**.
-| 전략 | 설명 |
-| -------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
-| **먼저 채우기** | 우선순위에 따라 계정을 사용합니다. 기본 계정은 사용할 수 없을 때까지 모든 요청을 처리합니다. |
-| **라운드 로빈** | 구성 가능한 고정 한도를 사용하여 모든 계정을 순환합니다(기본값: 계정당 호출 3회) |
-| **P2C(두 가지 선택의 힘)** | 2개의 무작위 계정을 선택하고 더 건강한 계정으로 라우팅 — 건강에 대한 인식과 부하의 균형을 유지 |
-| **랜덤** | Fisher-Yates shuffle | 을 사용하여 각 요청에 대해 무작위로 계정을 선택합니다. |
-| **최소 사용** | 가장 오래된 'lastUsedAt' 타임스탬프가 있는 계정으로 라우팅하여 트래픽을 균등하게 분산 |
-| **비용 최적화** | 가장 낮은 비용의 공급자를 위해 최적화하여 우선순위 값이 가장 낮은 계정으로 라우팅 | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-외부 세션 선호도(예: 역방향 프록시 뒤의 Claude Code/Codex 에이전트)의 경우 다음을 보냅니다.```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute는 'x_session_id'도 허용하고 'X-OmniRoute-Session-Id'에 유효한 세션 키를 반환합니다.
+If you use Nginx and send underscore-form headers, enable:
-Nginx를 사용하고 밑줄 형식 헤더를 보내는 경우 다음을 활성화합니다.```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-모델 이름을 다시 매핑하는 와일드카드 패턴을 만듭니다.```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-와일드카드는 `*`(모든 문자) 및 `?`(단일 문자)를 지원합니다.#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-모든 요청에 적용되는 전역 대체 체인을 정의합니다.```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-**대시보드 → 설정 → 복원력**을 통해 구성합니다.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute는 다음 네 가지 구성 요소를 사용하여 공급자 수준 복원력을 구현합니다.
+OmniRoute implements provider-level resilience with four components:
-1.**공급자 프로필**— 다음에 대한 공급자별 구성:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- 실패 임계값(개방 전 실패 횟수)
-- 쿨다운 시간
-- 비율 제한 감지 감도
-- 지수 백오프 매개변수
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**편집 가능한 속도 제한**— 대시보드에서 구성 가능한 시스템 수준 기본값: -**분당 요청(RPM)**— 계정당 분당 최대 요청 수 -**요청 간 최소 시간**— 요청 간 최소 간격(밀리초) -**최대 동시 요청**— 계정당 최대 동시 요청
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- 수정하려면**수정**을 클릭한 다음**저장**또는**취소**를 클릭하세요. 값은 복원력 API를 통해 유지됩니다.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**회로 차단기**— 공급자별 오류를 추적하고 임계값에 도달하면 자동으로 회로를 엽니다. -**CLOSED**(정상) — 요청 흐름이 정상적으로 진행됩니다. -**OPEN**— 반복적인 실패 후 공급자가 일시적으로 차단됩니다. -**HALF_OPEN**— 공급자가 복구되었는지 테스트
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**정책 및 잠긴 식별자**- 회로 차단기 상태와 강제 잠금 해제 기능이 있는 잠긴 식별자를 표시합니다.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**비율 제한 자동 감지**— '429' 및 'Retry-After' 헤더를 모니터링하여 공급자 비율 제한에 도달하는 것을 사전에 방지합니다.
-
-**프로 팁:**공급자가 중단에서 복구될 때**모두 재설정**버튼을 사용하여 모든 회로 차단기와 쿨다운을 해제합니다.---
+---
### Database Export / Import
-**대시보드 → 설정 → 시스템 및 스토리지**에서 데이터베이스 백업을 관리하세요.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| 액션 | 설명 |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
-| **데이터베이스 내보내기** | 현재 SQLite 데이터베이스를 '.sqlite' 파일로 다운로드 |
-| **모두 내보내기(.tar.gz)** | 데이터베이스, 설정, 콤보, 공급자 연결(자격 증명 없음), API 키 메타데이터를 포함한 전체 백업 아카이브를 다운로드합니다. |
-| **데이터베이스 가져오기** | 현재 데이터베이스를 대체하려면 '.sqlite' 파일을 업로드하세요. `DISABLE_SQLITE_AUTO_BACKUP=true`가 아니면 가져오기 전 백업이 자동으로 생성됩니다. | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**가져오기 검증:**가져온 파일은 무결성(SQLite pragma 검사), 필수 테이블(`provider_connections`, `provider_nodes`, `combos`, `api_keys`) 및 크기(최대 100MB)에 대해 검증됩니다.
+**Use Cases:**
-**사용 사례:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- 머신 간 OmniRoute 마이그레이션
-- 재해 복구를 위한 외부 백업 생성
-- 팀원 간 구성 공유(모두 내보내기 → 아카이브 공유)---
+---
### Settings Dashboard
-설정 페이지는 쉽게 탐색할 수 있도록 6개의 탭으로 구성되어 있습니다.
+The settings page is organized into 6 tabs for easy navigation:
-| 탭 | 내용 |
-| -------------- | --------------------------------------------------------------------------------- |
-|**일반**| 시스템 저장 도구, 모양 설정, 테마 제어 및 항목별 사이드바 가시성 |
-|**보안**| 로그인/비밀번호 설정, IP 액세스 제어, `/models`에 대한 API 인증 및 공급자 차단 |
-|**라우팅**| 글로벌 라우팅 전략(6개 옵션), 와일드카드 모델 별칭, 폴백 체인, 콤보 기본값 |
-|**탄력성**| 공급자 프로필, 편집 가능한 속도 제한, 회로 차단기 상태, 정책 및 잠긴 식별자 |
-|**AI**| 생각하는 예산 구성, 글로벌 시스템 프롬프트 주입, 프롬프트 캐시 통계 |
-|**고급**| 글로벌 프록시 구성(HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-**대시보드 → 비용**을 통해 액세스합니다.
+Access via **Dashboard → Costs**.
-| 탭 | 목적 |
-| ----------- | -------------------------------------------------------------- |
-|**예산**| 일별/주별/월별 예산 및 실시간 추적을 통해 API 키별 지출 한도 설정 |
-|**가격**| 모델 가격 항목 보기 및 편집 - 공급자당 입력/출력 토큰 1,000개당 비용 |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -765,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**비용 추적:**모든 요청은 토큰 사용량을 기록하고 가격표를 사용하여 비용을 계산합니다.**대시보드 → 사용량**에서 공급자, 모델, API 키별 분석을 확인하세요.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute는 OpenAI 호환 엔드포인트를 통해 오디오 전사를 지원합니다.```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-사용 가능한 공급자:**Deepgram**(`deepgram/`),**AssemblyAI**(`assembleai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-지원되는 오디오 형식: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.---
+---
### Combo Balancing Strategies
-**대시보드 → 콤보 → 생성/편집 → 전략**에서 콤보별 밸런싱을 구성하세요.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| 전략 | 설명 |
-| ------------------ | ----------------------------------------------------------- |
-|**라운드 로빈**| 모델을 순차적으로 회전 |
-|**우선순위**| 항상 첫 번째 모델을 시도합니다. 오류가 발생한 경우에만 폴백 |
-|**랜덤**| 각 요청에 대한 콤보에서 무작위 모델 선택 |
-|**가중치**| 모델별로 할당된 가중치를 기준으로 비례적으로 라우팅 |
-|**가장 적게 사용됨**| 최근 요청이 가장 적은 모델로 라우팅(콤보 메트릭 사용) |
-|**비용 최적화**| 가장 저렴한 모델로 연결(가격표 사용) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-글로벌 콤보 기본값은**대시보드 → 설정 → 라우팅 → 콤보 기본값**에서 설정할 수 있습니다.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-**대시보드 → 건강**을 통해 액세스합니다. 6개의 카드를 사용한 실시간 시스템 상태 개요:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| 카드 | 표시되는 내용 |
-| -------- | ---------------------------------------------- |
-|**시스템 상태**| 가동 시간, 버전, 메모리 사용량, 데이터 디렉터리 |
-|**제공자 건강**| 공급자별 회로 차단기 상태(폐쇄/개방/반개방) |
-|**비율 제한**| 남은 시간에 따른 계정당 활성 속도 제한 쿨다운 |
-|**활성 잠금**| 잠금 정책으로 인해 일시적으로 차단된 제공업체 |
-|**서명 캐시**| 중복 제거 캐시 통계(활성 키, 적중률) |
-|**지연 원격 측정**| 공급자별 p50/p95/p99 대기 시간 집계 |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**프로 팁:**상태 페이지는 10초마다 자동으로 새로 고쳐집니다. 회로 차단기 카드를 사용하여 어떤 공급자가 문제를 겪고 있는지 식별하십시오.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute는 Windows, macOS 및 Linux용 기본 데스크톱 애플리케이션으로 사용할 수 있습니다.### 설치
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### 설치
```bash
# From the electron directory:
@@ -833,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -845,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-출력 → `전자/dist-전자/`### Key Features
+Output → `electron/dist-electron/`
-| 기능 | 설명 |
-| -------------------- | ----------------------------------------------------- | ------------------------- |
-| **서버 준비 상태** | 창을 표시하기 전에 서버를 폴링합니다(빈 화면 없음) |
-| **시스템 트레이** | 트레이로 최소화, 포트 변경, 트레이 메뉴 종료 |
-| **항만 관리** | 트레이에서 서버 포트 변경(서버 자동 재시작) |
-| **콘텐츠 보안 정책** | 세션 헤더를 통한 제한적인 CSP |
-| **단일 인스턴스** | 한 번에 하나의 앱 인스턴스만 실행할 수 있습니다 |
-| **오프라인 모드** | 번들로 제공되는 Next.js 서버는 인터넷 없이 작동합니다 | ### Environment Variables |
+### Key Features
-| 변수 | 기본값 | 설명 |
-| --------------------- | ------- | --------------------------- |
-| `OMNIROUTE_PORT` | `20128` | 서버 포트 |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js 힙 제한(64~16384MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 전체 문서: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/ms/README.md b/docs/i18n/ms/README.md
index 02a1921aa6..8a8ef46feb 100644
--- a/docs/i18n/ms/README.md
+++ b/docs/i18n/ms/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/ms/docs/USER_GUIDE.md b/docs/i18n/ms/docs/USER_GUIDE.md
index 47f3894949..41cb8f6c64 100644
--- a/docs/i18n/ms/docs/USER_GUIDE.md
+++ b/docs/i18n/ms/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Panduan lengkap untuk mengkonfigurasi penyedia, mencipta gabungan, menyepadukan alatan CLI dan menggunakan OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Sekilas Pandang Harga](#-harga-sepintas lalu)
-- [Kes Penggunaan](# kes penggunaan)
-- [Persediaan Penyedia](#-persediaan-penyedia)
-- [Penyatuan CLI](penyepaduan #-cli)
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
- [Deployment](#-deployment)
-- [Model Tersedia](#-model-tersedia)
-- [Ciri Terperinci](#-ciri-termaju)---
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 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** | DeepSeek | Bayar setiap penggunaan | Tiada | Penaakulan murah |
-| | Groq | Bayar setiap penggunaan | Tiada | Inferens sangat pantas |
-| | xAI (Grok) | Bayar setiap penggunaan | Tiada | Grok 4 penaakulan |
-| | Mistral | Bayar setiap penggunaan | Tiada | Model yang dihoskan EU |
-| | Kebingungan | Bayar setiap penggunaan | Tiada | Carian-ditambah |
-| | Bersama AI | Bayar setiap penggunaan | Tiada | Model sumber terbuka |
-| | Bunga Api AI | Bayar setiap penggunaan | Tiada | Imej FLUX Pantas |
-| | Serebral | Bayar setiap penggunaan | Tiada | Kelajuan skala wafer |
-| | Cohere | Bayar setiap penggunaan | Tiada | Perintah R+ RAG |
-| | NVIDIA NIM | Bayar setiap penggunaan | Tiada | Model perusahaan |
-| **💰 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** | Qoder | $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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Petua Pro:**Mulakan dengan Gemini CLI (180K percuma/bulan) + Qoder (percuma tanpa had) kombo = $0 kos!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Masalah:**Kuota tamat tempoh tidak digunakan, had kadar semasa pengekodan berat```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Masalah:**Tidak mampu membayar langganan, memerlukan pengekodan AI yang boleh dipercayai```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Masalah:**Tarikh akhir, tidak mampu membayar masa henti```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Masalah:**Memerlukan pembantu AI dalam apl pemesejan, percuma sepenuhnya```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**Petua Pro:**Gunakan Opus untuk tugas yang rumit, Sonnet untuk kelajuan. OmniRoute menjejaki kuota setiap model!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Nilai Terbaik:**Peringkat percuma yang besar! Gunakan ini sebelum peringkat berbayar.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### 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: `kunci-anda`
+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` —**Petua Pro:**Pelan Pengekodan menawarkan kuota 3× pada kos 1/7! Tetapkan semula setiap hari 10:00 AM.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Daftar: [MiniMax](https://www.minimax.io/)
-2. Dapatkan kunci API → Papan Pemuka → Tambah Kunci API
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Gunakan:**`minimax/MiniMax-M2.1` —**Petua Pro:**Pilihan termurah untuk konteks panjang (token 1M)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Langgan: [Moonshot AI](https://platform.moonshot.ai/)
-2. Dapatkan kunci API → Papan Pemuka → Tambah Kunci API
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Gunakan:**`kimi/kimi-terbaru` —**Petua Pro:**Tetap $9/bulan untuk 10 juta token = $0.90/1J kos efektif!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Edit `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Edit `~/.claude/config.json`:```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Edit `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Atau gunakan Papan Pemuka:**CLI Tools → OpenClaw → Auto-config### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI secara automatik memuatkan `.env` daripada `~/.omniroute/.env` atau `./.env`.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-Untuk pelayan dengan RAM terhad, gunakan pilihan had memori:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Cipta `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,12 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-Untuk mod bersepadu hos dengan perduaan CLI, lihat bahagian Docker dalam dokumen utama.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Pengguna Linux yang tidak sah boleh membungkus dan memasang OmniRoute secara asli menggunakan rangka kerja kompilasi silang `xbps-src`. Ini mengautomasikan binaan kendiri Node.js bersama-sama dengan pengikatan asli `better-sqlite3` yang diperlukan.
+### Void Linux (xbps-src)
-
-Lihat templat xbps-src```bash
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -408,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -475,60 +516,63 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Pembolehubah | Lalai | Penerangan |
-| ---------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
-| `JWT_RAHSIA` | `omniroute-default-secret-change-me` | Rahsia menandatangani JWT (**perubahan dalam pengeluaran**) |
-| `KATA_laluan_AWAL` | `123456` | Kata laluan log masuk pertama |
-| `DATA_DIR` | `~/.omniroute` | Direktori data (db, penggunaan, log) |
-| `PORT` | lalai rangka kerja | Port perkhidmatan (`20128` dalam contoh) |
-| `HOSTNAME` | lalai rangka kerja | Ikat hos (Docker lalai kepada `0.0.0.0`) |
-| `NODE_ENV` | lalai masa jalan | Tetapkan `pengeluaran` untuk digunakan |
-| `URL_BASE` | `http://localhost:20128` | URL asas dalaman sebelah pelayan |
-| `CLOUD_URL` | `https://omniroute.dev` | URL asas titik akhir penyegerakan awan |
-| `RAHSIA_KUNCI_API` | `endpoint-proxy-api-key-secret` | Rahsia HMAC untuk kunci API yang dijana |
-| `PERLUKAN_KUNCI_API` | `palsu` | Kuatkuasakan kunci API Pembawa pada `/v1/*` |
-| `BENARKAN_KUNCI_API_DEDAH` | `palsu` | Benarkan Pengurus Api menyalin kunci API penuh atas permintaan |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Irama penyegaran sisi pelayan untuk data Had Penyedia yang dicache; Butang muat semula UI masih mencetuskan penyegerakan manual |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `palsu` | Lumpuhkan syot kilat SQLite automatik sebelum menulis/import/pulihkan; sandaran manual masih berfungsi |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `palsu` | Paksa kuki pengesahan `Secure` (di belakang proksi terbalik HTTPS) |
-| `CLOUDFLARED_BIN` | tidak ditetapkan | Gunakan binari `cloudflared` sedia ada dan bukannya muat turun terurus |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Pengangkutan untuk Terowong Pantas terurus (`http2`, `quic` atau `auto`) |
-| `OMNIROUTE_MEMORY_MB` | `512` | Had timbunan Node.js dalam MB |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | Kemasukan cache gesaan maksimum |
-| `SEMANTIK_CACHE_MAX_SIZE` | `100` | Entri cache semantik maksimum |Untuk rujukan pembolehubah persekitaran penuh, lihat [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Lihat semua model yang tersedia
+
+View all available models
-**Kod Claude (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— PERCUMA: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— $0.6/1J: `glm/glm-4.7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— $0.2/1J: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`jika/`)**— PERCUMA: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— PERCUMA: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— PERCUMA: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
@@ -538,17 +582,19 @@ vlicense LICENSE
**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Kekeliruan (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**Ai Bunga Api (`bunga api/`)**: `bunga api/akaun/bunga api/model/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**Serebral (`cerebras/`)**: `cerebras/llama-3.3-70b`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -556,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Tambahkan sebarang ID model pada mana-mana pembekal tanpa menunggu kemas kini apl:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -564,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Atau gunakan Papan Pemuka:**Pembekal → [Penyedia] → Model Tersuai**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Nota:
+Notes:
-- Pembekal OpenRouter dan OpenAI/Anthropic-compatible diuruskan daripada**Model Tersedia**sahaja. Tambah, import dan autosegerakkan secara manual semua mendarat dalam senarai model tersedia yang sama, jadi tiada bahagian Model Tersuai yang berasingan untuk pembekal tersebut.
-- Bahagian**Model Tersuai**bertujuan untuk pembekal yang tidak mendedahkan import model tersedia terurus.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Halakan permintaan terus kepada pembekal tertentu dengan pengesahan model:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Awalan pembekal ditambah secara automatik jika tiada. Model yang tidak sepadan mengembalikan `400`.### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -594,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Keutamaan:**Khusus kunci → Khusus kombo → Khusus pembekal → Global → Persekitaran.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Mengembalikan model yang dikumpulkan mengikut pembekal dengan jenis (`sembang`, `benam`, `imej`).### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Penyegerakan penyedia, gabungan dan tetapan merentas peranti
-- Penyegerakan latar belakang automatik dengan tamat masa + cepat gagal
-- Lebih suka bahagian pelayan `BASE_URL`/`CLOUD_URL` dalam pengeluaran### Cloudflare Quick Tunnel
+### Cloud Sync
-- Tersedia dalam**Papan Pemuka → Titik Tamat**untuk Docker dan penempatan dihoskan sendiri yang lain
-- Mencipta URL sementara `https://*.trycloudflare.com` yang memajukan ke titik akhir `/v1` semasa anda yang serasi dengan OpenAI
-- Mula-mula dayakan pemasangan `cloudflared` hanya apabila diperlukan; kemudian dimulakan semula menggunakan semula binari terurus yang sama
-- Terowong Pantas tidak dipulihkan secara automatik selepas OmniRoute atau kontena dimulakan semula; dayakan semula daripada papan pemuka apabila diperlukan
-- URL terowong bersifat sementara dan berubah setiap kali anda berhenti/memulakan terowong
-- Terowong Pantas Terurus lalai kepada pengangkutan HTTP/2 untuk mengelakkan amaran penimbal UDP QUIC yang bising dalam bekas yang dikekang
-- Tetapkan `CLOUDFLARED_PROTOCOL=quic` atau `auto` jika anda ingin mengatasi pilihan pengangkutan terurus
-- Tetapkan `CLOUDFLARED_BIN` jika anda lebih suka menggunakan binari `cloudflared` yang diprapasang dan bukannya muat turun terurus### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Semantic Cache**— Auto-cache bukan penstriman, suhu=0 respons (pintasan dengan `X-OmniRoute-No-Cache: true`) -**Minta Idempotency**— Menyahduplikasi permintaan dalam masa 5s melalui pengepala `Idempotency-Key` atau `X-Request-Id` -**Penjejakan Kemajuan**— Ikut serta SSE acara `event: progress` melalui pengepala `X-OmniRoute-Progress: true`---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Akses melalui**Papan Pemuka → Penterjemah**. Nyahpepijat dan gambarkan cara OmniRoute menterjemah permintaan API antara pembekal.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Mod | Tujuan |
-| --------------------- | -------------------------------------------------------------------------------------------------- |
-| **Taman Permainan** | Pilih format sumber/sasaran, tampal permintaan dan lihat output yang diterjemahkan serta-merta |
-| **Penguji Sembang** | Hantar mesej sembang langsung melalui proksi dan periksa kitaran permintaan/tindak balas penuh |
-| **Bangku Ujian** | Jalankan ujian kelompok merentasi pelbagai kombinasi format untuk mengesahkan ketepatan terjemahan |
-| **Pemantau Langsung** | Tonton terjemahan masa nyata apabila permintaan mengalir melalui proksi |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Kes penggunaan:**
+**Use cases:**
-- Nyahpepijat sebab gabungan klien/pembekal tertentu gagal
-- Sahkan bahawa teg pemikiran, panggilan alat dan gesaan sistem diterjemahkan dengan betul
-- Bandingkan perbezaan format antara format OpenAI, Claude, Gemini dan API Respons---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Konfigurasikan melalui**Papan Pemuka → Tetapan → Penghalaan**.
+Configure via **Dashboard → Settings → Routing**.
-| Strategi | Penerangan |
-| --------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Isi Dulu** | Menggunakan akaun dalam susunan keutamaan — akaun utama mengendalikan semua permintaan sehingga tidak tersedia |
-| **Robin Bulat** | Kitaran melalui semua akaun dengan had melekat boleh dikonfigurasikan (lalai: 3 panggilan setiap akaun) |
-| **P2C (Kuasa Dua Pilihan)** | Pilih 2 akaun rawak dan laluan ke yang lebih sihat — mengimbangi beban dengan kesedaran kesihatan |
-| **Rawak** | Memilih akaun secara rawak untuk setiap permintaan menggunakan Fisher-Yates shuffle |
-| **Kurang Digunakan** | Laluan ke akaun dengan cap waktu `lastUsedAt` tertua, mengagihkan trafik secara sama rata |
-| **Kos Dioptimumkan** | Laluan ke akaun dengan nilai keutamaan terendah, mengoptimumkan untuk pembekal kos terendah | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Untuk perkaitan sesi luaran (contohnya, ejen Claude Code/Codex di sebalik proksi terbalik), hantarkan:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute juga menerima `x_session_id` dan mengembalikan kunci sesi berkesan dalam `X-OmniRoute-Session-Id`.
+If you use Nginx and send underscore-form headers, enable:
-Jika anda menggunakan Nginx dan menghantar pengepala borang garis bawah, dayakan:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Cipta corak kad bebas untuk memetakan semula nama model:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Kad liar menyokong `*` (sebarang aksara) dan `?` (aksara tunggal).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Tentukan rantaian sandaran global yang digunakan merentas semua permintaan:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Konfigurasikan melalui**Papan Pemuka → Tetapan → Ketahanan**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute melaksanakan daya tahan peringkat penyedia dengan empat komponen:
+OmniRoute implements provider-level resilience with four components:
-1.**Profil Pembekal**— Konfigurasi setiap pembekal untuk:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Ambang kegagalan (berapa banyak kegagalan sebelum dibuka)
-- Tempoh penyejukan
-- Sensitiviti pengesanan had kadar
-- Parameter mundur eksponen
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Had Kadar Boleh Diedit**— Lalai peringkat sistem boleh dikonfigurasikan dalam papan pemuka: -**Permintaan Per Minit (RPM)**— Permintaan maksimum seminit setiap akaun -**Masa Min Antara Permintaan**— Jurang minimum dalam milisaat antara permintaan -**Permintaan Serentak Maks**— Permintaan serentak maksimum bagi setiap akaun
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Klik**Edit**untuk mengubah suai, kemudian**Simpan**atau**Batal**. Nilai kekal melalui API ketahanan.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Pemutus Litar**— Menjejaki kegagalan setiap pembekal dan membuka litar secara automatik apabila ambang dicapai: -**TUTUP**(Sihat) — Permintaan mengalir seperti biasa -**BUKA**— Pembekal disekat buat sementara waktu selepas kegagalan berulang -**HALF_OPEN**— Menguji jika pembekal telah pulih
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Dasar & Pengecam Terkunci**— Menunjukkan status pemutus litar dan pengecam terkunci dengan keupayaan buka kunci paksa.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Pengesanan Auto Had Kadar**— Memantau pengepala `429` dan `Retry-After` untuk mengelak daripada mencapai had kadar penyedia secara proaktif.
-
-**Petua Pro:**Gunakan butang**Reset Semua**untuk mengosongkan semua pemutus litar dan cooldown apabila pembekal pulih daripada gangguan.---
+---
### Database Export / Import
-Uruskan sandaran pangkalan data dalam**Papan Pemuka → Tetapan → Sistem & Storan**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Tindakan | Penerangan |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Eksport Pangkalan Data** | Memuat turun pangkalan data SQLite semasa sebagai fail `.sqlite` |
-| **Eksport Semua (.tar.gz)** | Memuat turun arkib sandaran penuh termasuk: pangkalan data, tetapan, kombo, sambungan pembekal (tiada bukti kelayakan), metadata kunci API |
-| **Import Pangkalan Data** | Muat naik fail `.sqlite` untuk menggantikan pangkalan data semasa. Sandaran praimport dibuat secara automatik melainkan `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Pengesahan Import:**Fail yang diimport disahkan untuk integriti (semakan pragma SQLite), jadual yang diperlukan (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) dan saiz (maks 100MB).
+**Use Cases:**
-**Kes Penggunaan:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Pindahkan OmniRoute antara mesin
-- Buat sandaran luaran untuk pemulihan bencana
-- Kongsi konfigurasi antara ahli pasukan (eksport semua → kongsi arkib)---
+---
### Settings Dashboard
-Halaman tetapan disusun menjadi 6 tab untuk navigasi mudah:
+The settings page is organized into 6 tabs for easy navigation:
-| Tab | Kandungan |
-| -------------- | ------------------------------------------------------------------------------------------------- |
-|**Umum**| Alat storan sistem, tetapan penampilan, kawalan tema dan keterlihatan bar sisi setiap item |
-|**Keselamatan**| Tetapan Log Masuk/Kata Laluan, Kawalan Akses IP, pengesahan API untuk `/model` dan Penyekatan Penyedia |
-|**Penghalaan**| Strategi penghalaan global (6 pilihan), alias model kad bebas, rantai sandaran, lalai kombo |
-|**Ketahanan**| Profil pembekal, had kadar boleh diedit, status pemutus litar, dasar & pengecam terkunci |
-|**AI**| Pemikiran konfigurasi belanjawan, suntikan segera sistem global, statistik cache segera |
-|**Lanjutan**| Konfigurasi proksi global (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Akses melalui**Papan Pemuka → Kos**.
+Access via **Dashboard → Costs**.
-| Tab | Tujuan |
-| ----------- | ------------------------------------------------------------------------------------ |
-|**Anggaran**| Tetapkan had perbelanjaan setiap kunci API dengan belanjawan harian/mingguan/bulanan dan penjejakan masa nyata |
-|**Harga**| Lihat dan edit entri harga model — kos setiap token input/output 1K bagi setiap pembekal |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -765,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Penjejakan Kos:**Setiap permintaan merekodkan penggunaan token dan mengira kos menggunakan jadual harga. Lihat pecahan dalam**Papan Pemuka → Penggunaan**oleh pembekal, model dan kunci API.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute menyokong transkripsi audio melalui titik akhir yang serasi dengan OpenAI:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Pembekal tersedia:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Format audio yang disokong: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.---
+---
### Combo Balancing Strategies
-Konfigurasikan pengimbangan setiap kombo dalam**Papan Pemuka → Kombo → Cipta/Edit → Strategi**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Strategi | Penerangan |
-| ------------------- | ---------------------------------------------------------------------- |
-|**Round-Robin**| Berputar melalui model secara berurutan |
-|**Keutamaan**| Sentiasa mencuba model pertama; jatuh semula hanya atas kesilapan |
-|**Rawak**| Memilih model rawak daripada kombo untuk setiap permintaan |
-|**Ditimbang**| Laluan secara berkadar berdasarkan berat yang ditetapkan bagi setiap model |
-|**Kurang Digunakan**| Laluan ke model dengan permintaan terkini yang paling sedikit (menggunakan metrik kombo) |
-|**Dioptimumkan Kos**| Laluan ke model yang tersedia paling murah (menggunakan jadual harga) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Lalai kombo global boleh ditetapkan dalam**Papan Pemuka → Tetapan → Penghalaan → Lalai Kombo**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Akses melalui**Papan Pemuka → Kesihatan**. Gambaran keseluruhan kesihatan sistem masa nyata dengan 6 kad:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Kad | Apa yang Ditunjukkan |
-| ---------------------- | -------------------------------------------------------- |
-|**Status Sistem**| Masa aktif, versi, penggunaan memori, direktori data |
-|**Kesihatan Pembekal**| Keadaan pemutus litar setiap pembekal (Tertutup/Terbuka/Separuh Terbuka) |
-|**Had Kadar**| Cooldown had kadar aktif bagi setiap akaun dengan baki masa |
-|**Sekat Aktif**| Pembekal disekat buat sementara waktu oleh dasar kunci keluar |
-|**Tandatangan Cache**| Statistik cache penyahduplikasian (kunci aktif, kadar pukulan) |
-|**Telemetri Latensi**| p50/p95/p99 pengagregatan kependaman bagi setiap pembekal |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Petua Pro:**Halaman Kesihatan dimuat semula secara automatik setiap 10 saat. Gunakan kad pemutus litar untuk mengenal pasti penyedia yang mengalami masalah.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute tersedia sebagai aplikasi desktop asli untuk Windows, macOS dan Linux.### Pasang
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Pasang
```bash
# From the electron directory:
@@ -833,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -845,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Output → `elektron/dist-elektron/`### Key Features
+Output → `electron/dist-electron/`
-| Ciri | Penerangan |
-| ------------------------------- | ----------------------------------------------------------------- | ------------------------- |
-| **Kesediaan Pelayan** | Pelayan undian sebelum menunjukkan tetingkap (tiada skrin kosong) |
-| **System Dulang** | Minimumkan kepada dulang, tukar port, keluar dari menu dulang |
-| **Pengurusan Pelabuhan** | Tukar port pelayan daripada dulang (pelayan auto-mula semula) |
-| **Dasar Keselamatan Kandungan** | CSP terhad melalui pengepala sesi |
-| **Instance Tunggal** | Hanya satu contoh apl boleh dijalankan pada satu masa |
-| **Mod Luar Talian** | Pelayan Bundled Next.js berfungsi tanpa internet | ### Environment Variables |
+### Key Features
-| Pembolehubah | Lalai | Penerangan |
-| --------------------- | ------- | ---------------------------------- |
-| `OMNIROUTE_PORT` | `20128` | Port pelayan |
-| `OMNIROUTE_MEMORY_MB` | `512` | Had timbunan Node.js (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Dokumentasi penuh: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/nl/README.md b/docs/i18n/nl/README.md
index 4cd21ad60c..c10234b42b 100644
--- a/docs/i18n/nl/README.md
+++ b/docs/i18n/nl/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/nl/docs/USER_GUIDE.md b/docs/i18n/nl/docs/USER_GUIDE.md
index 19f8d118b9..c75e7c8e54 100644
--- a/docs/i18n/nl/docs/USER_GUIDE.md
+++ b/docs/i18n/nl/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Volledige gids voor het configureren van providers, het maken van combo's, het integreren van CLI-tools en het implementeren van OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Prijzen in één oogopslag](#-prijzen in één oogopslag)
-- [Gebruiksscenario's](#-use-cases)
-- [Providerinstellingen](#-provider-setup)
-- [CLI-integratie](#-cli-integratie)
-- [Implementatie](#-implementatie)
-- [Beschikbare modellen](#-beschikbare-modellen)
-- [Geavanceerde functies](#-advanced-features)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 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** | DeepSeek | Betalen per gebruik | Geen | Goedkoop redeneren |
-| | Groq | Betalen per gebruik | Geen | Ultrasnelle gevolgtrekking |
-| | xAI (Grok) | Betalen per gebruik | Geen | Grok 4 redenering |
-| | Mistral | Betalen per gebruik | Geen | Door de EU gehoste modellen |
-| | Verbijstering | Betalen per gebruik | Geen | Zoek-uitgebreid |
-| | Samen AI | Betalen per gebruik | Geen | Open source-modellen |
-| | Vuurwerk AI | Betalen per gebruik | Geen | Snelle FLUX-afbeeldingen |
-| | Hersenen | Betalen per gebruik | Geen | Snelheid op wafelschaal |
-| | Cohier | Betalen per gebruik | Geen | Commando R+ RAG |
-| | NVIDIA NIM | Betalen per gebruik | Geen | Enterprise-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** | Qoder | $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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Pro-tip:**Begin met Gemini CLI (180K gratis/maand) + Qoder (onbeperkt gratis) combo = $ 0 kosten!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Probleem:**Quotum verloopt ongebruikt, snelheidslimieten tijdens intensief coderen```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Probleem:**Ik kan geen abonnementen betalen, heb betrouwbare AI-codering nodig```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Probleem:**Deadlines, downtime is niet mogelijk```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Probleem:**AI-assistent nodig in berichtenapps, geheel gratis```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**Pro-tip:**Gebruik Opus voor complexe taken, Sonnet voor snelheid. OmniRoute houdt quota bij per model!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Beste waarde:**Enorm gratis niveau! Gebruik dit vóór betaalde niveaus.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### 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: Provider: `glm`, API-sleutel: `uw-sleutel`
+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` —**Pro Tip:**Codeerplan biedt 3× quota tegen 1/7 kosten! Dagelijks resetten om 10:00 uur.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Aanmelden: [MiniMax](https://www.minimax.io/)
-2. API-sleutel ophalen → Dashboard → API-sleutel toevoegen
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Gebruik:**`minimax/MiniMax-M2.1` —**Pro Tip:**Goedkoopste optie voor lange context (1M tokens)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Abonneer je op: [Moonshot AI](https://platform.moonshot.ai/)
-2. API-sleutel ophalen → Dashboard → API-sleutel toevoegen
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Gebruik:**`kimi/kimi-latest` —**Pro-tip:**Vaste $ 9/maand voor 10 miljoen tokens = $ 0,90/1 miljoen effectieve kosten!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Bewerk `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Bewerk `~/.claude/config.json`:```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Bewerk `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Of gebruik Dashboard:**CLI Tools → OpenClaw → Auto-config### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-De CLI laadt automatisch `.env` van `~/.omniroute/.env` of `./.env`.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-Voor servers met beperkt RAM-geheugen gebruikt u de geheugenlimietoptie:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Maak `ecosystem.config.js` aan:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,12 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-Voor de host-geïntegreerde modus met CLI-binaire bestanden raadpleegt u de Docker-sectie in de hoofddocumentatie.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Void Linux-gebruikers kunnen OmniRoute native verpakken en installeren met behulp van het `xbps-src` cross-compilatieframework. Dit automatiseert de standalone build van Node.js samen met de vereiste `better-sqlite3` native bindingen.
+### Void Linux (xbps-src)
+
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
-Xbps-src-sjabloon bekijken
```bash
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -408,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -475,80 +516,85 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Variabel | Standaard | Beschrijving |
-| ------------------------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-standaard-geheim-wijzig-mij` | JWT-ondertekeningsgeheim (**productiewijziging**) |
-| `INITIAL_PASSWORD` | `123456` | Wachtwoord voor eerste aanmelding |
-| `DATA_DIR` | `~/.omniroute` | Gegevensmap (db, gebruik, logs) |
-| `POORT` | standaard raamwerk | Servicepoort (`20128` in voorbeelden) |
-| `HOSTNAAM` | standaard raamwerk | Bind host (Docker is standaard `0.0.0.0`) |
-| `NODE_ENV` | runtime-standaard | Stel `productie` in voor implementatie |
-| `BASE_URL` | `http://localhost:20128` | Interne basis-URL aan serverzijde |
-| `CLOUD_URL` | `https://omniroute.dev` | Basis-URL van cloudsynchronisatie-eindpunt |
-| `API_KEY_SECRET` | `eindpunt-proxy-api-sleutelgeheim` | HMAC-geheim voor gegenereerde API-sleutels |
-| `REQUIRE_API_KEY` | `vals` | Bearer API-sleutel afdwingen op `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `vals` | Sta Api Manager toe om op aanvraag volledige API-sleutels te kopiëren |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Verversingsfrequentie aan de serverzijde voor in de cache opgeslagen Provider Limits-gegevens; Knoppen voor het vernieuwen van de gebruikersinterface activeren nog steeds handmatige synchronisatie |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `vals` | Schakel automatische SQLite-snapshots uit vóór schrijven/importeren/herstellen; handmatige back-ups werken nog steeds |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `vals` | Forceer `Secure` auth-cookie (achter HTTPS reverse proxy) |
-| `CLOUDFLARED_BIN` | uitgeschakeld | Gebruik een bestaand `cloudflared` binair bestand in plaats van een beheerde download |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Transport voor beheerde Quick Tunnels (`http2`, `quic` of `auto`) |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js-heaplimiet in MB |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | Max. promptcache-items |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max. semantische cache-items |Voor de volledige referentie van de omgevingsvariabelen, zie [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-Bekijk alle beschikbare modellen
+View all available models
-**Claude-code (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— GRATIS: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**GitHub Copiloot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— $0,6/1 miljoen: `glm/glm-4,7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— $0,2/1M: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— GRATIS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— GRATIS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— GRATIS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
-**Groq (`groq/`)**: `groq/llama-3.3-70b-veelzijdig`, `groq/llama-4-maverick-17b-128e-instruct`
+**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
-**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-snel redeneren`, `xai/grok-code-mini`
+**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
-**Mistral (`mistral/`)**: `mistral/mistral-groot-2501`, `mistral/codestral-2501`
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Verbijstering (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**Samen AI (`samen/`)**: `samen/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**Vuurwerk AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -556,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Voeg elke model-ID toe aan elke provider zonder te wachten op een app-update:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -564,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Of gebruik Dashboard:**Aanbieders → [Aanbieder] → Aangepaste modellen**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Opmerkingen:
+Notes:
-- OpenRouter en OpenAI/Anthropic-compatibele providers worden uitsluitend beheerd vanuit**Beschikbare modellen**. Handmatig toevoegen, importeren en automatisch synchroniseren komen allemaal in dezelfde lijst met beschikbare modellen terecht, dus er is geen aparte sectie Aangepaste modellen voor die providers.
-- De sectie**Aangepaste modellen**is bedoeld voor providers die geen beheerde import van beschikbare modellen beschikbaar stellen.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Routeer verzoeken rechtstreeks naar een specifieke provider met modelvalidatie:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Het providervoorvoegsel wordt automatisch toegevoegd als het ontbreekt. Niet-overeenkomende modellen retourneren '400'.### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -594,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Voorrang:**Sleutelspecifiek → Combospecifiek → Providerspecifiek → Globaal → Omgeving.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Retourneert modellen gegroepeerd op provider met typen (`chat`, `embedding`, `image`).### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Synchroniseer providers, combo's en instellingen op verschillende apparaten
-- Automatische achtergrondsynchronisatie met time-out + fail-fast
-- Geef de voorkeur aan `BASE_URL`/`CLOUD_URL` aan de serverzijde in productie### Cloudflare Quick Tunnel
+### Cloud Sync
-- Beschikbaar in**Dashboard → Eindpunten**voor Docker en andere zelf-gehoste implementaties
-- Creëert een tijdelijke `https://*.trycloudflare.com` URL die doorstuurt naar uw huidige OpenAI-compatibele `/v1` eindpunt
-- Schakel eerst de installatie 'cloudflared' alleen in als dat nodig is; herstart later en hergebruikt hetzelfde beheerde binaire bestand
-- Quick Tunnels worden niet automatisch hersteld na een herstart van OmniRoute of een container; schakel ze indien nodig opnieuw in vanaf het dashboard
-- Tunnel-URL's zijn kortstondig en veranderen elke keer dat u de tunnel stopt/start
-- Beheerde Quick Tunnels gebruiken standaard HTTP/2-transport om luidruchtige QUIC UDP-bufferwaarschuwingen in beperkte containers te voorkomen
-- Stel `CLOUDFLARED_PROTOCOL=quic` of `auto` in als u de beheerde transportkeuze wilt overschrijven
-- Stel `CLOUDFLARED_BIN` in als u liever een vooraf geïnstalleerd `cloudflared` binair bestand gebruikt in plaats van de beheerde download### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Semantische cache**— Auto-caches van niet-streaming, temperatuur=0 reacties (omzeilen met `X-OmniRoute-No-Cache: true`) -**Request Idempotency**— Ontdubbelt verzoeken binnen 5 seconden via de header 'Idempotency-Key' of 'X-Request-Id' -**Voortgang bijhouden**— Meld u aan voor SSE `event: progress`-gebeurtenissen via `X-OmniRoute-Progress: true` header---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Toegang via**Dashboard → Vertaler**. Debug en visualiseer hoe OmniRoute API-verzoeken tussen providers vertaalt.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Modus | Doel |
-| --------------- | ----------------------------------------------------------------------------------------------------- |
-| **Speeltuin** | Selecteer bron-/doelformaten, plak een verzoek en bekijk direct de vertaalde uitvoer |
-| **Chattester** | Stuur livechatberichten via de proxy en inspecteer de volledige aanvraag/antwoordcyclus |
-| **Proefbank** | Voer batchtests uit voor meerdere formaatcombinaties om de juistheid van de vertalingen te verifiëren |
-| **Livemonitor** | Bekijk realtime vertalingen terwijl verzoeken via de proxy |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Gebruiksscenario's:**
+**Use cases:**
-- Debug waarom een specifieke client/provider-combinatie mislukt
-- Controleer of denktags, tooloproepen en systeemprompts correct worden vertaald
-- Vergelijk formaatverschillen tussen OpenAI-, Claude-, Gemini- en Responses API-formaten---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Configureer via**Dashboard → Instellingen → Routing**.
+Configure via **Dashboard → Settings → Routing**.
-| Strategie | Beschrijving |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Eerst invullen** | Gebruikt accounts in volgorde van prioriteit: het primaire account handelt alle verzoeken af totdat deze niet meer beschikbaar zijn |
-| **Ronde Robin** | Bladert door alle accounts met een configureerbare sticky limiet (standaard: 3 oproepen per account) |
-| **P2C (Kracht van twee keuzes)** | Kiest 2 willekeurige accounts en routes naar de gezondere – balanceert de belasting met bewustzijn van de gezondheid |
-| **Willekeurig** | Selecteert willekeurig een account voor elk verzoek met behulp van Fisher-Yates shuffle |
-| **Minst gebruikt** | Routes naar het account met het oudste `lastUsedAt`-tijdstempel, waarbij het verkeer gelijkmatig wordt verdeeld |
-| **Kostengeoptimaliseerd** | Routes naar het account met de laagste prioriteitswaarde, geoptimaliseerd voor providers met de laagste kosten | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Voor externe sessie-affiniteit (bijvoorbeeld Claude Code/Codex-agenten achter omgekeerde proxy's), verzendt u:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute accepteert ook `x_session_id` en retourneert de effectieve sessiesleutel in `X-OmniRoute-Session-Id`.
+If you use Nginx and send underscore-form headers, enable:
-Als u Nginx gebruikt en headers in onderstrepingsformulier verzendt, schakelt u het volgende in:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Maak jokertekenpatronen om modelnamen opnieuw toe te wijzen:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Jokertekens ondersteunen `*` (willekeurige tekens) en `?` (enkel teken).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Definieer globale fallback-ketens die op alle verzoeken van toepassing zijn:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Configureer via**Dashboard → Instellingen → Veerkracht**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute implementeert veerkracht op providerniveau met vier componenten:
+OmniRoute implements provider-level resilience with four components:
-1.**Providerprofielen**— Configuratie per provider voor:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Foutdrempel (hoeveel fouten vóór opening)
-- Cooldown-duur
-- Snelheidslimietdetectiegevoeligheid
-- Exponentiële uitstelparameters
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Bewerkbare tarieflimieten**— Standaardinstellingen op systeemniveau configureerbaar in het dashboard: -**Verzoeken per minuut (RPM)**— Maximaal aantal verzoeken per minuut per account -**Min. tijd tussen verzoeken**— Minimale pauze in milliseconden tussen verzoeken -**Max. gelijktijdige verzoeken**— Maximaal gelijktijdige verzoeken per account
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Klik op**Bewerken**om te wijzigen en vervolgens op**Opslaan**of**Annuleren**. Waarden blijven behouden via de veerkracht-API.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Circuit Breaker**— Volgt storingen per provider en opent automatisch het circuit wanneer een drempel wordt bereikt: -**GESLOTEN**(Gezond) — Verzoeken stromen normaal door -**OPEN**— Provider is tijdelijk geblokkeerd na herhaalde fouten -**HALF_OPEN**— Testen of de provider is hersteld
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Beleid en vergrendelde identificatiegegevens**— Toont de status van de stroomonderbreker en vergrendelde identificatiegegevens met de mogelijkheid tot geforceerd ontgrendelen.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Automatische detectie van snelheidslimiet**— Controleert de headers '429' en 'Retry-After' om proactief te voorkomen dat de tarieflimieten van de provider worden overschreden.
-
-**Pro-tip:**Gebruik de knop**Alles resetten**om alle stroomonderbrekers en cooldowns te wissen wanneer een provider herstelt van een storing.---
+---
### Database Export / Import
-Beheer databaseback-ups in**Dashboard → Instellingen → Systeem en opslag**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Actie | Beschrijving |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Database exporteren** | Downloadt de huidige SQLite-database als een `.sqlite`-bestand |
-| **Alles exporteren (.tar.gz)** | Downloadt een volledig back-uparchief inclusief: database, instellingen, combo's, providerverbindingen (geen inloggegevens), API-sleutelmetagegevens |
-| **Database importeren** | Upload een `.sqlite`-bestand om de huidige database te vervangen. Er wordt automatisch een pre-importback-up gemaakt tenzij `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Importvalidatie:**Het geïmporteerde bestand wordt gevalideerd op integriteit (SQLite pragma check), vereiste tabellen (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) en grootte (max. 100 MB).
+**Use Cases:**
-**Gebruiksscenario's:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Migreer OmniRoute tussen machines
-- Maak externe back-ups voor noodherstel
-- Deel configuraties tussen teamleden (alles exporteren → archief delen)---
+---
### Settings Dashboard
-De instellingenpagina is onderverdeeld in 6 tabbladen voor eenvoudige navigatie:
+The settings page is organized into 6 tabs for easy navigation:
-| Tabblad | Inhoud |
-| -------------- | ----------------------------------------------------------------------------------- |
-|**Algemeen**| Hulpmiddelen voor systeemopslag, weergave-instellingen, themabediening en zichtbaarheid in de zijbalk per item |
-|**Beveiliging**| Login-/wachtwoordinstellingen, IP-toegangscontrole, API-authenticatie voor `/modellen` en providerblokkering |
-|**Routing**| Globale routeringsstrategie (6 opties), wildcard-modelaliassen, fallback-ketens, combo-standaardwaarden |
-|**Veerkracht**| Providerprofielen, bewerkbare tarieflimieten, status van stroomonderbrekers, beleid en vergrendelde identificatiegegevens |
-|**AI**| Denken aan budgetconfiguratie, globale systeempromptinjectie, prompt cachestatistieken |
-|**Geavanceerd**| Globale proxyconfiguratie (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Toegang via**Dashboard → Kosten**.
+Access via **Dashboard → Costs**.
-| Tabblad | Doel |
-| ----------- | ------------------------------------------------------------------------------ |
-|**Begroting**| Stel bestedingslimieten per API-sleutel in met dagelijkse/wekelijkse/maandelijkse budgetten en realtime tracking |
-|**Prijzen**| Bekijk en bewerk modelprijsgegevens — kosten per 1K input/output-tokens per provider |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -765,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Kosten bijhouden:**Bij elk verzoek wordt het tokengebruik geregistreerd en worden de kosten berekend met behulp van de prijstabel. Bekijk de uitsplitsingen in**Dashboard → Gebruik**per provider, model en API-sleutel.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute ondersteunt audiotranscriptie via het OpenAI-compatibele eindpunt:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Beschikbare providers:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Ondersteunde audioformaten: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.---
+---
### Combo Balancing Strategies
-Configureer de balans per combo in**Dashboard → Combo's → Maken/bewerken → Strategie**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Strategie | Beschrijving |
-| ------------------ | ----------------------------------------------------------------- |
-|**Round-Robin**| Roteert opeenvolgend door modellen |
-|**Prioriteit**| Probeert altijd het eerste model; valt alleen terug op fouten |
-|**Willekeurig**| Kiest voor elk verzoek een willekeurig model uit de combo |
-|**Gewogen**| Routes proportioneel op basis van toegekende gewichten per model |
-|**Minst gebruikt**| Routes naar het model met de minste recente verzoeken (gebruikt combo-statistieken) |
-|**Kostengeoptimaliseerd**| Routes naar het goedkoopste beschikbare model (gebruikt prijstabel) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Algemene combo-standaardinstellingen kunnen worden ingesteld in**Dashboard → Instellingen → Routing → Combo-standaardwaarden**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Toegang via**Dashboard → Gezondheid**. Realtime overzicht van de systeemstatus met 6 kaarten:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Kaart | Wat het laat zien |
-| -------------------- | ---------------------------------------------------- |
-|**Systeemstatus**| Uptime, versie, geheugengebruik, datadirectory |
-|**Provider Gezondheid**| Status stroomonderbreker per provider (gesloten/open/halfopen) |
-|**Tarieflimieten**| Actieve afkoelperiodes voor tarieflimieten per account met resterende tijd |
-|**Actieve vergrendelingen**| Providers tijdelijk geblokkeerd door het lockoutbeleid |
-|**Handtekeningcache**| Deduplicatiecachestatistieken (actieve sleutels, trefpercentage) |
-|**Latentietelemetrie**| p50/p95/p99-latentieaggregatie per provider |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Pro-tip:**De Gezondheidspagina wordt elke 10 seconden automatisch vernieuwd. Gebruik de stroomonderbrekerkaart om te identificeren welke providers problemen ondervinden.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute is beschikbaar als native desktop-applicatie voor Windows, macOS en Linux.### Installeren
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Installeren
```bash
# From the electron directory:
@@ -833,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -845,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Uitvoer → `elektron/dist-elektron/`### Key Features
+Output → `electron/dist-electron/`
-| Kenmerk | Beschrijving |
-| ----------------------------- | ------------------------------------------------------------------------ | ------------------------- |
-| **Servergereedheid** | Pollt de server voordat het venster wordt weergegeven (geen leeg scherm) |
-| **Systeemvak** | Minimaliseren naar lade, poort wijzigen, afsluiten vanuit lademenu |
-| **Havenbeheer** | Serverpoort vanuit lade wijzigen (server automatisch opnieuw opstarten) |
-| **Inhoudsbeveiligingsbeleid** | Beperkende CSP via sessieheaders |
-| **Enkel exemplaar** | Er kan slechts één app-exemplaar tegelijk worden uitgevoerd |
-| **Offlinemodus** | Gebundelde Next.js-server werkt zonder internet | ### Environment Variables |
+### Key Features
-| Variabel | Standaard | Beschrijving |
-| --------------------- | --------- | -------------------------------- |
-| `OMNIROUTE_PORT` | `20128` | Serverpoort |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js-heaplimiet (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Volledige documentatie: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/no/README.md b/docs/i18n/no/README.md
index ba60001100..9c3221be57 100644
--- a/docs/i18n/no/README.md
+++ b/docs/i18n/no/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/no/docs/USER_GUIDE.md b/docs/i18n/no/docs/USER_GUIDE.md
index 2ed7cc8b14..96e80e9103 100644
--- a/docs/i18n/no/docs/USER_GUIDE.md
+++ b/docs/i18n/no/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Komplett veiledning for å konfigurere leverandører, lage kombinasjoner, integrere CLI-verktøy og distribuere OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Prising på et øyeblikk](#-pricing-at-a-glance)
+- [Pricing at a Glance](#-pricing-at-a-glance)
- [Use Cases](#-use-cases)
- – [Provider Setup](#-provider-setup)
-- [CLI-integrasjon](#-cli-integrasjon)
-- [Deployment](#-distribusjon)
-- [Tilgjengelige modeller](#-tilgjengelige-modeller)
-- [Avanserte funksjoner](#-avanserte-funksjoner)---
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 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** | DeepSeek | Betal per bruk | Ingen | Billig resonnement |
-| | Groq | Betal per bruk | Ingen | Ultrarask slutning |
-| | xAI (Grok) | Betal per bruk | Ingen | Grok 4 resonnement |
-| | Mistral | Betal per bruk | Ingen | EU-vertsbaserte modeller |
-| | Forvirring | Betal per bruk | Ingen | Søkeutvidet |
-| | Sammen AI | Betal per bruk | Ingen | Åpen kildekode-modeller |
-| | Fyrverkeri AI | Betal per bruk | Ingen | Rask FLUX bilder |
-| | Cerebras | Betal per bruk | Ingen | Wafer-skala hastighet |
-| | Sammenheng | Betal per bruk | Ingen | Kommando R+ RAG |
-| | NVIDIA NIM | Betal per bruk | Ingen | Bedriftsmodeller |
-| **💰 BILLIG** | GLM-4.7 | $0,6/1M | Daglig 10:00 | Budsjett backup |
-| | MiniMax M2.1 | $0,2/1 million | 5-timers rullende | Billigste alternativ |
-| | Kimi K2 | $9/md leilighet | 10 millioner tokens/mnd | Forutsigbar kostnad |
-| **🆓 GRATIS** | Qoder | $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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Pro-tips:**Start med Gemini CLI (180K gratis/måned) + Qoder (ubegrenset gratis) kombinasjon = $0 kostnad!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Problem:**Kvoten utløper ubrukt, satsgrenser under tung koding```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Problem:**Har ikke råd til abonnementer, trenger pålitelig AI-koding```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Problem:**Tidsfrister, har ikke råd til nedetid```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Problem:**Trenger AI-assistent i meldingsapper, helt gratis```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**Profftips:**Bruk Opus for komplekse oppgaver, Sonnet for hastighet. OmniRoute sporer kvote per modell!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Mest verdi:**Enormt gratis nivå! Bruk dette før betalte nivåer.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### 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: `din-nøkkel`
+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` —**Profftips:**Kodeplan tilbyr 3× kvote til 1/7 kostnad! Tilbakestill daglig 10:00.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Registrer deg: [MiniMax](https://www.minimax.io/)
-2. Hent API-nøkkel → Dashboard → Legg til API-nøkkel
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Bruk:**`minimax/MiniMax-M2.1` —**Profftips:**Billigste alternativ for lang kontekst (1M tokens)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Abonner: [Moonshot AI](https://platform.moonshot.ai/)
-2. Hent API-nøkkel → Dashboard → Legg til API-nøkkel
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Bruk:**`kimi/kimi-latest` —**Profftips:**Fast $9/måned for 10M tokens = $0,90/1M effektiv kostnad!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Rediger `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Rediger `~/.claude/config.json`:```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Rediger `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Eller bruk Dashboard:**CLI Tools → OpenClaw → Auto-config### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI laster automatisk `.env` fra `~/.omniroute/.env` eller `./.env`.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-For servere med begrenset RAM, bruk alternativet for minnegrense:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Opprett `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,12 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-For vertsintegrert modus med CLI-binærfiler, se Docker-delen i hoveddokumentene.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Void Linux-brukere kan pakke og installere OmniRoute naturlig ved å bruke "xbps-src" krysskompileringsrammeverket. Dette automatiserer Node.js frittstående build sammen med de nødvendige "better-sqlite3" native bindingene.
+### Void Linux (xbps-src)
-
-Se xbps-src-mal```bash
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -408,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -475,60 +516,63 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Variabel | Standard | Beskrivelse |
-| ----------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signeringshemmelighet (**endring i produksjon**) |
-| `INITIAL_PASSWORD` | `123456` | Første påloggingspassord |
-| `DATA_DIR` | `~/.omniroute` | Datakatalog (db, bruk, logger) |
-| `PORT` | standard rammeverk | Tjenesteport («20128» i eksempler) |
-| `VERTSNAVN` | standard rammeverk | Bind vert (Docker er standard til `0.0.0.0`) |
-| `NODE_ENV` | kjøretidsstandard | Angi "produksjon" for distribusjon |
-| `BASE_URL` | `http://localhost:20128` | Intern basis-URL på tjenersiden |
-| `CLOUD_URL` | `https://omniroute.dev` | Nettadresse for endepunkt for nettskysynkronisering |
-| `API_KEY_SECRET` | `endepunkt-proxy-api-nøkkel-hemmelig` | HMAC-hemmelighet for genererte API-nøkler |
-| `REQUIRE_API_KEY` | `false` | Håndhev Bearer API-nøkkel på `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `false` | Tillat at Api Manager kopierer fullstendige API-nøkler på forespørsel |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Oppdateringskadens på tjenersiden for bufrede Provider Limits-data; UI-oppdateringsknapper utløser fortsatt manuell synkronisering |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Deaktiver automatiske SQLite-øyeblikksbilder før skriving/importering/gjenoppretting; manuelle sikkerhetskopier fungerer fortsatt |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `false` | Tving `Sikker` auth-informasjonskapsel (bak HTTPS omvendt proxy) |
-| `CLOUDFLARED_BIN` | deaktivert | Bruk en eksisterende `cloudflared`-binær i stedet for administrert nedlasting |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for administrerte hurtigtunneler (`http2`, `quic` eller `auto`) |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js hauggrense i MB |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | Maks. hurtigbufferoppføringer |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Maks. semantisk cache-oppføringer |For hele miljøvariabelreferansen, se [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Se alle tilgjengelige modeller
+
+View all available models
-**Claude Code (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**– Pluss/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**– GRATIS: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**– $0,6/1M: `glm/glm-4,7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**– $0,2/1M: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**– GRATIS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**– GRATIS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**– GRATIS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
@@ -538,7 +582,7 @@ vlicense LICENSE
**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Forvirring (`pplx/`)**: `pplx/sonar-pro`, `pplx/ekkolodd`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
@@ -548,7 +592,9 @@ vlicense LICENSE
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -556,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Legg til hvilken som helst modell-ID til en hvilken som helst leverandør uten å vente på en appoppdatering:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -564,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Eller bruk Dashboard:**Leverandører → [Leverandør] → Egendefinerte modeller**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Merknader:
+Notes:
-- OpenRouter og OpenAI/Anthropic-kompatible leverandører administreres kun fra**Tilgjengelige modeller**. Manuell tillegging, import og automatisk synkronisering havner i samme liste over tilgjengelige modeller, så det er ingen egen seksjon for tilpassede modeller for disse leverandørene.
- –**Egendefinerte modeller**-delen er beregnet på leverandører som ikke eksponerer administrert import av tilgjengelige modeller.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Rute forespørsler direkte til en spesifikk leverandør med modellvalidering:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Leverandørprefikset blir automatisk lagt til hvis det mangler. Umatchede modeller returnerer `400`.### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -594,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Forrang:**Nøkkelspesifikk → Kombinasjonsspesifikk → Leverandørspesifikk → Global → Miljø.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Returnerer modeller gruppert etter leverandør med typer (`chat`, `embedding`, `image`).### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Synkroniser leverandører, kombinasjoner og innstillinger på tvers av enheter
-- Automatisk bakgrunnssynkronisering med timeout + feil-rask
-- Foretrekk "BASE_URL"/"CLOUD_URL" på serversiden i produksjon### Cloudflare Quick Tunnel
+### Cloud Sync
-- Tilgjengelig i**Dashboard → Endpoints**for Docker og andre selvvertsbaserte distribusjoner
-- Oppretter en midlertidig `https://*.trycloudflare.com` URL som videresender til ditt nåværende OpenAI-kompatible `/v1` endepunkt
-- Aktiver først installasjoner `cloudflared` bare når det er nødvendig; senere omstarter gjenbruk den samme administrerte binære filen
-- Hurtigtunneler blir ikke automatisk gjenopprettet etter omstart av OmniRoute eller container; aktiver dem på nytt fra dashbordet ved behov
-- Tunnel-URLer er flyktige og endres hver gang du stopper/starter tunnelen
-- Managed Quick Tunnels er som standard HTTP/2-transport for å unngå støyende QUIC UDP-buffervarsler i begrensede containere
-- Angi `CLOUDFLARED_PROTOCOL=quic` eller `auto` hvis du vil overstyre det administrerte transportvalget
-- Angi `CLOUDFLARED_BIN` hvis du foretrekker å bruke en forhåndsinstallert `cloudflared`-binær i stedet for den administrerte nedlastingen### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Semantisk hurtigbuffer**— Automatisk hurtigbufring som ikke er streaming, temperatur=0 svar (omgå med `X-OmniRoute-No-Cache: true`) -**Request Idempotency**— Dedupliserer forespørsler innen 5 s via «Idempotency-Key» eller «X-Request-Id»-overskrift -**Fremdriftssporing**— Meld deg på SSE `event: progress`-hendelser via `X-OmniRoute-Progress: true` header---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Tilgang via**Dashboard → Oversetter**. Feilsøk og visualiser hvordan OmniRoute oversetter API-forespørsler mellom leverandører.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Modus | Formål |
-| ---------------- | ------------------------------------------------------------------------------------------------ |
-| **Lekeplass** | Velg kilde-/målformater, lim inn en forespørsel og se den oversatte utgangen umiddelbart |
-| **Chattetester** | Send live chat-meldinger gjennom proxyen og inspiser hele forespørsels-/svarsyklusen |
-| **Testbenk** | Kjør batch-tester på tvers av flere formatkombinasjoner for å bekrefte oversettelsens korrekthet |
-| **Live Monitor** | Se sanntidsoversettelser mens forespørsler strømmer gjennom proxyen |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Brukstilfeller:**
+**Use cases:**
-- Feilsøk hvorfor en spesifikk klient/leverandør-kombinasjon mislykkes
-- Bekreft at tankekoder, verktøykall og systemmeldinger oversettes riktig
-- Sammenlign formatforskjeller mellom OpenAI, Claude, Gemini og Responses API-formater---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Konfigurer via**Dashboard → Innstillinger → Ruting**.
+Configure via **Dashboard → Settings → Routing**.
-| Strategi | Beskrivelse |
-| ------------------------------ | -------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Fyll først** | Bruker kontoer i prioritert rekkefølge — primærkonto håndterer alle forespørsler inntil utilgjengelig |
-| **Round Robin** | Bla gjennom alle kontoer med en konfigurerbar klebrig grense (standard: 3 samtaler per konto) |
-| **P2C (Power of Two Choices)** | Velger 2 tilfeldige kontoer og ruter til den sunnere — balanserer belastning med bevissthet om helse |
-| **Tilfeldig** | Velger tilfeldig en konto for hver forespørsel ved hjelp av Fisher-Yates shuffle |
-| **Minst brukt** | Ruter til kontoen med det eldste «lastUsedAt»-tidsstempelet, og fordeler trafikk jevnt |
-| **Kostnadsoptimalisert** | Ruter til kontoen med den laveste prioritetsverdien, optimalisering for de laveste kostnadsleverandørene | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-For ekstern sesjonstilhørighet (for eksempel Claude Code/Codex-agenter bak omvendte proxyer), send:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute godtar også `x_session_id` og returnerer den effektive øktnøkkelen i `X-OmniRoute-Session-Id`.
+If you use Nginx and send underscore-form headers, enable:
-Hvis du bruker Nginx og sender understrek-overskrifter, aktiver:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Lag jokertegnmønstre for å omordne modellnavn:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Jokertegn støtter `*` (alle tegn) og `?` (enkelttegn).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Definer globale reservekjeder som gjelder for alle forespørsler:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Konfigurer via**Dashboard → Innstillinger → Resiliens**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute implementerer motstandskraft på leverandørnivå med fire komponenter:
+OmniRoute implements provider-level resilience with four components:
-1.**Leverandørprofiler**— Konfigurasjon per leverandør for:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Feilterskel (hvor mange feil før åpning)
-- Nedkjølingsvarighet
-- Følsomhet for deteksjon av hastighetsgrense
-- Eksponentielle backoff-parametere
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Redigerbare rategrenser**— Standardinnstillinger på systemnivå som kan konfigureres i dashbordet: -**Forespørsler per minutt (RPM)**— Maksimalt antall forespørsler per minutt per konto -**Min time Between Requests**— Minimumsavstand i millisekunder mellom forespørsler -**Maks samtidige forespørsler**— Maksimalt antall samtidige forespørsler per konto
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Klikk på**Rediger**for å endre, deretter**Lagre**eller**Avbryt**. Verdiene vedvarer via resilience API.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Circuit Breaker**— Sporer feil per leverandør og åpner automatisk kretsen når en terskel er nådd: -**STENGT**(Sunn) — Forespørslene flyter normalt -**ÅPEN**— Leverandøren er midlertidig blokkert etter gjentatte feil -**HALF_OPEN**— Tester om leverandøren har kommet seg
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Retningslinjer og låste identifikatorer**— Viser strømbryterstatus og låste identifikatorer med tvangsopplåsingsfunksjon.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Rate Limit Auto-Detection**— Overvåker «429» og «Retry-After»-overskrifter for å proaktivt unngå å treffe leverandørens takstgrenser.
-
-**Profftips:**Bruk**Tilbakestill alle**-knappen for å fjerne alle strømbrytere og nedkjøling når en leverandør kommer seg etter et strømbrudd.---
+---
### Database Export / Import
-Administrer sikkerhetskopiering av databaser i**Dashboard → Innstillinger → System og lagring**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Handling | Beskrivelse |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Eksporter database** | Laster ned gjeldende SQLite-database som en `.sqlite`-fil |
-| **Eksporter alle (.tar.gz)** | Laster ned et fullstendig sikkerhetskopiarkiv inkludert: database, innstillinger, kombinasjoner, leverandørtilkoblinger (ingen legitimasjon), API-nøkkelmetadata |
-| **Importer database** | Last opp en `.sqlite`-fil for å erstatte gjeldende database. En forhåndsimport-sikkerhetskopi opprettes automatisk med mindre `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Importvalidering:**Den importerte filen er validert for integritet (SQLite pragmasjekk), nødvendige tabeller (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) og størrelse (maks. 100MB).
+**Use Cases:**
-**Brukstilfeller:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Migrer OmniRoute mellom maskiner
-- Lag eksterne sikkerhetskopier for katastrofegjenoppretting
-- Del konfigurasjoner mellom teammedlemmer (eksporter alle → del arkiv)---
+---
### Settings Dashboard
-Innstillingssiden er organisert i 6 faner for enkel navigering:
+The settings page is organized into 6 tabs for easy navigation:
-| Tab | Innhold |
-| -------------- | ------------------------------------------------------------------------------------------------------ |
-|**Generelt**| Systemlagringsverktøy, utseendeinnstillinger, temakontroller og synlighet i sidefeltet per element |
-|**Sikkerhet**| Innstillinger for pålogging/passord, IP-tilgangskontroll, API-autentisering for `/modeller` og leverandørblokkering |
-|**Ruting**| Global rutingstrategi (6 alternativer), jokertegnmodellaliaser, reservekjeder, kombinasjonsstandarder |
-|**Resiliens**| Leverandørprofiler, redigerbare hastighetsgrenser, strømbryterstatus, retningslinjer og låste identifikatorer |
-|**AI**| Tenker budsjettkonfigurasjon, global systempromptinjeksjon, promptbufferstatistikk |
-|**Avansert**| Global proxy-konfigurasjon (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Tilgang via**Dashboard → Kostnader**.
+Access via **Dashboard → Costs**.
-| Tab | Formål |
-| ----------- | ------------------------------------------------------------------------------------------ |
-|**Budsjett**| Angi utgiftsgrenser per API-nøkkel med daglige/ukentlige/månedlige budsjetter og sanntidssporing |
-|**Priser**| Se og rediger modellprisoppføringer — kostnad per 1K input/output tokens per leverandør |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -765,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Kostnadssporing:**Hver forespørsel logger tokenbruk og beregner kostnad ved hjelp av pristabellen. Se oversikter i**Dashboard → Bruk**etter leverandør, modell og API-nøkkel.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute støtter lydtranskripsjon via det OpenAI-kompatible endepunktet:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Tilgjengelige leverandører:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Støttede lydformater: "mp3", "wav", "m4a", "flac", "ogg", "webm".---
+---
### Combo Balancing Strategies
-Konfigurer balansering per kombinasjon i**Dashboard → Kombinasjoner → Opprett/Rediger → Strategi**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Strategi | Beskrivelse |
-| ------------------ | ---------------------------------------------------------------------------------- |
-|**Round-Robin**| Roterer gjennom modellene sekvensielt |
-|**Prioritet**| Prøver alltid den første modellen; faller tilbake kun på feil |
-|**Tilfeldig**| Velger en tilfeldig modell fra kombinasjonen for hver forespørsel |
-|**Vektet**| Ruter proporsjonalt basert på tildelte vekter per modell |
-|**Minst brukt**| Ruter til modellen med færrest nylige forespørsler (bruker kombinasjonsberegninger) |
-|**Kostnadsoptimalisert**| Ruter til den billigste tilgjengelige modellen (bruker pristabell) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Globale kombinasjonsstandarder kan angis i**Dashboard → Innstillinger → Ruting → Combo-standarder**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Tilgang via**Dashboard → Helse**. Sanntids systemhelseoversikt med 6 kort:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Kort | Hva det viser |
-| ---------------------- | ------------------------------------------------------------------ |
-|**Systemstatus**| Oppetid, versjon, minnebruk, datakatalog |
-|**Leverandørhelse**| Per leverandør effektbrytertilstand (lukket/åpen/halvåpen) |
-|**Satsgrenser**| Aktive nedkjølingshastigheter per konto med gjenværende tid |
-|**Aktive Lockouts**| Leverandører midlertidig blokkert av lockout-policyen |
-|**Signaturbuffer**| Dedupliseringsbufferstatistikk (aktive nøkler, trefffrekvens) |
-|**Latens-telemetri**| p50/p95/p99 latensaggregering per leverandør |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Profftips:**Helsesiden oppdateres automatisk hvert 10. sekund. Bruk kretsbryterkortet til å identifisere hvilke leverandører som har problemer.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute er tilgjengelig som en innebygd skrivebordsapplikasjon for Windows, macOS og Linux.### Installer
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Installer
```bash
# From the electron directory:
@@ -833,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -845,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Utgang → `elektron/dist-elektron/`### Key Features
+Output → `electron/dist-electron/`
-| Funksjon | Beskrivelse |
-| ---------------------------------------- | ------------------------------------------------------------------ | ------------------------- |
-| **Serverberedskap** | Avstemningsserver før vindu vises (ingen blank skjerm) |
-| **System Tray** | Minimer til skuff, bytt port, avslutt fra skuffmenyen |
-| **Port Management** | Endre serverport fra skuffen (starter serveren automatisk på nytt) |
-| **Retningslinjer for innholdssikkerhet** | Restriktiv CSP via økthoder |
-| **Enkeltforekomst** | Bare én appforekomst kan kjøres om gangen |
-| **Frakoblet modus** | Medfølgende Next.js-server fungerer uten internett | ### Environment Variables |
+### Key Features
-| Variabel | Standard | Beskrivelse |
-| --------------------- | -------- | --------------------------------- |
-| `OMNIROUTE_PORT` | `20128` | Serverport |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap-grense (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Full dokumentasjon: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/phi/README.md b/docs/i18n/phi/README.md
index 46aee141f1..97828badba 100644
--- a/docs/i18n/phi/README.md
+++ b/docs/i18n/phi/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/phi/docs/USER_GUIDE.md b/docs/i18n/phi/docs/USER_GUIDE.md
index 30a0f5ae11..9c18f0c196 100644
--- a/docs/i18n/phi/docs/USER_GUIDE.md
+++ b/docs/i18n/phi/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Kumpletong gabay para sa pag-configure ng mga provider, paggawa ng mga combo, pagsasama ng mga tool ng CLI, at pag-deploy ng OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Pagpepresyo sa isang Sulyap](#-pricing-sa-isang-sulyap)
+- [Pricing at a Glance](#-pricing-at-a-glance)
- [Use Cases](#-use-cases)
- [Provider Setup](#-provider-setup)
- [CLI Integration](#-cli-integration)
- [Deployment](#-deployment)
- [Available Models](#-available-models)
-- [Mga Advanced na Feature](#-advanced-features)---
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 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** | DeepSeek | Magbayad sa bawat paggamit | Wala | Murang pangangatwiran |
-| | Groq | Magbayad sa bawat paggamit | Wala | Napakabilis na hinuha |
-| | xAI (Grok) | Magbayad sa bawat paggamit | Wala | Grok 4 na pangangatwiran |
-| | Mistral | Magbayad sa bawat paggamit | Wala | Mga modelong naka-host sa EU |
-| | Pagkagulo | Magbayad sa bawat paggamit | Wala | Search-augmented |
-| | Magkasama AI | Magbayad sa bawat paggamit | Wala | Open-source na mga modelo |
-| | Fireworks AI | Magbayad sa bawat paggamit | Wala | Mabilis na FLUX na mga larawan |
-| | Cerebras | Magbayad sa bawat paggamit | Wala | Wafer-scale na bilis |
-| | Cohere | Magbayad sa bawat paggamit | Wala | Command R+ RAG |
-| | NVIDIA NIM | Magbayad sa bawat paggamit | Wala | Mga modelo ng enterprise |
-| **💰 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** | Qoder | $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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Pro Tip:**Magsimula sa Gemini CLI (180K libre/buwan) + Qoder (walang limitasyong libre) combo = $0 na halaga!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Problema:**Nag-e-expire ang quota nang hindi nagamit, mga limitasyon sa rate sa panahon ng mabigat na coding```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Problema:**Hindi kayang bayaran ang mga subscription, kailangan ng maaasahang AI coding```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Problema:**Mga deadline, hindi kayang bayaran ang downtime```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Problema:**Kailangan ng AI assistant sa mga app sa pagmemensahe, ganap na libre```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ 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!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Pinakamahusay na Halaga:**Malaking libreng tier! Gamitin ito bago ang mga bayad na tier.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### 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: Provider: `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`
-**Gamitin:**`glm/glm-4.7` —**Pro Tip:**Nag-aalok ang Coding Plan ng 3× na quota sa halagang 1/7! I-reset araw-araw 10:00 AM.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Mag-sign up: [MiniMax](https://www.minimax.io/)
-2. Kunin ang API key → Dashboard → Magdagdag ng API Key
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Gamitin:**`minimax/MiniMax-M2.1` —**Pro Tip:**Pinaka murang opsyon para sa mahabang konteksto (1M token)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Mag-subscribe: [Moonshot AI](https://platform.moonshot.ai/)
-2. Kunin ang API key → Dashboard → Magdagdag ng API Key
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Gamitin:**`kimi/kimi-latest` —**Pro Tip:**Fixed $9/month para sa 10M token = $0.90/1M epektibong gastos!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-I-edit ang `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ I-edit ang `~/.claude/config.json`:```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-I-edit ang `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**O gumamit ng Dashboard:**CLI Tools → OpenClaw → Auto-config### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-Awtomatikong naglo-load ang CLI ng `.env` mula sa `~/.omniroute/.env` o `./.env`.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-Para sa mga server na may limitadong RAM, gamitin ang opsyon sa limitasyon ng memorya:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Lumikha ng `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,12 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-Para sa host-integrated mode na may mga CLI binary, tingnan ang seksyong Docker sa mga pangunahing doc.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Ang mga gumagamit ng Void Linux ay maaaring mag-package at mag-install ng OmniRoute nang native gamit ang `xbps-src` cross-compilation framework. I-automate nito ang standalone na build ng Node.js kasama ng kinakailangang mga native na binding na `better-sqlite3`.
+### Void Linux (xbps-src)
-
-Tingnan ang xbps-src template```bash
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -408,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -475,60 +516,63 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Variable | Default | Paglalarawan |
-| --------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**pagbabago sa produksyon**) |
-| `INITIAL_PASSWORD` | `123456` | Unang login password |
-| `DATA_DIR` | `~/.omniroute` | Direktoryo ng data (db, paggamit, mga log) |
-| `PORT` | default na framework | Port ng serbisyo (`20128` sa mga halimbawa) |
-| `HOSTNAME` | default na framework | Bind host (Docker default sa `0.0.0.0`) |
-| `NODE_ENV` | default na runtime | Itakda ang `produksyon` para sa pag-deploy |
-| `BASE_URL` | `http://localhost:20128` | Panloob na base URL sa gilid ng server |
-| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
-| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret para sa mga nabuong API key |
-| `REQUIRE_API_KEY` | `false` | Ipatupad ang Bearer API key sa `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `false` | Payagan ang Api Manager na kopyahin ang buong API keys on demand |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence para sa naka-cache na data ng Mga Limitasyon ng Provider; Ang mga button ng pag-refresh ng UI ay nagti-trigger pa rin ng manu-manong pag-sync |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Huwag paganahin ang mga awtomatikong snapshot ng SQLite bago magsulat/mag-import/mag-restore; gumagana pa rin ang mga manu-manong backup |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `false` | Pilitin ang `Secure` auth cookie (sa likod ng HTTPS reverse proxy) |
-| `CLOUDFLARED_BIN` | hindi nakatakda | Gumamit ng kasalukuyang binary na `cloudflared` sa halip na pinamamahalaang pag-download |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Transport para sa pinamamahalaang Quick Tunnels (`http2`, `quic`, o `auto`) |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit sa MB |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entry |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache na mga entry |Para sa buong environment variable reference, tingnan ang [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Tingnan ang lahat ng available na modelo
+
+View all available models
-**Claude Code (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— LIBRE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— $0.6/1M: `glm/glm-4.7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— $0.2/1M: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— LIBRE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— LIBRE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— LIBRE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
@@ -548,7 +592,9 @@ vlicense LICENSE
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -556,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Magdagdag ng anumang ID ng modelo sa anumang provider nang hindi naghihintay ng update ng app:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -564,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-O gamitin ang Dashboard:**Mga Provider → [Provider] → Mga Custom na Modelo**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Mga Tala:
+Notes:
-- Ang OpenRouter at OpenAI/Anthropic-compatible na provider ay pinamamahalaan mula sa**Available Models**lang. Manu-manong pagdaragdag, pag-import, at pag-auto-sync ng lahat ng lupain sa parehong listahan ng available na modelo, kaya walang hiwalay na seksyon ng Mga Custom na Modelo para sa mga provider na iyon.
-- Ang seksyong**Custom Models**ay inilaan para sa mga provider na hindi naglalantad ng mga pinamamahalaang pag-import ng available na modelo.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Direktang iruta ang mga kahilingan sa isang partikular na provider na may pagpapatunay ng modelo:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Ang prefix ng provider ay awtomatikong idinaragdag kung nawawala. Ang mga hindi tugmang modelo ay nagbabalik ng `400`.### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -594,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Precedence:**Key-specific → Combo-specific → Provider-specific → Global → Environment.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Ibinabalik ang mga modelong nakapangkat ayon sa provider na may mga uri (`chat`, `embedding`, `image`).### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- I-sync ang mga provider, combo, at mga setting sa mga device
-- Awtomatikong pag-sync sa background na may timeout + mabilis na mabibigo
-- Mas gusto ang server-side `BASE_URL`/`CLOUD_URL` sa produksyon### Cloudflare Quick Tunnel
+### Cloud Sync
-- Available sa**Dashboard → Endpoints**para sa Docker at iba pang self-hosted deployment
-- Lumilikha ng pansamantalang `https://*.trycloudflare.com` URL na nagpapasa sa iyong kasalukuyang `/v1` na tugma sa OpenAI na endpoint
-- Unang paganahin ang pag-install ng `cloudflared` lamang kapag kinakailangan; sa paglaon ay muling mag-re-reuse ang parehong pinamamahalaang binary
-- Ang Mga Mabilisang Tunnel ay hindi na-auto-restore pagkatapos ng OmniRoute o pag-restart ng container; muling paganahin ang mga ito mula sa dashboard kung kinakailangan
-- Ang mga URL ng tunnel ay panandalian at nagbabago sa tuwing hihinto/simulan mo ang tunnel
-- Default ang Managed Quick Tunnels sa HTTP/2 transport para maiwasan ang maingay na QUIC UDP buffer na babala sa mga pinipigilang container
-- Itakda ang `CLOUDFLARED_PROTOCOL=quic` o `auto` kung gusto mong i-override ang piniling pinamamahalaang transportasyon
-- Itakda ang `CLOUDFLARED_BIN` kung mas gusto mong gumamit ng paunang naka-install na `cloudflared` binary sa halip na ang pinamamahalaang pag-download### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Semantic Cache**— Auto-cache non-streaming, temperature=0 responses (bypass gamit ang `X-OmniRoute-No-Cache: true`) -**Request Idempotency**— Nagde-deduplicate ng mga kahilingan sa loob ng 5s sa pamamagitan ng `Idempotency-Key` o `X-Request-Id` header -**Pagsubaybay sa Pag-unlad**— Mag-opt-in sa SSE na mga kaganapan sa `kaganapan: pag-unlad` sa pamamagitan ng header ng `X-OmniRoute-Progress: true`---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Access sa pamamagitan ng**Dashboard → Translator**. I-debug at i-visualize kung paano isinasalin ng OmniRoute ang mga kahilingan sa API sa pagitan ng mga provider.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Mode | Layunin |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
-| **Laruan** | Pumili ng pinagmulan/target na mga format, i-paste ang isang kahilingan, at makita agad ang isinaling output |
-| **Chat Tester** | Magpadala ng mga mensahe sa live chat sa pamamagitan ng proxy at siyasatin ang buong cycle ng kahilingan/pagtugon |
-| **Test Bench** | Magpatakbo ng mga batch test sa maraming kumbinasyon ng format upang i-verify ang kawastuhan ng pagsasalin |
-| **Live Monitor** | Manood ng mga real-time na pagsasalin habang dumadaloy ang mga kahilingan sa pamamagitan ng proxy |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Mga kaso ng paggamit:**
+**Use cases:**
-- I-debug kung bakit nabigo ang isang partikular na kumbinasyon ng kliyente/provider
-- I-verify na ang mga tag ng pag-iisip, mga tawag sa tool, at mga prompt ng system ay naisalin nang tama
-- Ihambing ang mga pagkakaiba sa format sa pagitan ng mga format ng OpenAI, Claude, Gemini, at Responses API---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-I-configure sa pamamagitan ng**Dashboard → Mga Setting → Pagruruta**.
+Configure via **Dashboard → Settings → Routing**.
-| Diskarte | Paglalarawan |
-| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Punan muna** | Gumagamit ng mga account sa pagkakasunud-sunod ng priyoridad — pinangangasiwaan ng pangunahing account ang lahat ng kahilingan hanggang sa hindi magamit |
-| **Round Robin** | Umiikot sa lahat ng account na may na-configure na malagkit na limitasyon (default: 3 tawag sa bawat account) |
-| **P2C (Power of Two Choices)** | Pumili ng 2 random na account at ruta patungo sa mas malusog — binabalanse ang load nang may kamalayan sa kalusugan |
-| **Random** | Random na pumipili ng account para sa bawat kahilingan gamit ang Fisher-Yates shuffle |
-| **Hindi gaanong Nagamit** | Mga ruta papunta sa account na may pinakamatandang `lastUsedAt` timestamp, na namamahagi ng trapiko nang pantay-pantay |
-| **Na-optimize ang Gastos** | Mga ruta patungo sa account na may pinakamababang halaga ng priyoridad, na nag-o-optimize para sa mga provider na may pinakamababang halaga | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Para sa panlabas na affinity ng session (halimbawa, mga ahente ng Claude Code/Codex sa likod ng mga reverse proxy), ipadala ang:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-Tumatanggap din ang OmniRoute ng `x_session_id` at ibinabalik ang epektibong session key sa `X-OmniRoute-Session-Id`.
+If you use Nginx and send underscore-form headers, enable:
-Kung gumagamit ka ng Nginx at magpadala ng mga underscore-form na header, paganahin ang:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Lumikha ng mga pattern ng wildcard para i-remap ang mga pangalan ng modelo:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Ang mga wildcard ay sumusuporta sa `*` (anumang character) at `?` (solong character).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Tukuyin ang mga pandaigdigang fallback chain na nalalapat sa lahat ng kahilingan:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-I-configure sa pamamagitan ng**Dashboard → Mga Setting → Resilience**.
+Configure via **Dashboard → Settings → Resilience**.
-Ang OmniRoute ay nagpapatupad ng pagiging matatag sa antas ng provider na may apat na bahagi:
+OmniRoute implements provider-level resilience with four components:
-1.**Provider Profile**— Configuration ng bawat provider para sa:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Failure threshold (ilang pagkabigo bago buksan)
-- Tagal ng cooldown
-- Rate limit detection sensitivity
-- Exponential backoff na mga parameter
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Editable Rate Limits**— System-level defaults configurable sa dashboard: -**Requests Per Minute (RPM)**— Mga maximum na kahilingan kada minuto bawat account -**Min Time Between Requests**— Minimum na agwat sa millisecond sa pagitan ng mga kahilingan -**Max Kasabay na Kahilingan**— Pinakamataas na sabay-sabay na kahilingan sa bawat account
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- I-click ang**I-edit**upang baguhin, pagkatapos ay**I-save**o**Kanselahin**. Nananatili ang mga halaga sa pamamagitan ng resilience API.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Circuit Breaker**— Sinusubaybayan ang mga pagkabigo sa bawat provider at awtomatikong bubuksan ang circuit kapag naabot ang isang threshold: -**SARADO**(Healthy) — Normal na dumadaloy ang mga kahilingan -**OPEN**— Pansamantalang naka-block ang provider pagkatapos ng paulit-ulit na pagkabigo -**HALF_OPEN**— Pagsubok kung nakabawi na ang provider
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Mga Patakaran at Mga Naka-lock na Identifier**— Nagpapakita ng status ng circuit breaker at mga naka-lock na identifier na may kakayahan sa force-unlock.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Awtomatikong Pagtukoy sa Limitasyon ng Rate**— Sinusubaybayan ang mga header ng `429` at `Retry-After` upang aktibong maiwasang maabot ang mga limitasyon sa rate ng provider.
-
-**Pro Tip:**Gamitin ang**I-reset Lahat**na button para i-clear ang lahat ng mga circuit breaker at cooldown kapag gumaling ang isang provider mula sa isang outage.---
+---
### Database Export / Import
-Pamahalaan ang mga backup ng database sa**Dashboard → Mga Setting → System at Storage**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Aksyon | Paglalarawan |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **I-export ang Database** | Dina-download ang kasalukuyang database ng SQLite bilang isang `.sqlite` file |
-| **I-export Lahat (.tar.gz)** | Nagda-download ng buong backup na archive kabilang ang: database, mga setting, combo, mga koneksyon sa provider (walang mga kredensyal), metadata ng API key |
-| **Import Database** | Mag-upload ng `.sqlite` file upang palitan ang kasalukuyang database. Awtomatikong nagagawa ang pre-import na backup maliban kung `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Import Validation:**Ang na-import na file ay napatunayan para sa integridad (SQLite pragma check), kinakailangang mga talahanayan (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), at laki (max 100MB).
+**Use Cases:**
-**Mga Kaso ng Paggamit:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- I-migrate ang OmniRoute sa pagitan ng mga machine
-- Lumikha ng mga panlabas na backup para sa pagbawi ng kalamidad
-- Magbahagi ng mga pagsasaayos sa pagitan ng mga miyembro ng koponan (i-export lahat → ibahagi ang archive)---
+---
### Settings Dashboard
-Ang pahina ng mga setting ay isinaayos sa 6 na tab para sa madaling pag-navigate:
+The settings page is organized into 6 tabs for easy navigation:
-| Tab | Mga Nilalaman |
-| -------------- | ------------------------------------------------------------------------------------------------- |
-|**Pangkalahatan**| Mga tool sa storage ng system, mga setting ng hitsura, mga kontrol sa tema, at per-item sidebar visibility |
-|**Seguridad**| Mga setting ng Login/Password, IP Access Control, API auth para sa `/models`, at Provider Blocking |
-|**Pagruruta**| Pandaigdigang diskarte sa pagruruta (6 na opsyon), wildcard model alias, fallback chain, combo default |
-|**Katatagan**| Mga profile ng provider, mga limitasyon sa nae-edit na rate, status ng circuit breaker, mga patakaran at mga naka-lock na identifier |
-|**AI**| Pag-iisip ng configuration ng badyet, pandaigdigang system prompt injection, prompt cache stats |
-|**Advanced**| Global proxy configuration (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Access sa pamamagitan ng**Dashboard → Mga Gastos**.
+Access via **Dashboard → Costs**.
-| Tab | Layunin |
-| ----------- | ------------------------------------------------------------------------------------ |
-|**Badyet**| Magtakda ng mga limitasyon sa paggastos sa bawat API key na may pang-araw-araw/lingguhan/buwanang mga badyet at real-time na pagsubaybay |
-|**Pagpepresyo**| Tingnan at i-edit ang mga entry sa pagpepresyo ng modelo — cost per 1K input/output token bawat provider |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -765,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Pagsubaybay sa Gastos:**Ang bawat kahilingan ay nagtatala ng paggamit ng token at kinakalkula ang gastos gamit ang talahanayan ng pagpepresyo. Tingnan ang mga breakdown sa**Dashboard → Paggamit**ayon sa provider, modelo, at API key.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-Sinusuportahan ng OmniRoute ang audio transcription sa pamamagitan ng OpenAI-compatible na endpoint:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Mga available na provider:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Mga sinusuportahang format ng audio: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.---
+---
### Combo Balancing Strategies
-I-configure ang per-combo balancing sa**Dashboard → Combos → Create/Edit → Strategy**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Diskarte | Paglalarawan |
-| ------------------- | ---------------------------------------------------------------------- |
-|**Round-Robin**| Umiikot sa mga modelo nang sunud-sunod |
-|**Priyoridad**| Palaging sinusubukan ang unang modelo; bumabalik lamang sa error |
-|**Random**| Pumipili ng random na modelo mula sa combo para sa bawat kahilingan |
-|**Tinimbang**| Mga rutang proporsyonal batay sa mga nakatalagang timbang sa bawat modelo |
-|**Hindi gaanong Nagamit**| Mga ruta patungo sa modelo na may kaunting mga kamakailang kahilingan (gumagamit ng combo metrics) |
-|**Cost-Optimized**| Mga ruta patungo sa pinakamurang available na modelo (gumagamit ng talahanayan ng pagpepresyo) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Maaaring itakda ang mga global combo default sa**Dashboard → Settings → Routing → Combo Defaults**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Access sa pamamagitan ng**Dashboard → Health**. Real-time na pangkalahatang-ideya ng kalusugan ng system na may 6 na card:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Card | Ano ang Ipinakikita Nito |
-| ---------------------- | -------------------------------------------------------- |
-|**System Status**| Uptime, bersyon, paggamit ng memorya, direktoryo ng data |
-|**Kalusugan ng Provider**| Status ng circuit breaker ng bawat provider (Sarado/Bukas/Kalahating Bukas) |
-|**Mga Limitasyon sa Rate**| Mga cooldown sa limitasyon ng aktibong rate sa bawat account na may natitirang oras |
-|**Mga Aktibong Lockout**| Pansamantalang na-block ang mga provider ng patakaran sa lockout |
-|**Signature Cache**| Deduplication cache stats (aktibong key, hit rate) |
-|**Latency Telemetry**| p50/p95/p99 latency aggregation bawat provider |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Pro Tip:**Awtomatikong nagre-refresh ang page ng Health bawat 10 segundo. Gamitin ang circuit breaker card upang matukoy kung aling mga provider ang nakakaranas ng mga isyu.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-Available ang OmniRoute bilang isang katutubong desktop application para sa Windows, macOS, at Linux.### I-install
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### I-install
```bash
# From the electron directory:
@@ -833,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -845,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Output → `electron/dist-electron/`### Key Features
+Output → `electron/dist-electron/`
-| Tampok | Paglalarawan |
-| --------------------------------------- | -------------------------------------------------------------------- | ------------------------- |
-| **Kahandaan ng Server** | Server ng botohan bago magpakita ng window (walang blangkong screen) |
-| **System Tray** | I-minimize sa tray, palitan ang port, quit mula sa tray menu |
-| **Pamamahala ng Port** | Baguhin ang port ng server mula sa tray (auto-restart ang server) |
-| **Patakaran sa Seguridad ng Nilalaman** | Mahigpit na CSP sa pamamagitan ng mga header ng session |
-| **Sisang Instance** | Isang instance ng app lang ang maaaring tumakbo sa isang pagkakataon |
-| **Offline Mode** | Ang Bundled Next.js server ay gumagana nang walang internet | ### Environment Variables |
+### Key Features
-| Variable | Default | Paglalarawan |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
+
+### Environment Variables
+
+| Variable | Default | Description |
| --------------------- | ------- | -------------------------------- |
-| `OMNIROUTE_PORT` | `20128` | Port ng server |
+| `OMNIROUTE_PORT` | `20128` | Server port |
| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
-📖 Buong dokumentasyon: [`electron/README.md`](../electron/README.md)
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/pl/README.md b/docs/i18n/pl/README.md
index 240a0d14ae..f1982931d2 100644
--- a/docs/i18n/pl/README.md
+++ b/docs/i18n/pl/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/pl/docs/USER_GUIDE.md b/docs/i18n/pl/docs/USER_GUIDE.md
index 2fe855c387..172ec460c7 100644
--- a/docs/i18n/pl/docs/USER_GUIDE.md
+++ b/docs/i18n/pl/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Kompletny przewodnik dotyczący konfigurowania dostawców, tworzenia kombinacji, integracji narzędzi CLI i wdrażania OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Ceny w skrócie](#-pricing-at-a-glance)
-- [Przypadki użycia](#-przypadków użycia)
-- [Konfiguracja dostawcy](#-konfiguracja-dostawcy)
-- [Integracja CLI](#-integracja z cli)
-- [Wdrożenie](#-wdrożenie)
-- [Dostępne modele](#-dostępne-modele)
-- [Funkcje zaawansowane](#-funkcje zaawansowane)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 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** | DeepSeek | Płać za użycie | Brak | Tanie rozumowanie |
-| | Groq | Płać za użycie | Brak | Ultraszybkie wnioskowanie |
-| | xAI (Grok) | Płać za użycie | Brak | Grok 4 rozumowanie |
-| | Mistral | Płać za użycie | Brak | Modele hostowane w UE |
-| | Zakłopotanie | Płać za użycie | Brak | Rozszerzone wyszukiwanie |
-| | Razem AI | Płać za użycie | Brak | Modele open source |
-| | Fajerwerki AI | Płać za użycie | Brak | Obrazy Fast FLUX |
-| | Cerebra | Płać za użycie | Brak | Prędkość w skali opłatka |
-| | Spójne | Płać za użycie | Brak | Polecenie R+RAG |
-| | NVIDIA NIM | Płać za użycie | Brak | Modele korporacyjne |
-| **💰 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** | Qoder | 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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Wskazówka dla profesjonalistów:**Zacznij od zestawu Gemini CLI (180 tys. za darmo/miesiąc) + Qoder (bez ograniczeń za darmo) = koszt 0 USD!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Problem:**Limit wygasa niewykorzystany, limity szybkości podczas intensywnego kodowania```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Problem:**Nie stać Cię na subskrypcję, potrzebujesz niezawodnego kodowania AI```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Problem:**Terminy, nie mogę sobie pozwolić na przestoje```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Problem:**Potrzebujesz asystenta AI w aplikacjach do przesyłania wiadomości, całkowicie za darmo```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,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!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Najlepsza wartość:**Ogromny darmowy poziom! Użyj tego przed płatnymi poziomami.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### 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: `twój-klucz`
+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` —**Wskazówka dla profesjonalistów:**Plan kodowania oferuje 3× limit przy cenie 1/7! Resetuj codziennie o 10:00.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Zarejestruj się: [MiniMax](https://www.minimax.io/)
-2. Uzyskaj klucz API → Panel kontrolny → Dodaj klucz API
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Użyj:**`minimax/MiniMax-M2.1` —**Wskazówka:**Najtańsza opcja dla długiego kontekstu (1M tokenów)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Subskrybuj: [Moonshot AI](https://platform.moonshot.ai/)
-2. Uzyskaj klucz API → Panel kontrolny → Dodaj klucz API
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Użyj:**`kimi/kimi-latest` —**Wskazówka:**Naprawiono 9 USD/miesiąc za 10 mln tokenów = efektywny koszt 0,90 USD/1 mln!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Edytuj `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Edytuj `~/.claude/config.json`:```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Edytuj `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Lub użyj Dashboardu:**Narzędzia CLI → OpenClaw → Auto-config### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-Interfejs CLI automatycznie ładuje `.env` z `~/.omniroute/.env` lub `./.env`.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-W przypadku serwerów z ograniczoną ilością pamięci RAM użyj opcji limitu pamięci:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Utwórz plik `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,13 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-Informacje na temat trybu zintegrowanego z hostem i plików binarnych CLI można znaleźć w sekcji Docker w głównych dokumentach.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Użytkownicy Void Linux mogą spakować i zainstalować OmniRoute natywnie, korzystając ze środowiska kompilacji krzyżowej `xbps-src`. Automatyzuje to samodzielną kompilację Node.js wraz z wymaganymi natywnymi powiązaniami „better-sqlite3”.
+### Void Linux (xbps-src)
-
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
-Wyświetl szablon xbps-src```bash
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -409,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -476,80 +516,85 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Zmienna | Domyślne | Opis |
-| ---------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
-| `JWT_SECRET` | `omniroute-domyślny-sekret-zmień mnie` | Tajemnica podpisania JWT (**zmiana w produkcji**) |
-| `INITIAL_HASŁO` | `123456` | Hasło pierwszego logowania |
-| `DANE_KATALOG` | `~/.omniroute` | Katalog danych (db, wykorzystanie, logi) |
-| `PORT` | domyślne ramy | Port serwisowy (w przykładach „20128”) |
-| `NAZWA HOSTA` | domyślne ramy | Powiąż hosta (Docker domyślnie ma wartość `0.0.0.0`) |
-| `WĘZEŁ_ENV` | domyślne środowisko wykonawcze | Ustaw „produkcję” dla wdrożenia |
-| `BAZA_URL` | `http://localhost:20128` | Wewnętrzny podstawowy adres URL po stronie serwera |
-| `CHMUROWY_URL` | `https://omniroute.dev` | Podstawowy adres URL punktu końcowego synchronizacji w chmurze |
-| `API_KEY_SECRET` | `sekret-klucza-proxy-api-punktu końcowego` | Sekret HMAC dla wygenerowanych kluczy API |
-| `REQUIRE_API_KEY` | `fałszywy` | Wymuś klucz API nośnika na `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `fałszywy` | Zezwalaj Api Managerowi na kopiowanie pełnych kluczy API na żądanie |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Częstotliwość odświeżania po stronie serwera buforowanych danych dotyczących limitów dostawcy; Przyciski odświeżania interfejsu użytkownika nadal uruchamiają ręczną synchronizację |
-| `WYŁĄCZ_SQLITE_AUTO_BACKUP` | `fałszywy` | Wyłącz automatyczne migawki SQLite przed zapisem/importem/przywróceniem; ręczne kopie zapasowe nadal działają |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `fałszywy` | Wymuś „bezpieczny” plik cookie uwierzytelniający (za odwrotnym proxy HTTPS) |
-| `CLOUDFLARED_BIN` | rozbrojony | Użyj istniejącego pliku binarnego `cloudflared` zamiast zarządzanego pobierania |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Transport dla zarządzanych szybkich tuneli (`http2`, `quic` lub `auto`) |
-| `OMNIROUTE_MEMORY_MB` | `512` | Limit sterty Node.js w MB |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | Maksymalna liczba wpisów w pamięci podręcznej monitów |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Maksymalna liczba wpisów w semantycznej pamięci podręcznej |Pełne odwołanie do zmiennych środowiskowych można znaleźć w [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Wyświetl wszystkie dostępne modele
+
+View all available models
-**Kod Claude (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Kodeks (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— ZA DARMO: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM („glm/`)**— 0,6 USD/1 mln: `glm/glm-4,7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax („minimax/`)**— 0,2 USD/1 mln: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— BEZPŁATNE: `if/kimi-k2-myślenie`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— ZA DARMO: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— ZA DARMO: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
-**Groq (`groq/`)**: `groq/llama-3.3-70b-uniwersalny`, `groq/llama-4-maverick-17b-128e-instrukcja`
+**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
-**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-szybkie-rozumowanie`, `xai/grok-code-mini`
+**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Zagubienie (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**Razem AI („razem/`)**: `razem/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**Fajerwerki AI (`fajerwerki/`)**: `fajerwerki/konta/fajerwerki/modele/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**Cerebras (`cerebras/`)**: `mózgowie/lama-3.3-70b`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
-**Spójność (`spójność/`)**: `spójność/polecenie-r-plus-08-2024`
+**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instrukcja`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -557,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Dodaj dowolny identyfikator modelu do dowolnego dostawcy, nie czekając na aktualizację aplikacji:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -565,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Lub użyj Panelu:**Dostawcy → [Dostawca] → Modele niestandardowe**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Uwagi:
+Notes:
-- Dostawcy obsługujący OpenRouter i OpenAI/Anthropic są zarządzani wyłącznie z poziomu**Dostępnych modeli**. Ręczne dodawanie, importowanie i automatyczna synchronizacja wszystkich gruntów na tej samej liście dostępnych modeli, więc nie ma osobnej sekcji modeli niestandardowych dla tych dostawców.
- — Sekcja**Modele niestandardowe**jest przeznaczona dla dostawców, którzy nie udostępniają importów zarządzanych dostępnych modeli.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Kieruj żądania bezpośrednio do konkretnego dostawcy z walidacją modelu:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Prefiks dostawcy jest dodawany automatycznie, jeśli go brakuje. Niedopasowane modele zwracają „400”.### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -595,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Pierwszeństwo:**specyficzne dla klucza → specyficzne dla kombinacji → specyficzne dla dostawcy → globalne → środowisko.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Zwraca modele pogrupowane według dostawców z typami („czat”, „osadzanie”, „obraz”).### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Synchronizuj dostawców, kombinacje i ustawienia na różnych urządzeniach
-- Automatyczna synchronizacja w tle z limitem czasu + szybka awaria
-- Preferuj `BASE_URL`/`CLOUD_URL` po stronie serwera w środowisku produkcyjnym### Cloudflare Quick Tunnel
+### Cloud Sync
-- Dostępne w**Panel kontrolny → Punkty końcowe**dla Dockera i innych wdrożeń hostowanych samodzielnie
-- Tworzy tymczasowy adres URL `https://*.trycloudflare.com`, który przekazuje do bieżącego punktu końcowego `/v1` kompatybilnego z OpenAI
-- Najpierw włącz instalację „cloudflared” tylko wtedy, gdy jest to potrzebne; później uruchamia ponownie, ponownie używa tego samego zarządzanego pliku binarnego
-- Szybkie tunele nie są automatycznie przywracane po ponownym uruchomieniu OmniRoute lub kontenera; w razie potrzeby włącz je ponownie z poziomu pulpitu nawigacyjnego
-- Adresy URL tuneli są efemeryczne i zmieniają się przy każdym zatrzymaniu/uruchomieniu tunelu
- — Zarządzane szybkie tunele domyślnie korzystają z transportu HTTP/2, aby uniknąć hałaśliwych ostrzeżeń o buforze QUIC UDP w ograniczonych kontenerach
-- Ustaw `CLOUDFLARED_PROTOCOL=quic` lub `auto`, jeśli chcesz zastąpić wybór zarządzanego transportu
-- Ustaw `CLOUDFLARED_BIN`, jeśli wolisz używać preinstalowanego pliku binarnego `cloudflared` zamiast zarządzanego pobierania### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Semantyczna pamięć podręczna**— automatycznie buforuje dane niestrumieniowe, temperatura = 0 odpowiedzi (pomiń przy użyciu opcji `X-OmniRoute-No-Cache: true`) -**Request Idempotency**— Deduplikuje żądania w ciągu 5 sekund za pomocą nagłówka `Idempotency-Key` lub `X-Request-Id` -**Śledzenie postępu**— Możliwość wyrażenia zgody na zdarzenia SSE „event: postęp” poprzez nagłówek „X-OmniRoute-Progress: true”---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Dostęp przez**Panel kontrolny → Tłumacz**. Debuguj i wizualizuj, jak OmniRoute tłumaczy żądania API między dostawcami.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Tryb | Cel |
-| ------------------------- | --------------------------------------------------------------------------------------------------- |
-| **Plac zabaw** | Wybierz formaty źródłowe/docelowe, wklej żądanie i natychmiast zobacz przetłumaczone dane wyjściowe |
-| **Tester czatu** | Wysyłaj wiadomości na czacie na żywo przez serwer proxy i sprawdzaj pełny cykl żądań/odpowiedzi |
-| **Stolik testowy** | Przeprowadź testy wsadowe w wielu kombinacjach formatów, aby sprawdzić poprawność tłumaczenia |
-| **Monitorowanie na żywo** | Oglądaj tłumaczenia w czasie rzeczywistym, gdy żądania przepływają przez serwer proxy |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Przypadki użycia:**
+**Use cases:**
-- Debugowanie, dlaczego konkretna kombinacja klient/dostawca nie działa
-- Sprawdź, czy znaczniki myślenia, wywołania narzędzi i podpowiedzi systemowe są tłumaczone poprawnie
-- Porównaj różnice w formatach między formatami OpenAI, Claude, Gemini i Responses API---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Skonfiguruj za pomocą**Panel kontrolny → Ustawienia → Routing**.
+Configure via **Dashboard → Settings → Routing**.
-| Strategia | Opis |
-| ------------------------------ | ----------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Najpierw wypełnij** | Używa kont w kolejności priorytetów — konto podstawowe obsługuje wszystkie żądania, aż będą niedostępne |
-| **Robinowy** | Przełącza między wszystkimi kontami z konfigurowalnym limitem stałym (domyślnie: 3 połączenia na konto) |
-| **P2C (potęga dwóch wyborów)** | Wybiera 2 losowe konta i ścieżki do zdrowszego — równoważy obciążenie świadomością zdrowia |
-| **Losowe** | Losowo wybiera konto dla każdego żądania, korzystając z funkcji losowania Fisher-Yates |
-| **Najrzadziej używane** | Trasy do konta z najstarszym znacznikiem czasu „lastUsedAt”, równomiernie rozkładając ruch |
-| **Optymalizacja kosztów** | Kieruje do konta o najniższej wartości priorytetu, optymalizując pod kątem dostawców o najniższych kosztach | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-W przypadku koligacji sesji zewnętrznej (na przykład agenci Claude Code/Codex za zwrotnymi serwerami proxy) wyślij:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute akceptuje także `x_session_id` i zwraca efektywny klucz sesji w `X-OmniRoute-Session-Id`.
+If you use Nginx and send underscore-form headers, enable:
-Jeśli używasz Nginx i wysyłasz nagłówki w formie podkreślenia, włącz:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Utwórz wzorce symboli wieloznacznych, aby ponownie przypisać nazwy modeli:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Symbole wieloznaczne obsługują `*` (dowolne znaki) i `?` (pojedynczy znak).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Zdefiniuj globalne łańcuchy awaryjne, które mają zastosowanie do wszystkich żądań:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Skonfiguruj za pomocą**Panel kontrolny → Ustawienia → Odporność**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute wdraża odporność na poziomie dostawcy za pomocą czterech komponentów:
+OmniRoute implements provider-level resilience with four components:
-1.**Profile dostawców**— konfiguracja dla poszczególnych dostawców dla:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Próg awaryjności (ile awarii przed otwarciem)
-- Czas odnowienia
-- Czułość wykrywania limitu szybkości
-- Wykładnicze parametry wycofywania
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Edytowalne limity prędkości**— Domyślne ustawienia na poziomie systemu można skonfigurować w panelu kontrolnym: -**Żądania na minutę (RPM)**— Maksymalna liczba żądań na minutę na konto -**Min. czas między żądaniami**— Minimalna przerwa w milisekundach między żądaniami -**Maksymalna liczba jednoczesnych żądań**— Maksymalna liczba jednoczesnych żądań na konto
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Kliknij**Edytuj**, aby zmodyfikować, a następnie**Zapisz**lub**Anuluj**. Wartości są zachowywane za pośrednictwem interfejsu API odporności.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Wyłącznik**— śledzi awarie według dostawcy i automatycznie otwiera obwód po osiągnięciu progu: -**ZAMKNIĘTE**(zdrowe) — Żądania przebiegają normalnie -**OTWARTE**— Dostawca jest tymczasowo blokowany po powtarzających się awariach -**HALF_OPEN**— Sprawdzanie, czy dostawca powrócił do zdrowia
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Zasady i zablokowane identyfikatory**— Pokazuje stan wyłącznika automatycznego i zablokowane identyfikatory z możliwością wymuszonego odblokowania.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Automatyczne wykrywanie limitu szybkości**— Monitoruje nagłówki „429” i „Retry-After”, aby aktywnie zapobiegać przekroczeniu limitów szybkości dostawcy.
-
-**Wskazówka dla profesjonalistów:**Użyj przycisku**Resetuj wszystko**, aby wyczyścić wszystkie wyłączniki automatyczne i czasy odnowienia, gdy dostawca wznowi działanie po awarii.---
+---
### Database Export / Import
-Zarządzaj kopiami zapasowymi baz danych w**Panel kontrolny → Ustawienia → System i pamięć masowa**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Akcja | Opis |
-| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Eksportuj bazę danych** | Pobiera bieżącą bazę danych SQLite jako plik `.sqlite` |
-| **Eksportuj wszystko (.tar.gz)** | Pobiera pełne archiwum kopii zapasowych, w tym: bazę danych, ustawienia, kombinacje, połączenia z dostawcami (bez poświadczeń), metadane klucza API |
-| **Importuj bazę danych** | Prześlij plik `.sqlite`, aby zastąpić bieżącą bazę danych. Kopia zapasowa przed importem jest tworzona automatycznie, chyba że `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Weryfikacja importu:**Zaimportowany plik jest sprawdzany pod kątem integralności (sprawdzanie pragma SQLite), wymaganych tabel („połączenia_dostawcy”, „węzły_dostawcy”, „combos”, „klucze_api”) i rozmiaru (maks. 100MB).
+**Use Cases:**
-**Przypadki użycia:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Przeprowadź migrację OmniRoute pomiędzy maszynami
-- Twórz zewnętrzne kopie zapasowe w celu odzyskiwania po awarii
-- Udostępniaj konfiguracje pomiędzy członkami zespołu (eksportuj wszystko → udostępnij archiwum)---
+---
### Settings Dashboard
-Strona ustawień jest podzielona na 6 zakładek ułatwiających nawigację:
+The settings page is organized into 6 tabs for easy navigation:
-| Zakładka | Spis treści |
-| -------------- | -------------------------------------------------------------------------------------------------------- |
-|**Ogólne**| Narzędzia pamięci systemowej, ustawienia wyglądu, elementy sterujące motywem i widoczność paska bocznego poszczególnych elementów |
-|**Bezpieczeństwo**| Ustawienia loginu/hasła, kontrola dostępu IP, autoryzacja API dla `/models` i blokowanie dostawców |
-|**Trasowanie**| Globalna strategia routingu (6 opcji), aliasy modeli z symbolami wieloznacznymi, łańcuchy awaryjne, domyślne kombinacje |
-|**Odporność**| Profile dostawców, edytowalne limity stawek, stan wyłącznika, zasady i zablokowane identyfikatory |
-|**AI**| Myślenie o konfiguracji budżetu, globalnym wstrzykiwaniu podpowiedzi do systemu, szybkich statystykach pamięci podręcznej |
-|**Zaawansowane**| Globalna konfiguracja proxy (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Dostęp przez**Panel kontrolny → Koszty**.
+Access via **Dashboard → Costs**.
-| Zakładka | Cel |
-| ----------- | -------------------------------------------------------------------------------------------------- |
-|**Budżet**| Ustaw limity wydatków na klucz API z budżetami dziennymi/tygodniowymi/miesięcznymi i śledzeniem w czasie rzeczywistym |
-|**Cennik**| Wyświetlaj i edytuj wpisy cen modelu — koszt za 1 tys. tokenów wejścia/wyjścia na dostawcę |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -766,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Śledzenie kosztów:**każde żądanie rejestruje użycie tokena i oblicza koszt, korzystając z tabeli cen. Zobacz zestawienia w**Panel kontrolny → Użycie**według dostawcy, modelu i klucza API.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute obsługuje transkrypcję audio za pośrednictwem punktu końcowego kompatybilnego z OpenAI:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Dostępni dostawcy:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Obsługiwane formaty audio: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.---
+---
### Combo Balancing Strategies
-Skonfiguruj równoważenie poszczególnych kombinacji w**Panel sterowania → Kombinacje → Utwórz/edytuj → Strategia**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Strategia | Opis |
-| ------------------ | ---------------------------------------------------------------------------------- |
-|**Równy każdy z każdym**| Obraca modele sekwencyjnie |
-|**Priorytet**| Zawsze wypróbowuje pierwszy model; powraca tylko w przypadku błędu |
-|**Losowe**| Wybiera losowy model z kombinacji dla każdego żądania |
-|**Ważona**| Trasy proporcjonalnie na podstawie przypisanych wag do modelu |
-|**Najrzadziej używane**| Trasy do modelu z najmniejszą liczbą ostatnich żądań (wykorzystuje metryki kombi) |
-|**Optymalizacja kosztów**| Trasy do najtańszego dostępnego modelu (korzysta z tabeli cen) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Globalne ustawienia domyślne kombinacji można ustawić w**Panel sterowania → Ustawienia → Routing → Domyślne ustawienia kombinacji**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Dostęp przez**Panel kontrolny → Zdrowie**. Przegląd stanu systemu w czasie rzeczywistym za pomocą 6 kart:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Karta | Co to pokazuje |
-| ----------------------------------- | ----------------------------------------------------------- |
-|**Stan systemu**| Czas pracy, wersja, wykorzystanie pamięci, katalog danych |
-|**Zdrowie dostawcy**| Stan wyłącznika automatycznego dostawcy (zamknięty/otwarty/półotwarty) |
-|**Limity stawek**| Aktywne czasy odnowienia limitu szybkości na konto z pozostałym czasem |
-|**Aktywne blokady**| Dostawcy tymczasowo zablokowani przez politykę blokad |
-|**Pamięć podręczna podpisów**| Statystyki pamięci podręcznej deduplikacji (aktywne klucze, współczynnik trafień) |
-|**Telemetria opóźnień**| Agregacja opóźnień p50/p95/p99 na dostawcę |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Wskazówka dla profesjonalistów:**Strona Zdrowie odświeża się automatycznie co 10 sekund. Użyj karty wyłącznika, aby zidentyfikować dostawców, u których występują problemy.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute jest dostępny jako natywna aplikacja komputerowa dla systemów Windows, macOS i Linux.### Zainstaluj
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Zainstaluj
```bash
# From the electron directory:
@@ -834,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -846,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Wyjście → `elektron/odległość-elektron/`### Key Features
+Output → `electron/dist-electron/`
-| Funkcja | Opis |
-| ---------------------------------- | ---------------------------------------------------------------- | ------------------------- |
-| **Gotowość serwera** | Odpytuje serwer przed wyświetleniem okna (bez pustego ekranu) |
-| **Taca systemowa** | Minimalizuj do zasobnika, zmień port, wyjdź z menu zasobnika |
-| **Zarządzanie portem** | Zmień port serwera z zasobnika (automatycznie restartuje serwer) |
-| **Polityka bezpieczeństwa treści** | Restrykcyjny CSP poprzez nagłówki sesji |
-| **Pojedyncza instancja** | Jednocześnie może działać tylko jedna instancja aplikacji |
-| **Tryb offline** | Dołączony serwer Next.js działa bez Internetu | ### Environment Variables |
+### Key Features
-| Zmienna | Domyślne | Opis |
-| --------------------- | -------- | ---------------------------------- |
-| `OMNIROUT_PORT` | `20128` | Port serwera |
-| `OMNIROUTE_MEMORY_MB` | `512` | Limit sterty Node.js (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Pełna dokumentacja: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/pt-BR/README.md b/docs/i18n/pt-BR/README.md
index 8fa83980c1..2d944b4aa3 100644
--- a/docs/i18n/pt-BR/README.md
+++ b/docs/i18n/pt-BR/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/pt-BR/docs/USER_GUIDE.md b/docs/i18n/pt-BR/docs/USER_GUIDE.md
index 8eac29d065..4a2c80254e 100644
--- a/docs/i18n/pt-BR/docs/USER_GUIDE.md
+++ b/docs/i18n/pt-BR/docs/USER_GUIDE.md
@@ -4,6 +4,8 @@
---
+
+
Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
---
@@ -223,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -339,6 +343,17 @@ omniroute --port 3000
The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### VPS Deployment
```bash
diff --git a/docs/i18n/pt/README.md b/docs/i18n/pt/README.md
index e8a1b441f6..8f62841b13 100644
--- a/docs/i18n/pt/README.md
+++ b/docs/i18n/pt/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/pt/docs/USER_GUIDE.md b/docs/i18n/pt/docs/USER_GUIDE.md
index a41d2f2a1c..4769e1c9c6 100644
--- a/docs/i18n/pt/docs/USER_GUIDE.md
+++ b/docs/i18n/pt/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Guia completo para configurar provedores, criar combos, integrar ferramentas CLI e implantar OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Preços resumidos](#-pricing-at-a-glance)
-- [Casos de uso](#-casos de uso)
-- [Configuração do provedor](#-configuração do provedor)
-- [Integração CLI](#-cli-integração)
-- [Implantação](#-implantação)
-- [Modelos disponíveis](#-modelos disponíveis)
-- [Recursos avançados](#-recursos avançados)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 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** | DeepSeek | Pague por uso | Nenhum | Raciocínio barato |
-| | Groq | Pague por uso | Nenhum | Inferência ultrarrápida |
-| | xAI (Grok) | Pague por uso | Nenhum | Raciocínio Grok 4 |
-| | Mistral | Pague por uso | Nenhum | Modelos hospedados na UE |
-| | Perplexidade | Pague por uso | Nenhum | Pesquisa aumentada |
-| | Juntos IA | Pague por uso | Nenhum | Modelos de código aberto |
-| | IA de fogos de artifício | Pague por uso | Nenhum | Imagens FLUX rápidas |
-| | Cérebros | Pague por uso | Nenhum | Velocidade em escala de wafer |
-| | Coerente | Pague por uso | Nenhum | Comando R+ RAG |
-| | NVIDIA NIM | Pague por uso | Nenhum | Modelos empresariais |
-| **💰 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** | Qoder | $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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Dica profissional:**Comece com Gemini CLI (180 mil grátis/mês) + combo Qoder (grátis ilimitado) = custo de $ 0!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Problema:**A cota expira sem ser utilizada, limites de taxa durante codificação pesada```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Problema:**Não posso pagar assinaturas, preciso de codificação de IA confiável```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Problema:**Prazos, não podemos arcar com o tempo de inatividade```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Problema:**Precisa de assistente de IA em aplicativos de mensagens, totalmente gratuito```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,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!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Melhor valor:**Grande nível gratuito! Use isso antes dos níveis pagos.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### 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 de API: Provedor: `glm`, chave de API: `sua-chave`
+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 profissional:**O plano de codificação oferece cota 3× pelo custo de 1/7! Redefinir diariamente às 10h.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Cadastre-se: [MiniMax](https://www.minimax.io/)
-2. Obter chave de API → Painel → Adicionar chave de API
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Use:**`minimax/MiniMax-M2.1` —**Dica profissional:**Opção mais barata para contexto longo (tokens de 1 milhão)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Inscreva-se: [Moonshot AI](https://platform.moonshot.ai/)
-2. Obter chave de API → Painel → Adicionar chave de API
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Use:**`kimi/kimi-latest` —**Dica profissional:**Fixo US$ 9/mês para 10 milhões de tokens = US$ 0,90/1 milhão de custo efetivo!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Edite `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Edite `~/.claude/config.json`:```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Edite `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Ou use o Dashboard:**Ferramentas CLI → OpenClaw → Configuração automática### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-A CLI carrega automaticamente `.env` de `~/.omniroute/.env` ou `./.env`.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-Para servidores com RAM limitada, use a opção de limite de memória:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Crie `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,12 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-Para o modo integrado ao host com binários CLI, consulte a seção Docker na documentação principal.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Os usuários do Void Linux podem empacotar e instalar o OmniRoute nativamente usando a estrutura de compilação cruzada `xbps-src`. Isso automatiza a construção autônoma do Node.js junto com as ligações nativas `better-sqlite3` necessárias.
+### Void Linux (xbps-src)
-
-Ver modelo xbps-src```bash
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -408,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -475,60 +516,63 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Variável | Padrão | Descrição |
-| --------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | Segredo de assinatura do JWT (**mudança na produção**) |
-| `INITIAL_PASSWORD` | `123456` | Senha do primeiro login |
-| `DADOS_DIR` | `~/.omniroute` | Diretório de dados (banco de dados, uso, logs) |
-| `PORTO` | padrão da estrutura | Porta de serviço (`20128` nos exemplos) |
-| `NOME DO ANFITRIÃO` | padrão da estrutura | Vincular host (o padrão do Docker é `0.0.0.0`) |
-| `NODE_ENV` | padrão de tempo de execução | Defina `produção` para implantação |
-| `BASE_URL` | `http://localhost:20128` | URL base interna do lado do servidor |
-| `CLOUD_URL` | `https://omniroute.dev` | URL base do endpoint de sincronização em nuvem |
-| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Segredo HMAC para chaves de API geradas |
-| `REQUIRE_API_KEY` | `falso` | Aplicar chave de API do portador em `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `falso` | Permitir que o Api Manager copie chaves de API completas sob demanda |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Cadência de atualização do lado do servidor para dados armazenados em cache do Provider Limits; Os botões de atualização da IU ainda acionam a sincronização manual |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `falso` | Desative os instantâneos automáticos do SQLite antes de gravar/importar/restaurar; backups manuais ainda funcionam |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `falso` | Forçar cookie de autenticação `Secure` (por trás do proxy reverso HTTPS) |
-| `CLOUDFLARED_BIN` | desarmar | Use um binário `cloudflared` existente em vez de download gerenciado |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Transporte para Quick Tunnels gerenciados (`http2`, `quic` ou `auto`) |
-| `OMNIROUTE_MEMORY_MB` | `512` | Limite de heap do Node.js em MB |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | Máximo de entradas de cache de prompt |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Máximo de entradas de cache semântico |Para obter a referência completa da variável de ambiente, consulte o [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Ver todos os modelos disponíveis
+
+View all available models
-**Código Claude (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— GRATUITO: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**Copiloto do GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— US$ 0,6/1 milhão: `glm/glm-4.7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— US$ 0,2/1 milhão: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— GRATUITO: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— GRATUITO: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— GRATUITO: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
@@ -538,17 +582,19 @@ vlicense LICENSE
**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Perplexidade (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**Juntos AI (`juntos/`)**: `juntos/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**IA do Fireworks (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -556,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Adicione qualquer ID de modelo a qualquer provedor sem esperar por uma atualização do aplicativo:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -564,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Ou use o Dashboard:**Provedores → [Provedor] → Modelos personalizados**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Notas:
+Notes:
-- Provedores compatíveis com OpenRouter e OpenAI/Anthropic são gerenciados apenas a partir de**Modelos disponíveis**. Adição manual, importação e sincronização automática estão na mesma lista de modelos disponíveis, portanto, não há uma seção separada de modelos personalizados para esses provedores.
-- A seção**Modelos Personalizados**destina-se a provedores que não expõem importações gerenciadas de modelos disponíveis.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Encaminhe solicitações diretamente para um provedor específico com validação de modelo:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-O prefixo do provedor é adicionado automaticamente se estiver ausente. Modelos incompatíveis retornam `400`.### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -594,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Precedência:**Específico da chave → Específico do combo → Específico do provedor → Global → Ambiente.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Retorna modelos agrupados por provedor com tipos (`chat`, `embedding`, `image`).### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Sincronize provedores, combos e configurações entre dispositivos
-- Sincronização automática em segundo plano com tempo limite + falha rápida
-- Prefira `BASE_URL`/`CLOUD_URL` do lado do servidor em produção### Cloudflare Quick Tunnel
+### Cloud Sync
-- Disponível em**Dashboard → Endpoints**para Docker e outras implantações auto-hospedadas
-- Cria um URL `https://*.trycloudflare.com` temporário que encaminha para seu endpoint `/v1` compatível com OpenAI atual
-- Primeiro habilite a instalação do `cloudflared` somente quando necessário; depois reinicia reutilizar o mesmo binário gerenciado
-- Os Quick Tunnels não são restaurados automaticamente após um OmniRoute ou reinicialização do contêiner; reative-os no painel quando necessário
-- Os URLs do túnel são efêmeros e mudam sempre que você interrompe/inicia o túnel
-- Túneis rápidos gerenciados padrão para transporte HTTP/2 para evitar avisos de buffer QUIC UDP barulhentos em contêineres restritos
-- Defina `CLOUDFLARED_PROTOCOL=quic` ou `auto` se desejar substituir a opção de transporte gerenciado
-- Defina `CLOUDFLARED_BIN` se preferir usar um binário `cloudflared` pré-instalado em vez do download gerenciado### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Cache Semântico**— Armazena automaticamente em cache sem streaming, respostas de temperatura = 0 (ignorar com `X-OmniRoute-No-Cache: true`) -**Request Idempotency**— Desduplica solicitações em 5s por meio do cabeçalho `Idempotency-Key` ou `X-Request-Id` -**Acompanhamento de progresso**— Eventos SSE `event: progress` opcionais por meio do cabeçalho `X-OmniRoute-Progress: true`---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Acesso via**Painel → Tradutor**. Depure e visualize como o OmniRoute traduz solicitações de API entre provedores.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Modo | Finalidade |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| **Parque Infantil** | Selecione os formatos de origem/destino, cole uma solicitação e veja o resultado traduzido instantaneamente |
-| **Testador de bate-papo** | Envie mensagens de chat ao vivo através do proxy e inspecione todo o ciclo de solicitação/resposta |
-| **Banco de testes** | Execute testes em lote em múltiplas combinações de formatos para verificar a exatidão da tradução |
-| **Monitoramento ao vivo** | Assista às traduções em tempo real enquanto as solicitações fluem pelo proxy |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Casos de uso:**
+**Use cases:**
-- Depure por que uma combinação específica de cliente/provedor falha
-- Verifique se as tags de pensamento, as chamadas de ferramentas e os prompts do sistema são traduzidos corretamente
-- Compare as diferenças de formato entre os formatos OpenAI, Claude, Gemini e Responses API---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Configure via**Painel → Configurações → Roteamento**.
+Configure via **Dashboard → Settings → Routing**.
-| Estratégia | Descrição |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Preencha primeiro** | Usa contas em ordem de prioridade – a conta principal lida com todas as solicitações até ficar indisponível |
-| **Round Robin** | Percorre todas as contas com um limite fixo configurável (padrão: 3 chamadas por conta) |
-| **P2C (Poder de Duas Escolhas)** | Escolhe 2 contas aleatórias e direciona para a mais saudável — equilibra a carga com a consciência da saúde |
-| **Aleatório** | Seleciona aleatoriamente uma conta para cada solicitação usando o embaralhamento Fisher-Yates |
-| **Menos usado** | Roteia para a conta com o carimbo de data/hora `lastUsedAt` mais antigo, distribuindo o tráfego uniformemente |
-| **Custo Otimizado** | Rotas para a conta com menor valor de prioridade, otimizando para provedores de menor custo | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Para afinidade de sessão externa (por exemplo, agentes Claude Code/Codex por trás de proxies reversos), envie:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute também aceita `x_session_id` e retorna a chave de sessão efetiva em `X-OmniRoute-Session-Id`.
+If you use Nginx and send underscore-form headers, enable:
-Se você usa Nginx e envia cabeçalhos em formato de sublinhado, habilite:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Crie padrões curinga para remapear nomes de modelos:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Os curingas suportam `*` (qualquer caractere) e `?` (caractere único).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Defina cadeias de fallback globais que se aplicam a todas as solicitações:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Configure via**Painel → Configurações → Resiliência**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute implementa resiliência em nível de provedor com quatro componentes:
+OmniRoute implements provider-level resilience with four components:
-1.**Perfis de Provedores**— Configuração por provedor para:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Limite de falha (quantas falhas antes da abertura)
-- Duração do resfriamento
-- Sensibilidade de detecção de limite de taxa
-- Parâmetros de espera exponencial
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Limites de taxa editáveis**— Padrões de nível de sistema configuráveis no painel: -**Solicitações por minuto (RPM)**— Máximo de solicitações por minuto por conta -**Tempo mínimo entre solicitações**— Intervalo mínimo em milissegundos entre solicitações -**Máximo de solicitações simultâneas**— Máximo de solicitações simultâneas por conta
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Clique em**Editar**para modificar e depois em**Salvar**ou**Cancelar**. Os valores persistem por meio da API de resiliência.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Disjuntor**— Rastreia falhas por provedor e abre automaticamente o circuito quando um limite é atingido: -**FECHADO**(Saudável) — As solicitações fluem normalmente -**OPEN**— O provedor é bloqueado temporariamente após falhas repetidas -**HALF_OPEN**— Testando se o provedor se recuperou
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Políticas e identificadores bloqueados**— Mostra o status do disjuntor e identificadores bloqueados com capacidade de desbloqueio forçado.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Detecção automática de limite de taxa**— Monitora os cabeçalhos `429` e `Retry-After` para evitar proativamente atingir os limites de taxa do provedor.
-
-**Dica profissional:**Use o botão**Redefinir tudo**para limpar todos os disjuntores e resfriamentos quando um provedor se recupera de uma interrupção.---
+---
### Database Export / Import
-Gerencie backups de banco de dados em**Painel → Configurações → Sistema e armazenamento**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Ação | Descrição |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Exportar banco de dados** | Baixa o banco de dados SQLite atual como um arquivo `.sqlite` |
-| **Exportar tudo (.tar.gz)** | Baixa um arquivo de backup completo, incluindo: banco de dados, configurações, combos, conexões de provedor (sem credenciais), metadados de chave API |
-| **Importar banco de dados** | Carregue um arquivo `.sqlite` para substituir o banco de dados atual. Um backup de pré-importação é criado automaticamente, a menos que `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Validação de importação:**O arquivo importado é validado quanto à integridade (verificação de pragma SQLite), tabelas necessárias (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) e tamanho (máximo de 100 MB).
+**Use Cases:**
-**Casos de uso:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Migrar OmniRoute entre máquinas
-- Crie backups externos para recuperação de desastres
-- Compartilhe configurações entre membros da equipe (exportar tudo → compartilhar arquivo)---
+---
### Settings Dashboard
-A página de configurações está organizada em 6 guias para facilitar a navegação:
+The settings page is organized into 6 tabs for easy navigation:
-| Guia | Conteúdo |
-| -------------- | --------------------------------------------------------------------------------------------- |
-|**Geral**| Ferramentas de armazenamento do sistema, configurações de aparência, controles de tema e visibilidade da barra lateral por item |
-|**Segurança**| Configurações de login/senha, controle de acesso IP, autenticação de API para `/models` e bloqueio de provedor |
-|**Roteamento**| Estratégia de roteamento global (6 opções), aliases de modelo curinga, cadeias de fallback, padrões de combinação |
-|**Resiliência**| Perfis de provedores, limites de taxas editáveis, status de disjuntores, políticas e identificadores bloqueados |
-|**IA**| Pensando na configuração do orçamento, injeção de prompt do sistema global, estatísticas de cache de prompt |
-|**Avançado**| Configuração de proxy global (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Acesso via**Painel → Custos**.
+Access via **Dashboard → Costs**.
-| Guia | Finalidade |
-| ----------- | --------------------------------------------------------------------------------------------------- |
-|**Orçamento**| Defina limites de gastos por chave de API com orçamentos diários/semanais/mensais e rastreamento em tempo real |
-|**Preços**| Visualize e edite entradas de preços de modelo — custo por 1 mil tokens de entrada/saída por provedor |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -765,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Acompanhamento de custos:**cada solicitação registra o uso do token e calcula o custo usando a tabela de preços. Veja detalhes em**Painel → Uso**por provedor, modelo e chave de API.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute oferece suporte à transcrição de áudio por meio do endpoint compatível com OpenAI:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Provedores disponíveis:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Formatos de áudio suportados: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.---
+---
### Combo Balancing Strategies
-Configure o balanceamento por combo em**Painel → Combos → Criar/Editar → Estratégia**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Estratégia | Descrição |
-| ------------------ | --------------------------------------------------------------------------------------- |
-|**Round-Robin**| Gira pelos modelos sequencialmente |
-|**Prioridade**| Tenta sempre o primeiro modelo; recorre apenas ao erro |
-|**Aleatório**| Escolhe um modelo aleatório do combo para cada solicitação |
-|**Ponderada**| Rotas proporcionalmente com base nos pesos atribuídos por modelo |
-|**Menos usado**| Rotas para o modelo com o menor número de solicitações recentes (usa métricas combinadas) |
-|**Custo Otimizado**| Rotas para o modelo mais barato disponível (usa tabela de preços) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Os padrões de combinação global podem ser definidos em**Painel → Configurações → Roteamento → Padrões de combinação**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Acesso via**Painel → Saúde**. Visão geral da integridade do sistema em tempo real com 6 cartões:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Cartão | O que mostra |
+| Card | What It Shows |
| --------------------- | ----------------------------------------------------------- |
-|**Status do sistema**| Tempo de atividade, versão, uso de memória, diretório de dados |
-|**Provedor de Saúde**| Estado do disjuntor por fornecedor (Fechado/Aberto/Meio-aberto) |
-|**Limites de Tarifas**| Cooldowns de limite de taxa ativa por conta com tempo restante |
-|**Bloqueios ativos**| Prestadores bloqueados temporariamente pela política de lockout |
-|**Cache de Assinaturas**| Estatísticas do cache de desduplicação (chaves ativas, taxa de acertos) |
-|**Telemetria de latência**| Agregação de latência p50/p95/p99 por provedor |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Dica profissional:**a página Saúde é atualizada automaticamente a cada 10 segundos. Use a placa do disjuntor para identificar quais provedores estão enfrentando problemas.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute está disponível como um aplicativo de desktop nativo para Windows, macOS e Linux.### Instalar
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Instalar
```bash
# From the electron directory:
@@ -833,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -845,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Saída → `elétron/dist-elétron/`### Key Features
+Output → `electron/dist-electron/`
-| Recurso | Descrição |
-| ------------------------------------- | ---------------------------------------------------------------------------- | ------------------------- |
-| **Prontidão do servidor** | Pesquisa o servidor antes de mostrar a janela (sem tela em branco) |
-| **Bandeja do sistema** | Minimizar para a bandeja, alterar a porta, sair do menu da bandeja |
-| **Gerenciamento Portuário** | Alterar a porta do servidor na bandeja (reinicia automaticamente o servidor) |
-| **Política de segurança de conteúdo** | CSP restritivo por meio de cabeçalhos de sessão |
-| **Instância única** | Apenas uma instância de aplicativo pode ser executada por vez |
-| **Modo off-line** | Servidor Next.js incluído funciona sem internet | ### Environment Variables |
+### Key Features
-| Variável | Padrão | Descrição |
-| --------------------- | ------- | ---------------------------------------- |
-| `OMNIROUTE_PORT` | `20128` | Porta do servidor |
-| `OMNIROUTE_MEMORY_MB` | `512` | Limite de heap do Node.js (64–16.384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Documentação completa: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/ro/README.md b/docs/i18n/ro/README.md
index 7945e09734..6b79e40f69 100644
--- a/docs/i18n/ro/README.md
+++ b/docs/i18n/ro/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/ro/docs/USER_GUIDE.md b/docs/i18n/ro/docs/USER_GUIDE.md
index f494164822..61a07b26d5 100644
--- a/docs/i18n/ro/docs/USER_GUIDE.md
+++ b/docs/i18n/ro/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Ghid complet pentru configurarea furnizorilor, crearea combo-urilor, integrarea instrumentelor CLI și implementarea OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Prețul dintr-o privire](#-pricing-at-a-glance)
-- [Cazuri de utilizare](#-cazuri de utilizare)
-- [Configurare furnizor](#-provider-setup)
-- [Integrare CLI](#-cli-integration)
-- [Implementare](#-implementare)
-- [Modele disponibile](#-modele-disponibile)
-- [Funcții avansate](#-funcții-avansate)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 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** | DeepSeek | Plată pe utilizare | Niciuna | Raționament ieftin |
-| | Groq | Plată pe utilizare | Niciuna | Inferență ultra-rapidă |
-| | xAI (Grok) | Plată pe utilizare | Niciuna | Grok 4 raționament |
-| | Mistral | Plată pe utilizare | Niciuna | Modele găzduite de UE |
-| | Nedumerire | Plată pe utilizare | Niciuna | Căutare sporită |
-| | Împreună AI | Plată pe utilizare | Niciuna | Modele open-source |
-| | Artificii AI | Plată pe utilizare | Niciuna | Imagini Fast FLUX |
-| | Cerebre | Plată pe utilizare | Niciuna | Viteza la scara plachetei |
-| | Cohere | Plată pe utilizare | Niciuna | Comanda R+ RAG |
-| | NVIDIA NIM | Plată pe utilizare | Niciuna | Modele de întreprindere |
-| **💰 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** | Qoder | $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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Sfat profesional:**Începeți cu Gemini CLI (180K gratuit/lună) + Qoder (gratuit nelimitat) combo = cost 0 USD!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Problemă:**Cota expiră neutilizată, limitele ratei în timpul codării grele```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Problemă:**Nu-mi permit abonamente, au nevoie de codare AI fiabilă```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Problemă:**Termenele limită, nu-mi permit timpi de nefuncționare```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Problemă:**Aveți nevoie de asistent AI în aplicațiile de mesagerie, complet gratuit```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ 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!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Cea mai bună valoare:**Nivel gratuit imens! Utilizați acest lucru înainte de nivelurile plătite.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### 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`, Cheia API: `cheia dvs.`
+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` —**Sfat profesionist:**Planul de codare oferă 3× cotă la 1/7 cost! Resetați zilnic la 10:00.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Înscrieți-vă: [MiniMax](https://www.minimax.io/)
-2. Obțineți cheia API → Tabloul de bord → Adăugați cheia API
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Utilizați:**`minimax/MiniMax-M2.1` —**Sfat profesional:**Cea mai ieftină opțiune pentru context lung (1 milion de jetoane)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Abonați-vă: [Moonshot AI](https://platform.moonshot.ai/)
-2. Obțineți cheia API → Tabloul de bord → Adăugați cheia API
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Utilizați:**`kimi/kimi-latest` —**Sfat profesionist:**Fix 9 USD/lună pentru 10 milioane de jetoane = 0,90 USD/1 milion cost efectiv!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Editați `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Editați `~/.claude/config.json`:```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Editați `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Sau utilizați Dashboard:**CLI Tools → OpenClaw → Auto-config### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI încarcă automat `.env` din `~/.omniroute/.env` sau `./.env`.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-Pentru serverele cu RAM limitată, utilizați opțiunea de limită de memorie:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Creați `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,12 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-Pentru modul integrat în gazdă cu binare CLI, consultați secțiunea Docker din documentele principale.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Utilizatorii Void Linux pot împacheta și instala OmniRoute în mod nativ folosind cadrul de compilare încrucișată `xbps-src`. Acest lucru automatizează construcția independentă Node.js împreună cu legăturile native necesare `better-sqlite3`.
+### Void Linux (xbps-src)
-
-Vizualizați șablonul xbps-src```bash
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -408,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -475,80 +516,85 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Variabila | Implicit | Descriere |
-| --------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | Secret de semnare JWT (**schimbarea producției**) |
-| `PAROLA_INIȚIALĂ` | `123456` | Prima parolă de conectare |
-| `DATA_DIR` | `~/.omniroute` | Director de date (db, utilizare, jurnale) |
-| `PORT` | cadru implicit | Port de serviciu (`20128` în exemple) |
-| `HOSTNAME` | cadru implicit | Leagă gazdă (Docker este implicit `0.0.0.0`) |
-| `NODE_ENV` | implicit de rulare | Setați `producție` pentru implementare |
-| `BASE_URL` | `http://localhost:20128` | Adresa URL de bază internă pe partea serverului |
-| `CLOUD_URL` | `https://omniroute.dev` | Adresa URL de bază a punctului final de sincronizare în cloud |
-| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Secret HMAC pentru cheile API generate |
-| `REQUIRE_API_KEY` | `fals` | Aplicați cheia API Bearer pe `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `fals` | Permiteți Managerului Api să copieze chei API complete la cerere |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | cadență de reîmprospătare la nivelul serverului pentru datele din cache ale Limitelor furnizorului; Butoanele de reîmprospătare a interfeței de utilizator declanșează în continuare sincronizarea manuală |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `fals` | Dezactivați instantaneele automate SQLite înainte de scriere/import/restaurare; backup-urile manuale încă funcționează |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `fals` | Forțați cookie-ul de autentificare „Securizat” (în spatele proxy-ului invers HTTPS) |
-| `CLOUDFLARED_BIN` | dezactivat | Utilizați un binar `cloudflared` existent în loc de descărcare gestionată |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Transport pentru tuneluri rapide gestionate (`http2`, `quic` sau `auto`) |
-| `OMNIROUTE_MEMORY_MB` | `512` | Limită heap Node.js în MB |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | Numărul maxim de intrări în cache pentru prompt |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Numărul maxim de intrări semantice în cache |Pentru referința completă a variabilei de mediu, consultați [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Vedeți toate modelele disponibile
+
+View all available models
-**Cod Claude (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— GRATUIT: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**Copilot GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— 0,6 USD/1 M: `glm/glm-4,7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— 0,2 USD/1 M: `minimax/MiniMax-M2,1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— GRATUIT: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— GRATUIT: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— GRATUIT: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
-**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-raționament rapid`, `xai/grok-code-mini`
+**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Perplexitate (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**Fireworks AI (`fireworks/`)**: `fireworks/conturi/fireworks/models/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -556,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Adăugați orice ID de model oricărui furnizor fără a aștepta o actualizare a aplicației:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -564,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Sau utilizați Tabloul de bord:**Furnizori → [Furnizor] → Modele personalizate**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Note:
+Notes:
-- Furnizorii OpenRouter și OpenAI/compatibili cu Anthropic sunt gestionați numai din**Modele disponibile**. Adăugarea manuală, importarea și sincronizarea automată ajung toate în aceeași listă de modele disponibile, deci nu există o secțiune separată de modele personalizate pentru acei furnizori.
-- Secțiunea**Modele personalizate**este destinată furnizorilor care nu expun importurile gestionate de modele disponibile.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Dirijați cererile direct către un anumit furnizor cu validarea modelului:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Prefixul furnizorului este adăugat automat dacă lipsește. Modelele nepotrivite returnează `400`.### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -594,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Precedență:**Specific cheie → Specific combo → Specific furnizor → Global → Mediu.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Returnează modele grupate după furnizor cu tipuri (`chat`, `embedding`, `image`).### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Sincronizați furnizorii, combo-urile și setările pe dispozitive
-- Sincronizare automată în fundal cu timeout + fail-rapid
-- Preferați `BASE_URL`/`CLOUD_URL` pe partea de server în producție### Cloudflare Quick Tunnel
+### Cloud Sync
-- Disponibil în**Tabloul de bord → Puncte finale**pentru Docker și alte implementări găzduite de sine
-- creează o adresă URL temporară „https://\*.trycloudflare.com” care redirecționează către punctul final „/v1” compatibil cu OpenAI.
-- Activați mai întâi instalările `cloudflared` numai când este necesar; repornirile ulterioare reutilizează același binar gestionat
-- Tunelurile rapide nu sunt restaurate automat după o repornire a OmniRoute sau a containerului; reactivați-le din tabloul de bord când este necesar
-- URL-urile tunelului sunt efemere și se schimbă de fiecare dată când opriți/porniți tunelul
-- Tunelurile rapide gestionate implicit la transportul HTTP/2 pentru a evita avertismentele zgomotoase ale bufferului QUIC UDP în containerele constrânse
-- Setați `CLOUDFLARED_PROTOCOL=quic` sau `auto` dacă doriți să suprascrieți opțiunea de transport gestionat
-- Setați `CLOUDFLARED_BIN` dacă preferați să utilizați un binar `cloudflared` preinstalat în loc de descărcarea gestionată### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Semantic Cache**— Memorează automat în cache non-streaming, temperatură=0 răspunsuri (ocolire cu `X-OmniRoute-No-Cache: true`) -**Solicitare Idempotency**— Deduplică cererile în 5 secunde prin antetul `Idempotency-Key` sau `X-Request-Id` -**Urmărirea progresului**— Opt-in SSE „eveniment: progres” evenimente prin antetul „X-OmniRoute-Progress: true”---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Acces prin**Tabloul de bord → Translator**. Depanați și vizualizați modul în care OmniRoute traduce cererile API între furnizori.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Modul | Scop |
-| ------------------- | ----------------------------------------------------------------------------------------------------- |
-| **Teren de joacă** | Selectați formatele sursă/țintă, inserați o solicitare și vedeți instantaneu rezultatul tradus |
-| **Tester de chat** | Trimiteți mesaje de chat live prin proxy și inspectați întregul ciclu de solicitare/răspuns |
-| **Banc de testare** | Rulați teste în loturi în mai multe combinații de formate pentru a verifica corectitudinea traducerii |
-| **Monitor live** | Urmăriți traducerile în timp real pe măsură ce solicitările curg prin proxy |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Cazuri de utilizare:**
+**Use cases:**
-- Depanați de ce o anumită combinație client/furnizor eșuează
-- Verificați dacă etichetele de gândire, apelurile de instrumente și instrucțiunile de sistem se traduc corect
-- Comparați diferențele de format dintre formatele OpenAI, Claude, Gemini și Responses API---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Configurați prin**Tablou de bord → Setări → Rutare**.
+Configure via **Dashboard → Settings → Routing**.
-| Strategie | Descriere |
-| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Umpleți mai întâi** | Utilizează conturile în ordine de prioritate — contul principal gestionează toate solicitările până când nu sunt disponibile |
-| **Round Robin** | Parcurge toate conturile cu o limită stabilă configurabilă (implicit: 3 apeluri per cont) |
-| **P2C (Puterea a două opțiuni)** | Alege 2 conturi aleatorii și rute către cel mai sănătos — echilibrează sarcina cu conștientizarea sănătății |
-| **La întâmplare** | Selectează aleatoriu un cont pentru fiecare solicitare folosind Fisher-Yates shuffle |
-| **Cel mai puțin folosit** | Rute către contul cu cea mai veche amprentă temporală `lastUsedAt`, distribuind traficul uniform |
-| **Cost optimizat** | Rute către contul cu cea mai mică valoare de prioritate, optimizare pentru furnizorii cu cel mai mic cost | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Pentru afinitatea sesiunii externe (de exemplu, agenți Claude Code/Codex din spatele proxy-urilor inverse), trimiteți:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute acceptă, de asemenea, `x_session_id` și returnează cheia efectivă de sesiune în `X-OmniRoute-Session-Id`.
+If you use Nginx and send underscore-form headers, enable:
-Dacă utilizați Nginx și trimiteți antete pentru formulare de subliniere, activați:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Creați modele de metacara pentru a remapa numele modelelor:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Wildcards acceptă `*` (orice caractere) și `?` (un singur caracter).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Definiți lanțuri globale de rezervă care se aplică tuturor solicitărilor:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Configurați prin**Tabloul de bord → Setări → Reziliență**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute implementează rezistența la nivel de furnizor cu patru componente:
+OmniRoute implements provider-level resilience with four components:
-1.**Profiluri de furnizor**— Configurație per furnizor pentru:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Pragul de eșec (cate defecțiuni înainte de deschidere)
-- Durata de răcire
-- Sensibilitatea de detectare a limitei ratei
-- Parametrii de backoff exponenţial
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Limite de rată editabile**— Setări implicite la nivel de sistem configurabile în tabloul de bord: -**Solicitări pe minut (RPM)**— Numărul maxim de solicitări pe minut per cont -**Timp minim între solicitări**— Intervalul minim în milisecunde între solicitări -**Max. de solicitări simultane**— Maxim de solicitări simultane per cont
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Faceți clic pe**Editați**pentru a modifica, apoi pe**Salvați**sau**Anulați**. Valorile persistă prin intermediul API-ului de rezistență.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Circuit Breaker**— Urmărește defecțiunile pentru fiecare furnizor și deschide automat circuitul când este atins un prag: -**ÎNCHIS**(sănătos) — Solicitările curg normal -**DESCHIS**— Furnizorul este blocat temporar după eșecuri repetate -**HALF_OPEN**— Se testează dacă furnizorul și-a revenit
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Politici și identificatori blocați**— Afișează starea întrerupătorului și identificatorii blocați cu capacitatea de deblocare forțată.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Rate Limit Auto-Detection**— Monitorizează anteturile `429` și `Retry-After` pentru a evita în mod proactiv atingerea limitelor de rate ale furnizorului.
-
-**Sfat profesionist:**Folosiți butonul**Reset All**pentru a șterge toate întreruptoarele de circuit și perioadele de răcire atunci când un furnizor își revine după o întrerupere.---
+---
### Database Export / Import
-Gestionați copiile de rezervă ale bazei de date în**Tabloul de bord → Setări → Sistem și stocare**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Acțiune | Descriere |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Exportați baza de date** | Descarcă baza de date SQLite curentă ca fișier `.sqlite` |
-| **Exportați toate (.tar.gz)** | Descărcă o arhivă de rezervă completă, inclusiv: bază de date, setări, combinații, conexiuni la furnizor (fără acreditări), metadatele cheii API |
-| **Importă baza de date** | Încărcați un fișier `.sqlite` pentru a înlocui baza de date curentă. O copie de rezervă pre-import este creată automat, cu excepția cazului în care `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Validare import:**Fișierul importat este validat pentru integritate (verificare pragma SQLite), tabelele necesare (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) și dimensiune (maximum 100MB).
+**Use Cases:**
-**Cazuri de utilizare:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Migrați OmniRoute între mașini
-- Creați copii de rezervă externe pentru recuperarea în caz de dezastru
-- Partajați configurațiile între membrii echipei (exportați toate → partajați arhiva)---
+---
### Settings Dashboard
-Pagina de setări este organizată în 6 file pentru o navigare ușoară:
+The settings page is organized into 6 tabs for easy navigation:
-| Tab | Cuprins |
-| -------------- | ----------------------------------------------------------------------------------------------------- |
-|**General**| Instrumente de stocare a sistemului, setări de aspect, comenzi ale temei și vizibilitate pe bara laterală per articol |
-|**Securitate**| Setări de conectare/parolă, control acces IP, autentificare API pentru „/modele” și blocare furnizor |
-|**Dirutare**| Strategie globală de rutare (6 opțiuni), aliasuri de model cu wildcard, lanțuri de rezervă, valori implicite combo |
-|**Reziliență**| Profilurile furnizorilor, limitele de rată modificabile, starea întrerupătorului, politicile și identificatorii blocați |
-|**AI**| Gândire la configurația bugetului, injectarea promptă a sistemului global, statisticile cache prompte |
-|**Avansat**| Configurație globală proxy (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Acces prin**Tabloul de bord → Costuri**.
+Access via **Dashboard → Costs**.
-| Tab | Scop |
+| Tab | Purpose |
| ----------- | ---------------------------------------------------------------------------------------- |
-|**Buget**| Setați limite de cheltuieli pentru fiecare cheie API cu bugete zilnice/săptămânale/lunare și urmărire în timp real |
-|**Prețuri**| Vizualizați și editați intrările de prețuri ale modelului — cost pe 1K jetonuri de intrare/ieșire per furnizor |```bash
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -765,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Urmărirea costurilor:**Fiecare solicitare înregistrează utilizarea simbolurilor și calculează costul utilizând tabelul de prețuri. Vedeți defalcări în**Tabloul de bord → Utilizare**în funcție de furnizor, model și cheie API.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute acceptă transcrierea audio prin punctul final compatibil cu OpenAI:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Furnizori disponibili:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Formate audio acceptate: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.---
+---
### Combo Balancing Strategies
-Configurați echilibrarea per-combo în**Tabloul de bord → Combo → Creare/Editare → Strategie**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Strategie | Descriere |
+| Strategy | Description |
| ------------------ | ------------------------------------------------------------------------ |
-|**Round-Robin**| Se rotește succesiv prin modele |
-|**Prioritate**| Încearcă întotdeauna primul model; cade înapoi numai pe eroare |
-|**La întâmplare**| Alege un model aleatoriu din combo pentru fiecare cerere |
-|**Ponderat**| Rute proporționale pe baza greutăților atribuite per model |
-|**Cel mai puțin folosit**| Rute către modelul cu cele mai puține solicitări recente (folosește valori combinate) |
-|**Optimizat din punct de vedere al costurilor**| Rute către cel mai ieftin model disponibil (folosește tabelul de prețuri) |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Valorile implicite globale ale combo pot fi setate în**Tabloul de bord → Setări → Rutare → Setări implicite combo**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Acces prin**Tabloul de bord → Sănătate**. Prezentare generală a stării sistemului în timp real cu 6 carduri:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Card | Ce arată |
-| --------------------- | ---------------------------------------------------------- |
-|**Stare sistem**| Uptime, versiune, utilizare a memoriei, director de date |
-|**Sănătatea furnizorului**| Stare întrerupător pentru fiecare furnizor (Închis/Deschis/Pe jumătate deschis) |
-|**Limite de rate**| Reduceri de reducere a limitei ratei active per cont cu timpul rămas |
-|**Blocari active**| Furnizori blocați temporar de politica de blocare |
-|**Cache pentru semnături**| Statistici cache de deduplicare (chei active, rata de accesare) |
-|**Telemetrie de latență**| agregarea latenței p50/p95/p99 per furnizor |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Sfat profesional:**Pagina Sănătate se reîmprospătează automat la fiecare 10 secunde. Utilizați cardul de întrerupător pentru a identifica furnizorii care se confruntă cu probleme.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute este disponibil ca aplicație desktop nativă pentru Windows, macOS și Linux.### Instalare
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Instalare
```bash
# From the electron directory:
@@ -833,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -845,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Ieșire → `electron/dist-electron/`### Key Features
+Output → `electron/dist-electron/`
-| Caracteristica | Descriere |
-| ----------------------------------------- | ------------------------------------------------------------------ | ------------------------- |
-| **Pregătirea serverului** | Sondați serverul înainte de a afișa fereastra (fără ecran gol) |
-| **Tava de sistem** | Minimizați în tavă, schimbați portul, ieșiți din meniul tavă |
-| **Gestionarea portului** | Schimbați portul serverului din tavă (repornește automat serverul) |
-| **Politica de securitate a conținutului** | CSP restrictiv prin anteturile de sesiune |
-| **Instanță unică** | O singură instanță de aplicație poate rula o dată |
-| **Mod offline** | Serverul Next.js inclus funcționează fără internet | ### Environment Variables |
+### Key Features
-| Variabila | Implicit | Descriere |
-| --------------------- | -------- | --------------------------------- |
-| `OMNIROUTE_PORT` | `20128` | Port server |
-| `OMNIROUTE_MEMORY_MB` | `512` | Limită heap Node.js (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Documentația completă: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/ru/README.md b/docs/i18n/ru/README.md
index 8c4239c0e1..e3bc95ff63 100644
--- a/docs/i18n/ru/README.md
+++ b/docs/i18n/ru/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/ru/docs/USER_GUIDE.md b/docs/i18n/ru/docs/USER_GUIDE.md
index 34de24980d..3f6d187b85 100644
--- a/docs/i18n/ru/docs/USER_GUIDE.md
+++ b/docs/i18n/ru/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Полное руководство по настройке поставщиков, созданию комбинаций, интеграции инструментов CLI и развертыванию OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Краткий обзор цен](#-цены-краткий обзор)
-- [Случаи использования](#-сценариев использования)
-- [Настройка поставщика](#-provider-setup)
-- [Интеграция CLI](#-cli-интеграция)
-- [Развертывание](#-развертывание)
-- [Доступные модели](#-доступных-моделей)
-- [Расширенные функции](#-расширенные-функции)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 Pricing at a Glance
-| Уровень | Провайдер | Стоимость | Сброс квоты | Лучшее для |
-| ---------------- | ------------------- | ------------------------------ | ---------------------------- | -------------------------------- |
-| **💳 ПОДПИСКА** | Клод Код (Про) | 20 долларов США в месяц | 5 часов + еженедельно | Уже подписан |
-| | Кодекс (Плюс/Про) | 20–200 долларов в месяц | 5 часов + еженедельно | Пользователи OpenAI |
-| | Близнецы CLI | **БЕСПЛАТНО** | 180 тыс./мес + 1 тыс./день | Каждый! |
-| | Второй пилот GitHub | 10–19 долларов в месяц | Ежемесячно | Пользователи GitHub |
-| **🔑 КЛЮЧ API** | ДипСик | Плата за использование | Нет | Дешевое рассуждение |
-| | Грок | Плата за использование | Нет | Сверхбыстрый вывод |
-| | xAI (Грок) | Плата за использование | Нет | рассуждения Грока 4 |
-| | Мистраль | Плата за использование | Нет | Модели, размещенные в ЕС |
-| | Растерянность | Плата за использование | Нет | Расширенный поиск |
-| | Вместе ИИ | Плата за использование | Нет | Модели с открытым исходным кодом |
-| | Фейерверк ИИ | Плата за использование | Нет | Изображения Fast FLUX |
-| | Церебра | Плата за использование | Нет | Скорость пластинчатого масштаба |
-| | Согласовано | Плата за использование | Нет | Команда R+ ТРЯПКА |
-| | NVIDIA НИМ | Плата за использование | Нет | Модели предприятия |
-| **💰 ДЕШЕВО** | ГЛМ-4.7 | 0,6 долл. США/1 млн | Ежедневно в 10:00 | Резервное копирование бюджета |
-| | МиниМакс М2.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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡Совет для профессионалов:**Начните с комбинации Gemini CLI (180 000 бесплатно в месяц) + Qoder (бесплатно без ограничений) = стоимость 0 долларов США!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Проблема:**Срок действия квоты истекает, а скорость ограничена во время интенсивного кодирования.```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Проблема:**Не могу позволить себе подписку, нужно надежное кодирование с использованием искусственного интеллекта.```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Проблема:**сроки, невозможность простоя```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Проблема:**Нужен ИИ-помощник в приложениях для обмена сообщениями, совершенно бесплатно.```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**Совет для профессионалов.**Используйте Opus для сложных задач и Sonnet для скорости. OmniRoute отслеживает квоту на каждую модель!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Лучшая цена:**Огромный уровень бесплатного пользования! Используйте это перед платными уровнями.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### GLM-4.7 (Daily reset, $0.6/1M)
-1. Зарегистрируйтесь: [Zhipu AI](https://open.bigmodel.cn/)
-2. Получите ключ API из плана кодирования.
-3. Панель управления → Добавить ключ API: Поставщик: `glm`, Ключ API: `ваш-ключ`
+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` —**Совет для профессионалов:**План кодирования предлагает 3-кратную квоту за 1/7 стоимости! Сброс ежедневно в 10:00.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Зарегистрируйтесь: [MiniMax](https://www.minimax.io/)
-2. Получите ключ API → Панель управления → Добавить ключ API.
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Используйте:**`minimax/MiniMax-M2.1` —**Совет для профессионалов:**Самый дешевый вариант для длинного контекста (1 млн токенов)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Подпишитесь: [Moonshot AI](https://platform.moonshot.ai/)
-2. Получите ключ API → Панель управления → Добавить ключ API.
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Используйте:**`kimi/kimi-latest` —**Совет для профессионалов:**Фиксированная 9 долларов США в месяц за 10 миллионов токенов = эффективная стоимость 0,90 долларов США/1 миллион долларов США!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Отредактируйте `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Settings → Models → Advanced:
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Отредактируйте `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Или используйте панель инструментов:**Инструменты CLI → OpenClaw → Автонастройка.### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI автоматически загружает .env из ~/.omniroute/.env или ./.env.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-Для серверов с ограниченным объемом оперативной памяти используйте опцию ограничения памяти:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Создайте `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,13 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-Для режима интеграции с хостом с двоичными файлами CLI см. раздел Docker в основной документации.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Пользователи Void Linux могут упаковать и установить OmniRoute, используя среду кросс-компиляции xbps-src. Это автоматизирует автономную сборку Node.js вместе с необходимыми собственными привязками Better-sqlite3.
+### Void Linux (xbps-src)
-<подробности>
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
-Просмотр шаблона xbps-src```bash
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -409,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -476,80 +516,85 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Переменная | По умолчанию | Описание |
+| Variable | Default | Description |
| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | Секрет подписания JWT (**изменение в производстве**) |
-| `INITIAL_PASSWORD` | `123456` | Первый пароль для входа |
-| `DATA_DIR` | `~/.omniroute` | Каталог данных (база данных, использование, журналы) |
-| `ПОРТ` | структура по умолчанию | Сервисный порт (в примерах «20128») |
-| `ИМЯ ХОСТА` | структура по умолчанию | Привязать хост (по умолчанию в Docker установлено значение «0.0.0.0») |
-| `NODE_ENV` | по умолчанию во время выполнения | Установить `производство` для развертывания |
-| `BASE_URL` | `http://localhost:20128` | Внутренний базовый URL-адрес на стороне сервера |
-| `CLOUD_URL` | `https://omniroute.dev` | Базовый URL-адрес конечной точки облачной синхронизации |
-| `API_KEY_SECRET` | `конечная точка-прокси-api-ключ-секрет` | Секрет HMAC для сгенерированных ключей API |
-| `REQUIRE_API_KEY` | `ложь` | Принудительно использовать ключ API носителя для `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `ложь` | Разрешить Api Manager копировать полные ключи API по требованию |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Частота обновления на стороне сервера кэшированных данных о лимитах поставщика; Кнопки обновления пользовательского интерфейса по-прежнему запускают ручную синхронизацию |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `ложь` | Отключить автоматическое создание снимков SQLite перед записью/импортом/восстановлением; резервное копирование вручную все еще работает |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `ложь` | Принудительно использовать файл cookie аутентификации `Secure` (за обратным прокси-сервером HTTPS) |
-| `CLOUDFLARED_BIN` | не установлен | Использовать существующий двоичный файл «cloudflared» вместо управляемой загрузки |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Транспорт для управляемых быстрых туннелей (http2, quic или auto) |
-| `OMNIROUTE_MEMORY_MB` | `512` | Ограничение кучи Node.js в МБ |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | Максимальное количество записей в кэше подсказок |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Максимальное количество записей семантического кэша |Полную ссылку на переменную среды см. в [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-<подробности>
-Просмотреть все доступные модели
+
+View all available models
-**Код Клода (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Кодекс (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— БЕСПЛАТНО: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— 0,6 долл. США/1 миллион: `glm/glm-4.7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— 0,2 долл. США/1 миллион: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— БЕСПЛАТНО: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— БЕСПЛАТНО: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Киро (`kr/`)**— БЕСПЛАТНО: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
-**Грок (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
+**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
-**Мистраль (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Недоумение (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**Вместе AI (`вместе/`)**: `вместе/мета-лама/Ллама-3.3-70B-Instruct-Turbo`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**ИИ фейерверков (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**Церебрас (`cerebras/`)**: `cerebras/llama-3.3-70b`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -557,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Добавьте любой идентификатор модели к любому поставщику, не дожидаясь обновления приложения:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -565,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Или используйте панель управления:**Поставщики → [Поставщик] → Пользовательские модели**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Примечания:
+Notes:
-- Поставщики OpenRouter и OpenAI/Anthropic-совместимые управляются только из**Доступных моделей**. Добавление, импорт и автоматическая синхронизация вручную попадают в один и тот же список доступных моделей, поэтому для этих поставщиков нет отдельного раздела «Пользовательские модели».
- – Раздел**Пользовательские модели**предназначен для поставщиков, которые не предоставляют управляемый импорт доступных моделей.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Направляйте запросы непосредственно к конкретному поставщику с проверкой модели:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Префикс провайдера добавляется автоматически, если он отсутствует. Несовпадающие модели возвращают «400».### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -595,169 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Приоритет:**Зависит от ключа → Зависит от комбинации → Зависит от поставщика → Глобальный → Окружающая среда.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Возвращает модели, сгруппированные по поставщикам с типами («чат», «встраивание», «изображение»).### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Синхронизация поставщиков, комбинаций и настроек между устройствами.
-- Автоматическая фоновая синхронизация с таймаутом + отказоустойчивость
-- Предпочитайте серверную версию `BASE_URL`/`CLOUD_URL` в рабочей среде.### Cloudflare Quick Tunnel
+### Cloud Sync
-- Доступно в разделе**Панель управления → Конечные точки**для Docker и других локальных развертываний.
-- Создает временный URL-адрес https://\*.trycloudflare.com, который перенаправляет вас на текущую конечную точку, совместимую с OpenAI, /v1.
-- Первое включение устанавливает Cloudflared только при необходимости; последующие перезапуски повторно используют тот же управляемый двоичный файл
- — Быстрые туннели не восстанавливаются автоматически после перезапуска OmniRoute или контейнера; при необходимости повторно включите их с панели управления
-- URL-адреса туннелей являются эфемерными и меняются каждый раз, когда вы останавливаете/запускаете туннель.
-- Управляемые быстрые туннели по умолчанию используют транспорт HTTP/2, чтобы избежать шумных предупреждений буфера QUIC UDP в ограниченных контейнерах.
-- Установите `CLOUDFLARED_PROTOCOL=quic` или `auto`, если вы хотите переопределить выбор управляемого транспорта.
-- Установите `CLOUDFLARED_BIN`, если вы предпочитаете использовать предустановленный двоичный файл `cloudflared` вместо управляемой загрузки.### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Семантический кеш**— автоматически кэширует непоточные ответы, температура = 0 (обход с помощью `X-OmniRoute-No-Cache: true`) -**Request Idempotency**— дедупликация запросов в течение 5 секунд через заголовок Idempotency-Key или X-Request-Id. -**Отслеживание прогресса** — включите события SSE `event: Progress` через заголовок `X-OmniRoute-Progress: true`.---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Доступ через**Личный кабинет → Переводчик**. Отладка и визуализация того, как OmniRoute преобразует запросы API между поставщиками.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Режим | Цель |
-| ----------------------- | -------------------------------------------------------------------------------------------------- |
-| **Детская площадка** | Выберите исходный/целевой формат, вставьте запрос и мгновенно просмотрите переведенный результат |
-| **Тестер чата** | Отправляйте сообщения в чате через прокси и проверяйте полный цикл запросов/ответов |
-| **Испытательный стенд** | Запустите пакетные тесты для нескольких комбинаций форматов, чтобы проверить правильность перевода |
-| **Живой монитор** | Наблюдайте за переводами в реальном времени, пока запросы проходят через прокси |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Случаи использования:**
+**Use cases:**
-- Отладка причины сбоя конкретной комбинации клиента/провайдера.
-- Убедитесь, что теги мышления, вызовы инструментов и системные подсказки переводятся правильно.
-- Сравните различия форматов между форматами API OpenAI, Claude, Gemini и Responses.---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Настройте через**Панель управления → Настройки → Маршрутизация**.
+Configure via **Dashboard → Settings → Routing**.
-| Стратегия | Описание |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Сначала заполните** | Использует учетные записи в порядке приоритета — основная учетная запись обрабатывает все запросы, пока они не станут недоступны |
-| **Круговая система** | Циклически перебирает все учетные записи с настраиваемым фиксированным лимитом (по умолчанию: 3 вызова на учетную запись) |
-| **P2C (Сила двух вариантов)** | Выбирает 2 случайных аккаунта и направляется к более здоровому — балансирует нагрузку с осознанием здоровья |
-| **Случайный** | Случайным образом выбирает учетную запись для каждого запроса, используя перемешивание Фишера-Йейтса |
-| **Наименее используемый** | Маршруты к учетной записи с самой старой отметкой времени `lastUsedAt`, равномерно распределяя трафик |
-| **Оптимизирована стоимость** | Маршруты к учетной записи с наименьшим значением приоритета, оптимизация для поставщиков с наименьшими затратами | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Для привязки внешнего сеанса (например, агенты Claude Code/Codex за обратными прокси-серверами) отправьте:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute также принимает x_session_id и возвращает эффективный ключ сеанса в X-OmniRoute-Session-Id.
+If you use Nginx and send underscore-form headers, enable:
-Если вы используете Nginx и отправляете заголовки формы подчеркивания, включите:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Создайте шаблоны подстановочных знаков для переназначения имен моделей:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Подстановочные знаки поддерживают `*` (любые символы) и `?` (один символ).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Определите глобальные резервные цепочки, которые применяются ко всем запросам:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Настройте через**Панель управления → Настройки → Устойчивость**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute реализует устойчивость на уровне поставщика с помощью четырех компонентов:
+OmniRoute implements provider-level resilience with four components:
-1.**Профили поставщиков**— конфигурация каждого поставщика для:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Порог отказа (сколько отказов до открытия)
-- Продолжительность перезарядки
-- Чувствительность определения ограничения скорости
-- Параметры экспоненциальной отсрочки
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Редактируемые ограничения скорости**— настройки по умолчанию на уровне системы, которые можно настроить на панели управления: -**Запросов в минуту (RPM)**— максимальное количество запросов в минуту на аккаунт. -**Min Time Between Requests**— Минимальный промежуток в миллисекундах между запросами. -**Максимальное количество одновременных запросов**— максимальное количество одновременных запросов на одну учетную запись.
- – Нажмите**Изменить**, чтобы изменить, затем**Сохранить**или**Отменить**. Значения сохраняются через API устойчивости.
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
- 3.**Прерыватель цепи**— отслеживает сбои каждого провайдера и автоматически размыкает цепь при достижении порогового значения: -**ЗАКРЫТО**(Исправно) — запросы выполняются нормально. -**OPEN**— Провайдер временно заблокирован после повторных сбоев. -**HALF_OPEN**— Проверка восстановления провайдера
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 4.**Политики и заблокированные идентификаторы**— отображает состояние автоматического выключателя и заблокированные идентификаторы с возможностью принудительной разблокировки.
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 5.**Автоматическое определение ограничения скорости** — отслеживает заголовки `429` и `Retry-After`, чтобы заранее избежать превышения ограничений скорости провайдера.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
-**Совет для профессионалов.**Используйте кнопку**Сбросить все**, чтобы сбросить все автоматические выключатели и время восстановления, когда поставщик услуг восстанавливается после сбоя.---
+---
### Database Export / Import
-Управляйте резервными копиями базы данных в**Панель управления → Настройки → Система и хранилище**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Действие | Описание |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
-| **Экспорт базы данных** | Загружает текущую базу данных SQLite в виде файла `.sqlite` |
-| **Экспортировать все (.tar.gz)** | Загружает полный архив резервных копий, включая: базу данных, настройки, комбинации, подключения к провайдерам (без учетных данных), метаданные ключей API |
-| **Импорт базы данных** | Загрузите файл `.sqlite`, чтобы заменить текущую базу данных. Резервная копия перед импортом создается автоматически, если `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Проверка импорта.**Импортированный файл проверяется на целостность (проверка прагмы SQLite), наличие необходимых таблиц («provider_connections», «provider_nodes», «combos», «api_keys») и размера (максимум 100 МБ).
+**Use Cases:**
-**Примеры использования:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Миграция OmniRoute между компьютерами
-- Создание внешних резервных копий для аварийного восстановления.
-- Делитесь конфигурациями между членами команды (экспортировать все → поделиться архивом)---
+---
### Settings Dashboard
-Страница настроек разделена на 6 вкладок для удобной навигации:
+The settings page is organized into 6 tabs for easy navigation:
-| Вкладка | Содержание |
-| -------------- | --------------------------------------------------------------------------------------------- |
-|**Общие**| Инструменты системного хранения, настройки внешнего вида, элементы управления темами и видимость боковой панели для каждого элемента |
-|**Безопасность**| Настройки логина/пароля, контроль доступа по IP, аутентификация API для `/models` и блокировка провайдера |
-|**Маршрутизация**| Глобальная стратегия маршрутизации (6 вариантов), псевдонимы моделей с подстановочными знаками, резервные цепочки, комбинированные значения по умолчанию |
-|**Устойчивость**| Профили провайдеров, редактируемые ограничения скорости, статус автоматического выключателя, политики и заблокированные идентификаторы |
-|**ИИ**| Обдумывание конфигурации бюджета, глобальная системная инъекция подсказок, статистика кэша подсказок |
-|**Расширенный**| Глобальная конфигурация прокси (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Доступ через**Личный кабинет → Расходы**.
+Access via **Dashboard → Costs**.
-| Вкладка | Цель |
+| Tab | Purpose |
| ----------- | ---------------------------------------------------------------------------------------- |
-|**Бюджет**| Установите лимиты расходов на ключ API с ежедневными/еженедельными/месячными бюджетами и отслеживанием в реальном времени |
-|**Цены**| Просмотр и редактирование записей цен модели — стоимость за 1 тыс. токенов ввода/вывода на одного поставщика |```bash
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -765,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Отслеживание затрат.**Каждый запрос регистрирует использование токенов и рассчитывает стоимость с использованием таблицы цен. Просмотрите разбивку в**Панель управления → Использование**по поставщикам, моделям и ключам API.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute поддерживает транскрипцию звука через конечную точку, совместимую с OpenAI:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Доступные провайдеры:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Поддерживаемые аудиоформаты: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.---
+---
### Combo Balancing Strategies
-Настройте балансировку для каждой комбинации в**Панель управления → Комбо → Создать/Редактировать → Стратегия**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Стратегия | Описание |
-| ------------------ | -------------------------------------------------------- |
-|**Круговой**| Последовательное переключение моделей |
-|**Приоритет**| Всегда пробует первую модель; возвращается только в случае ошибки |
-|**Случайный**| Выбирает случайную модель из комбинации для каждого запроса |
-|**Взвешенный**| Маршруты пропорциональны на основе назначенных весов для каждой модели |
-|**Наименее используемый**| Маршруты к модели с наименьшим количеством недавних запросов (использует комбинированные метрики) |
-|**Оптимизированная стоимость**| Маршруты к самой дешевой доступной модели (используется таблица цен) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Глобальные настройки комбо по умолчанию можно установить в**Панель управления → Настройки → Маршрутизация → Параметры комбо по умолчанию**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Доступ через**Панель управления → Здоровье**. Обзор состояния системы в реальном времени с 6 картами:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Карта | Что это показывает |
-| --------------------- | ------------------------------------------- |
-|**Состояние системы**| Время работы, версия, использование памяти, каталог данных |
-|**Здоровье поставщика услуг**| Состояние автоматического выключателя каждого поставщика (Закрыто/Открыто/Полуоткрыто) |
-|**Ограничения ставок**| Время восстановления активного лимита скорости на аккаунт с оставшимся временем |
-|**Активные блокировки**| Провайдеры временно заблокированы политикой блокировки |
-|**Кэш подписей**| Статистика кэша дедупликации (активные ключи, частота попаданий) |
-|**Телеметрия с задержкой**| Агрегация задержек p50/p95/p99 для каждого провайдера |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Совет для профессионалов.**Страница «Здоровье» автоматически обновляется каждые 10 секунд. Используйте карту автоматического выключателя, чтобы определить, у каких поставщиков возникли проблемы.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute доступен как собственное настольное приложение для Windows, macOS и Linux.### Установить
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Установить
```bash
# From the electron directory:
@@ -833,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -845,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Вывод → `электрон/дист-электрон/`### Key Features
+Output → `electron/dist-electron/`
-| Особенность | Описание |
-| ---------------------------------- | ----------------------------------------------------------------- | ------------------------- |
-| **Готовность сервера** | Опрос сервера перед отображением окна (без пустого экрана) |
-| **Системный лоток** | Свернуть в трей, изменить порт, выйти из меню трея |
-| **Управление портом** | Изменить порт сервера из трея (автоматический перезапуск сервера) |
-| **Политика безопасности контента** | Ограничительный CSP через заголовки сеансов |
-| **Единичный экземпляр** | Одновременно может работать только один экземпляр приложения |
-| **Офлайн-режим** | Входящий в комплект сервер Next.js работает без Интернета | ### Environment Variables |
+### Key Features
-| Переменная | По умолчанию | Описание |
-| --------------------- | ------------ | -------------------------------------- |
-| `OMNIROUTE_PORT` | `20128` | Порт сервера |
-| `OMNIROUTE_MEMORY_MB` | `512` | Ограничение кучи Node.js (64–16384 МБ) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Полная документация: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/sk/README.md b/docs/i18n/sk/README.md
index ef733442cf..124d68c6eb 100644
--- a/docs/i18n/sk/README.md
+++ b/docs/i18n/sk/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/sk/docs/USER_GUIDE.md b/docs/i18n/sk/docs/USER_GUIDE.md
index 1b3c1a588f..343abba94b 100644
--- a/docs/i18n/sk/docs/USER_GUIDE.md
+++ b/docs/i18n/sk/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Kompletný sprievodca pre konfiguráciu poskytovateľov, vytváranie komb, integráciu nástrojov CLI a nasadenie OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Prehľad cien](#-pricing-a-gance)
-- [prípady použitia](#-prípadov použitia)
-- [Nastavenie poskytovateľa](#-provider-setup)
-- [Integrácia CLI](#-cli-integrácia)
-- [Nasadenie](#-nasadenie)
-- [Dostupné modely](#-dostupných-modelov)
-- [Pokročilé funkcie](#-pokročilých-funkcií)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 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** | DeepSeek | Platba za použitie | Žiadne | Lacné uvažovanie |
-| | Groq | Platba za použitie | Žiadne | Ultra-rýchle odvodenie |
-| | xAI (Grok) | Platba za použitie | Žiadne | Grok 4 zdôvodnenie |
-| | Mistral | Platba za použitie | Žiadne | Modely hostené v EÚ |
-| | Zmätok | Platba za použitie | Žiadne | Rozšírené vyhľadávanie |
-| | Spolu AI | Platba za použitie | Žiadne | Modely s otvoreným zdrojom |
-| | Ohňostroje AI | Platba za použitie | Žiadne | Fast FLUX obrázky |
-| | Cerebras | Platba za použitie | Žiadne | Rýchlosť plátkovej stupnice |
-| | Cohere | Platba za použitie | Žiadne | Príkaz R+ RAG |
-| | NVIDIA NIM | Platba za použitie | Žiadne | Podnikové modely |
-| **💰 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** | Qoder | 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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Tip pre profesionálov:**Začnite s Gemini CLI (180 000 zadarmo/mesiac) + kombinácia Qoder (neobmedzene zadarmo) = cena 0 $!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Problém:**Platnosť kvóty vyprší nevyužitá, obmedzenia sadzieb počas náročného kódovania```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Problém:**Nemôžem si dovoliť predplatné, potrebujem spoľahlivé kódovanie AI```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Problém:**Termíny, nemôžem si dovoliť prestoje```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Problém:**Potrebujete asistenta AI v aplikáciách na odosielanie správ, úplne zadarmo```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ 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!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Najlepšia hodnota:**Obrovská bezplatná úroveň! Použite to pred platenými úrovňami.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### 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. Dashboard → Pridať kľúč API: Poskytovateľ: `glm`, Kľúč API: `váš kľúč`
+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` —**Tip pre profesionálov:**Plán kódovania ponúka 3× kvótu za 1/7 cenu! Resetovať denne o 10:00.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Zaregistrujte sa: [MiniMax](https://www.minimax.io/)
-2. Získať kľúč API → Dashboard → Pridať kľúč API
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Použitie:**`minimax/MiniMax-M2.1` —**Tip pre profesionálov:**Najlacnejšia možnosť pre dlhý kontext (1 milión tokenov)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Prihláste sa na odber: [Moonshot AI](https://platform.moonshot.ai/)
-2. Získať kľúč API → Dashboard → Pridať kľúč API
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Použitie:**`kimi/kimi-najnovšie` —**Tip pre profesionálov:**Pevné 9 $/mesiac za 10 miliónov tokenov = 0,90 $/1 milión efektívnych nákladov!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Upravte `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Upravte `~/.claude/config.json`:```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Upravte `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Alebo použite Dashboard:**Nástroje CLI → OpenClaw → Automatická konfigurácia### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI automaticky načítava `.env` z `~/.omniroute/.env` alebo `./.env`.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-Pre servery s obmedzenou pamäťou RAM použite možnosť obmedzenia pamäte:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Vytvorte súbor `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,12 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-Informácie o režime integrovanom s hostiteľom s binárnymi súbormi CLI nájdete v časti Docker v hlavných dokumentoch.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Používatelia Void Linuxu môžu zabaliť a nainštalovať OmniRoute natívne pomocou rámca krížovej kompilácie `xbps-src`. Toto automatizuje samostatné zostavenie Node.js spolu s požadovanými natívnymi väzbami „better-sqlite3“.
+### Void Linux (xbps-src)
-
-Zobraziť šablónu xbps-src```bash
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -408,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -475,80 +516,85 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Premenná | Predvolené | Popis |
-| ---------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | Tajomstvo podpisu JWT (**zmena vo výrobe**) |
-| `ÚVODNÉ_HESLO` | "123456" | Prvé prihlasovacie heslo |
-| "DATA_DIR" | `~/.omniroute` | Adresár údajov (db, využitie, protokoly) |
-| "PORT" | štandardný rámec | Port služby (v príkladoch `20128`) |
-| `HOSTNAME` | štandardný rámec | Zviazať hostiteľa (predvolená hodnota Dockera je `0.0.0.0`) |
-| `NODE_ENV` | runtime default | Nastaviť `produkciu` pre nasadenie |
-| "BASE_URL" | `http://localhost:20128` | Interná základná adresa URL na strane servera |
-| `CLOUD_URL` | `https://omniroute.dev` | Základná adresa URL koncového bodu synchronizácie v cloude |
-| `API_KEY_SECRET` | "endpoint-proxy-api-key-secret" | Tajný kľúč HMAC pre vygenerované kľúče API |
-| `REQUIRE_API_KEY` | "nepravda" | Vynútiť kľúč rozhrania Bearer API na `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | "nepravda" | Povoliť Správcovi API kopírovať úplné kľúče API na požiadanie |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | "70" | Kadencia obnovovania na strane servera pre údaje limitov poskytovateľa uložené vo vyrovnávacej pamäti; Tlačidlá obnovenia používateľského rozhrania stále spúšťajú manuálnu synchronizáciu |
-| `DISABLE_SQLITE_AUTO_BACKUP` | "nepravda" | Zakázať automatické snímky SQLite pred zápisom/importom/obnovením; manuálne zálohovanie stále funguje |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| „AUTH_COOKIE_SECURE“ | "nepravda" | Vynútiť „Secure“ auth cookie (za HTTPS reverzným proxy serverom) |
-| `CLOUDFLARED_BIN` | deaktivovaný | Namiesto riadeného sťahovania použite existujúci binárny súbor „cloudflared“ |
-| `CLOUDFLARED_PROTOCOL` | "http2" | Transport pre spravované rýchle tunely (`http2`, `quic` alebo `auto`) |
-| `OMNIROUTE_MEMORY_MB` | "512" | Limit haldy Node.js v MB |
-| "PROMPT_CACHE_MAX_SIZE" | "50" | Maximálne rýchle položky cache |
-| `SEMANTIC_CACHE_MAX_SIZE` | "100" | Maximálny počet záznamov sémantickej vyrovnávacej pamäte |Úplný odkaz na premenné prostredia nájdete v [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Zobraziť všetky dostupné modely
+
+View all available models
-**Claude Code (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— ZDARMA: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4,5-sonnet`
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**– 0,6 USD/1 milión: `glm/glm-4,7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**– 0,2 USD/1 milión: `minimax/MiniMax-M2,1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**– ZDARMA: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— ZDARMA: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— ZDARMA: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
-**Groq (`groq/`)**: `groq/lama-3.3-70b-versatile`, `groq/lama-4-maverick-17b-128e-instruct`
+**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Zložitosť (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**Together AI (`together/`)**: `together/meta-lama/Llama-3.3-70B-Instruct-Turbo`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**Umelá inteligencia ohňostrojov (`ohňostroj/`)**: `ohňostroje/účty/ohňostroje/modely/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**Cerebras (`cerebras/`)**: `cerebras/lama-3.3-70b`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -556,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Pridajte akékoľvek ID modelu k akémukoľvek poskytovateľovi bez čakania na aktualizáciu aplikácie:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -564,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Alebo použite Dashboard:**Poskytovatelia → [Poskytovateľ] → Vlastné modely**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Poznámky:
+Notes:
-- OpenRouter a poskytovatelia kompatibilní s OpenAI/Anthropic sú spravovaní iba z**dostupných modelov**. Manuálne pridávanie, import a automatická synchronizácia všetkých pozemkov v rovnakom zozname dostupných modelov, takže pre týchto poskytovateľov neexistuje samostatná sekcia vlastných modelov.
- – Sekcia**Vlastné modely**je určená pre poskytovateľov, ktorí nezverejňujú importy spravovaných dostupných modelov.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Smerujte požiadavky priamo ku konkrétnemu poskytovateľovi s overením modelu:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Ak chýba predpona poskytovateľa, automaticky sa pridá. Nezhodné modely vrátia hodnotu „400“.### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -594,171 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Prednosť:**Špecifické pre kľúč → Špecifické pre kombináciu → Špecifické pre poskytovateľa → Globálne → Prostredie.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Vráti modely zoskupené podľa poskytovateľa s typmi („chat“, „vkladanie“, „obrázok“).### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Synchronizujte poskytovateľov, kombinácie a nastavenia medzi zariadeniami
-- Automatická synchronizácia na pozadí s časovým limitom + rýchle zlyhanie
-- V produkcii uprednostňujte `BASE_URL`/`CLOUD_URL` na strane servera### Cloudflare Quick Tunnel
+### Cloud Sync
-- Dostupné v**Dashboard → Endpoints**pre Docker a ďalšie nasadenia s vlastným hosťovaním
-- Vytvorí dočasnú adresu URL `https://*.trycloudflare.com`, ktorá prepošle váš aktuálny koncový bod `/v1` kompatibilný s OpenAI
-- Najprv povoľte inštaláciu „cloudflared“ iba v prípade potreby; neskoršie reštarty znova použijú rovnaký spravovaný binárny súbor
-- Rýchle tunely sa po reštarte OmniRoute alebo kontajnera automaticky neobnovia; v prípade potreby ich znova povoľte z palubnej dosky
-- Adresy URL tunelov sú pominuteľné a menia sa pri každom zastavení/spustení tunela
-- Spravované rýchle tunely predvolene používajú prenos HTTP/2, aby sa predišlo hlučným upozorneniam vyrovnávacej pamäte QUIC UDP v obmedzených kontajneroch
-- Ak chcete prepísať výber spravovaného prenosu, nastavte `CLOUDFLARED_PROTOCOL=quic` alebo `auto`
-- Nastavte `CLOUDFLARED_BIN`, ak uprednostňujete použitie predinštalovaného binárneho súboru `cloudflared` namiesto spravovaného sťahovania### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
-–**Sémantická vyrovnávacia pamäť**– Automatické ukladanie do vyrovnávacej pamäte bez streamovania, teplota = 0 odoziev (obíďte sa pomocou „X-OmniRoute-No-Cache: true“)
-–**Request Idempotency**– Deduplikuje požiadavky do 5 sekúnd prostredníctvom hlavičky „Idempotency-Key“ alebo „X-Request-Id“ -**Sledovanie pokroku**– Prihláste sa do udalostí SSE `event: progress` cez hlavičku `X-OmniRoute-Progress: true`---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Prístup cez**Dashboard → Translator**. Laďte a vizualizujte, ako OmniRoute prekladá požiadavky API medzi poskytovateľmi.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Režim | Účel |
-| --------------------- | ------------------------------------------------------------------------------------------ |
-| **Ihrisko** | Vyberte zdrojové/cieľové formáty, vložte požiadavku a okamžite si pozrite preložený výstup |
-| **Tester chatu** | Posielajte správy živého chatu cez proxy a skontrolujte celý cyklus žiadostí/odpovedí |
-| **Testovacia lavica** | Spustite dávkové testy vo viacerých kombináciách formátov na overenie správnosti prekladu |
-| **Živý monitor** | Sledujte preklady v reálnom čase, keď požiadavky prechádzajú cez server proxy |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Prípady použitia:**
+**Use cases:**
-- Odlaďte, prečo konkrétna kombinácia klient/poskytovateľ zlyhá
-- Overte, či sa značky myslenia, volania nástrojov a systémové výzvy prekladajú správne
-- Porovnajte rozdiely medzi formátmi OpenAI, Claude, Gemini a Responses API---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Konfigurujte cez**Dashboard → Nastavenia → Smerovanie**.
+Configure via **Dashboard → Settings → Routing**.
-| Stratégia | Popis |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------- |
-| **Vyplňte ako prvé** | Používa účty v poradí podľa priority – primárny účet spracováva všetky požiadavky, kým nie je dostupný |
-| **Round Robin** | Prechádza cez všetky účty s konfigurovateľným fixným limitom (predvolené: 3 hovory na účet) |
-| **P2C (sila dvoch možností)** | Vyberie 2 náhodné účty a cesty k zdravšiemu — vyrovnáva záťaž s uvedomením si zdravia |
-| **Náhodné** | Náhodne vyberie účet pre každú požiadavku pomocou Fisher-Yates shuffle |
-| **Najmenej používané** | Smeruje na účet s najstaršou časovou pečiatkou `lastUsedAt`, rovnomerne rozdeľuje návštevnosť |
-| **Costovo optimalizované** | Smeruje na účet s najnižšou prioritou, optimalizácia pre poskytovateľov s najnižšou cenou | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Pre externú príbuznosť relácie (napríklad agenti Claude Code/Codex za reverznými proxy servermi) odošlite:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute tiež akceptuje `x_session_id` a vráti efektívny kľúč relácie v `X-OmniRoute-Session-Id`.
+If you use Nginx and send underscore-form headers, enable:
-Ak používate Nginx a odosielate hlavičky formulárov podčiarknutia, povoľte:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Vytvorte vzory zástupných znakov na premapovanie názvov modelov:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Zástupné znaky podporujú `*` (ľubovoľné znaky) a `?` (jeden znak).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Definujte globálne záložné reťazce, ktoré platia pre všetky požiadavky:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Konfigurujte cez**Dashboard → Nastavenia → Odolnosť**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute implementuje odolnosť na úrovni poskytovateľa so štyrmi komponentmi:
+OmniRoute implements provider-level resilience with four components:
-1.**Profily poskytovateľa**— Konfigurácia podľa jednotlivých poskytovateľov pre:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Prah zlyhania (koľko porúch pred otvorením)
-- Trvanie chladenia
-- Citlivosť detekcie limitu rýchlosti
-- Exponenciálne parametre backoff
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Upraviteľné limity rýchlosti**— Predvolené nastavenia na úrovni systému konfigurovateľné na paneli: -**Požiadavky za minútu (RPM)**– Maximálny počet žiadostí za minútu na účet -**Min Time Between Requests**– Minimálna medzera v milisekundách medzi požiadavkami -**Max Concurrent Requests**– Maximálny počet simultánnych požiadaviek na účet
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Kliknite na**Upraviť**a upravte, potom na**Uložiť**alebo**Zrušiť**. Hodnoty pretrvávajú prostredníctvom rozhrania API odolnosti.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Circuit Breaker**– Sleduje zlyhania podľa poskytovateľa a automaticky otvára okruh, keď sa dosiahne prah: -**ZATVORENÉ**(zdravé) – požiadavky prebiehajú normálne -**OPEN**— Poskytovateľ je po opakovaných zlyhaniach dočasne zablokovaný -**HALF_OPEN**– Testuje sa, či sa poskytovateľ zotavil
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Policies & Locked Identifiers**– Zobrazuje stav ističa a uzamknuté identifikátory s možnosťou vynútenia odomknutia.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Automatická detekcia limitu rýchlosti**— Monitoruje hlavičky `429` a `Retry-After`, aby sa proaktívne vyhlo prekročeniu limitov sadzby poskytovateľa.
-
-**Tip pre profesionálov:**Použite tlačidlo**Reset All**na vymazanie všetkých ističov a chladenia, keď sa poskytovateľ zotaví z výpadku.---
+---
### Database Export / Import
-Spravujte zálohy databázy v**Dashboard → Nastavenia → Systém a úložisko**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Akcia | Popis |
-| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Exportovať databázu** | Stiahne aktuálnu databázu SQLite ako súbor `.sqlite` |
-| **Exportovať všetko (.tar.gz)** | Stiahne celý záložný archív vrátane: databázy, nastavení, kombinácií, pripojení poskytovateľa (bez poverení), metadát kľúča API |
-| **Importovať databázu** | Ak chcete nahradiť aktuálnu databázu, nahrajte súbor `.sqlite`. Predimportná záloha sa vytvorí automaticky, pokiaľ `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Overenie importu:**Overí sa integrita importovaného súboru (kontrola SQLite pragma), požadované tabuľky (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) a veľkosť (max 100 MB).
+**Use Cases:**
-**Prípady použitia:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Migrujte OmniRoute medzi strojmi
-- Vytvorte externé zálohy na obnovu po havárii
-- Zdieľanie konfigurácií medzi členmi tímu (exportovať všetko → zdieľať archív)---
+---
### Settings Dashboard
-Stránka nastavení je usporiadaná do 6 kariet pre jednoduchú navigáciu:
+The settings page is organized into 6 tabs for easy navigation:
-| Tab | Obsah |
-| --------------- | --------------------------------------------------------------------------------------------- |
-|**Všeobecné**| Nástroje systémového úložiska, nastavenia vzhľadu, ovládacie prvky tém a viditeľnosť bočného panela pre jednotlivé položky |
-|**Bezpečnosť**| Nastavenia prihlasovacieho mena/hesla, kontrola prístupu IP, overenie API pre `/modely` a blokovanie poskytovateľa |
-|**Smerovanie**| Globálna stratégia smerovania (6 možností), aliasy modelu so zástupnými znakmi, záložné reťazce, predvolené nastavenia komba |
-|**Odolnosť**| Profily poskytovateľov, upraviteľné limity sadzieb, stav ističa, zásady a zamknuté identifikátory |
-|**AI**| Konfigurácia rozpočtu myslenia, rýchle vloženie globálneho systému, rýchle štatistiky vyrovnávacej pamäte |
-|**Pokročilé**| Globálna konfigurácia proxy (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Prístup cez**Dashboard → Náklady**.
+Access via **Dashboard → Costs**.
-| Tab | Účel |
+| Tab | Purpose |
| ----------- | ---------------------------------------------------------------------------------------- |
-|**Rozpočet**| Nastavte limity výdavkov na kľúč API s dennými/týždennými/mesačnými rozpočtami a sledovaním v reálnom čase |
-|**Ceny**| Zobrazenie a úprava položiek cien modelu – cena za 1 000 vstupných/výstupných tokenov na poskytovateľa |```bash
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -766,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Sledovanie nákladov:**Každá požiadavka zaznamenáva použitie tokenu a vypočítava náklady pomocou cenovej tabuľky. Pozrite si rozpisy v**Dashboard → Použitie**podľa poskytovateľa, modelu a kľúča API.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute podporuje prepis zvuku cez koncový bod kompatibilný s OpenAI:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Dostupní poskytovatelia:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Podporované zvukové formáty: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.---
+---
### Combo Balancing Strategies
-Nakonfigurujte vyváženie jednotlivých kombinácií v**Dashboard → Combos → Create/Edit → Strategy**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Stratégia | Popis |
-| ------------------- | ------------------------------------------------------------------------ |
-|**Round-Robin**| Postupne rotuje medzi modelmi |
-|**Priorita**| Vždy vyskúšajte prvý model; vracia sa len pri chybe |
-|**Náhodné**| Vyberie náhodný model z kombinácie pre každú požiadavku |
-|**Vážený**| Trasy proporcionálne na základe pridelených hmotností na model |
-|**Najmenej používané**| Smeruje k modelu s najmenším počtom nedávnych požiadaviek (používa kombinovanú metriku) |
-|**Nákladovo optimalizované**| Trasy k najlacnejšiemu dostupnému modelu (používa cenovú tabuľku) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Globálne predvolené nastavenia pre kombináciu je možné nastaviť v**Dashboard → Settings → Routing → Combo Defaults**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Prístup cez**Dashboard → Health**. Prehľad stavu systému v reálnom čase so 6 kartami:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Karta | Čo ukazuje |
-| ---------------------- | ----------------------------------------------------------- |
-|**Stav systému**| Uptime, verzia, využitie pamäte, dátový adresár |
-|**Zdravie poskytovateľa**| Stav ističa podľa poskytovateľa (zatvorené/otvorené/polootvorené) |
-|**Obmedzenia sadzieb**| Aktívne zníženia rýchlosti limitu na účet so zostávajúcim časom |
-|**Aktívne blokovania**| Poskytovatelia dočasne zablokovaní politikou uzamknutia |
-|**Vyrovnávacia pamäť podpisov**| Štatistiky vyrovnávacej pamäte deduplikácie (aktívne kľúče, počet prístupov) |
-|**Telemetria latencie**| p50/p95/p99 agregácia latencie podľa poskytovateľa |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Tip pre profesionálov:**Stránka Zdravie sa automaticky obnovuje každých 10 sekúnd. Pomocou karty ističa identifikujte, ktorí poskytovatelia majú problémy.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute je k dispozícii ako natívna desktopová aplikácia pre Windows, MacOS a Linux.### Inštalácia
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Inštalácia
```bash
# From the electron directory:
@@ -834,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -846,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Výstup → `elektrón/dist-elektrón/`### Key Features
+Output → `electron/dist-electron/`
-| Funkcia | Popis |
-| ------------------------------ | ----------------------------------------------------------------- | ------------------------- |
-| **Pripravenosť servera** | Polls server pred zobrazením okna (bez prázdnej obrazovky) |
-| **Systémová lišta** | Minimalizovať do zásobníka, zmeniť port, ukončiť ponuku zásobníka |
-| **Správa portov** | Zmeňte port servera zo zásobníka (automaticky reštartuje server) |
-| **Zásady zabezpečenia obsahu** | Reštriktívny CSP prostredníctvom hlavičiek relácie |
-| **Jedna inštancia** | Naraz môže bežať iba jedna inštancia aplikácie |
-| **Režim offline** | Pribalený server Next.js funguje bez internetu | ### Environment Variables |
+### Key Features
-| Premenná | Predvolené | Popis |
-| --------------------- | ---------- | --------------------------------- |
-| "OMNIROUTE_PORT" | "20128" | Port servera |
-| `OMNIROUTE_MEMORY_MB` | "512" | Limit haldy Node.js (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Úplná dokumentácia: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/sv/README.md b/docs/i18n/sv/README.md
index 629636f400..f96f55ad93 100644
--- a/docs/i18n/sv/README.md
+++ b/docs/i18n/sv/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/sv/docs/USER_GUIDE.md b/docs/i18n/sv/docs/USER_GUIDE.md
index 5bd0881999..2a8f0ddbc8 100644
--- a/docs/i18n/sv/docs/USER_GUIDE.md
+++ b/docs/i18n/sv/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Komplett guide för att konfigurera leverantörer, skapa kombinationer, integrera CLI-verktyg och distribuera OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Prissättning i ett ögonkast](#-pricing-at-a-glance)
+- [Pricing at a Glance](#-pricing-at-a-glance)
- [Use Cases](#-use-cases)
- [Provider Setup](#-provider-setup)
-- [CLI-integration](#-cli-integration)
-- [Deployment](#-distribution)
-- [Tillgängliga modeller](#-tillgängliga-modeller)
-- [Avancerade funktioner](#-avancerade-funktioner)---
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 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** | DeepSeek | Betala per användning | Inga | Billigt resonemang |
-| | Groq | Betala per användning | Inga | Ultrasnabb slutledning |
-| | xAI (Grok) | Betala per användning | Inga | Grok 4 resonemang |
-| | Mistral | Betala per användning | Inga | EU-värdade modeller |
-| | Förvirring | Betala per användning | Inga | Sökförstärkt |
-| | Tillsammans AI | Betala per användning | Inga | Modeller med öppen källkod |
-| | Fireworks AI | Betala per användning | Inga | Fast FLUX bilder |
-| | Cerebras | Betala per användning | Inga | Wafer-skala hastighet |
-| | Sammanhålla | Betala per användning | Inga | Kommando R+ RAG |
-| | NVIDIA NIM | Betala per användning | Inga | Företagsmodeller |
-| **💰 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** | Qoder | $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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Proffstips:**Börja med Gemini CLI (180K gratis/månad) + Qoder (obegränsat gratis) combo = $0 kostnad!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Problem:**Kvoten går ut oanvänd, hastighetsgränser under tung kodning```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Problem:**Har inte råd med prenumerationer, behöver pålitlig AI-kodning```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Problem:**Deadlines, har inte råd med driftstopp```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Problem:**Behöver AI-assistent i meddelandeappar, helt gratis```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ 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!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Bäst värde:**Enorma gratis nivå! Använd detta före betalda nivåer.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### 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. Dashboard → Lägg till API-nyckel: Leverantör: `glm`, API-nyckel: `din nyckel`
+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` —**Proffstips:**Coding Plan erbjuder 3× kvot till 1/7 kostnad! Återställ dagligen 10:00.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Registrera dig: [MiniMax](https://www.minimax.io/)
-2. Hämta API-nyckel → Dashboard → Lägg till API-nyckel
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Använd:**`minimax/MiniMax-M2.1` —**Proffstips:**Billigaste alternativet för långa sammanhang (1M tokens)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Prenumerera: [Moonshot AI](https://platform.moonshot.ai/)
-2. Hämta API-nyckel → Dashboard → Lägg till API-nyckel
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Använd:**`kimi/kimi-senaste` —**Proffstips:**Fast $9/månad för 10 miljoner tokens = $0,90/1 miljon effektiv kostnad!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Redigera `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Redigera `~/.claude/config.json`:```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Redigera `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Eller använd Dashboard:**CLI Tools → OpenClaw → Auto-config### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI:n laddar automatiskt `.env` från `~/.omniroute/.env` eller `./.env`.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-För servrar med begränsat RAM, använd alternativet för minnesbegränsning:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Skapa `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,12 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-För värdintegrerat läge med CLI-binärer, se Docker-sektionen i huvuddokumenten.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Void Linux-användare kan paketera och installera OmniRoute naturligt med hjälp av "xbps-src" korskompileringsramverket. Detta automatiserar Node.js fristående konstruktion tillsammans med de nödvändiga inbyggda bindningarna för "bättre-sqlite3".
+### Void Linux (xbps-src)
-
-Visa xbps-src-mall```bash
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -408,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -475,60 +516,63 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Variabel | Standard | Beskrivning |
-| ----------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT-signeringshemlighet (**förändring i produktion**) |
-| `INITIAL_PASSWORD` | `123456` | Första inloggningslösenordet |
-| `DATA_DIR` | `~/.omniroute` | Datakatalog (db, användning, loggar) |
-| `PORT` | ram standard | Serviceport ('20128' i exempel) |
-| `VÄRDNAMN` | ram standard | Bind värd (Docker har som standard `0.0.0.0`) |
-| `NODE_ENV` | runtime default | Ställ in "produktion" för distribution |
-| `BASE_URL` | `http://localhost:20128` | Intern bas-URL på serversidan |
-| `CLOUD_URL` | `https://omniroute.dev` | Bas-URL för molnsynkroniseringsslutpunkt |
-| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC-hemlighet för genererade API-nycklar |
-| `REQUIRE_API_KEY` | `falskt` | Framtvinga Bearer API-nyckel på `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `falskt` | Tillåt Api Manager att kopiera fullständiga API-nycklar på begäran |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Uppdateringskadens på serversidan för cachelagrade Provider Limits-data; UI-uppdateringsknappar utlöser fortfarande manuell synkronisering |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `falskt` | Inaktivera automatiska SQLite-ögonblicksbilder före skrivning/import/återställning; manuella säkerhetskopieringar fungerar fortfarande |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `falskt` | Tvinga "Säker" auth-cookie (bakom HTTPS omvänd proxy) |
-| `CLOUDFLARED_BIN` | avstängd | Använd en befintlig `cloudflared`-binär istället för hanterad nedladdning |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Transport för hanterade snabba tunnlar (`http2`, `quic` eller `auto`) |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap-gräns i MB |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | Max cacheposter för prompt |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantiska cacheposter |För den fullständiga referensen till miljövariabeln, se [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Visa alla tillgängliga modeller
+
+View all available models
-**Claude Code (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**– GRATIS: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**– 0,6 USD/1M: `glm/glm-4,7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**– $0,2/1M: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— GRATIS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— GRATIS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— GRATIS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
@@ -538,7 +582,7 @@ vlicense LICENSE
**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Perplexity (`pplx/`)**: `pplx/ekolod-pro`, `pplx/ekolod`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
@@ -548,7 +592,9 @@ vlicense LICENSE
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -556,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Lägg till valfritt modell-ID till valfri leverantör utan att vänta på en appuppdatering:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -564,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Eller använd Dashboard:**Leverantörer → [Leverantör] → Anpassade modeller**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Anmärkningar:
+Notes:
-- OpenRouter och OpenAI/Anthropic-kompatibla leverantörer hanteras endast från**Tillgängliga modeller**. Manuell tillägg, import och automatisk synkronisering hamnar i samma lista med tillgängliga modeller, så det finns ingen separat avsnitt för anpassade modeller för dessa leverantörer.
-- Avsnittet**Anpassade modeller**är avsett för leverantörer som inte exponerar hanterad import av tillgängliga modeller.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Ruttförfrågningar direkt till en specifik leverantör med modellvalidering:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Providerprefixet läggs till automatiskt om det saknas. Omatchade modeller returnerar "400".### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -594,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Tillrang:**Nyckelspecifik → Kombinationsspecifik → Leverantörsspecifik → Global → Miljö.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Returnerar modeller grupperade efter leverantör med typer ('chatt', 'inbäddning', 'bild').### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Synkronisera leverantörer, kombinationer och inställningar mellan enheter
-- Automatisk bakgrundssynkronisering med timeout + felsnabb
-- Föredrar server-side `BASE_URL`/`CLOUD_URL` i produktion### Cloudflare Quick Tunnel
+### Cloud Sync
-- Tillgängligt i**Dashboard → Endpoints**för Docker och andra driftsättningar med egen värd
-- Skapar en tillfällig `https://*.trycloudflare.com`-URL som vidarebefordrar till din nuvarande OpenAI-kompatibla `/v1`-slutpunkt
-- Aktivera först installerar `cloudflared` endast när det behövs; senare omstarter återanvänd samma hanterade binära filer
-- Snabbtunnlar återställs inte automatiskt efter omstart av OmniRoute eller container; återaktivera dem från instrumentpanelen vid behov
-- Tunnel-URL:er är tillfälliga och ändras varje gång du stoppar/startar tunneln
-- Managed Quick Tunnels som standard till HTTP/2-transport för att undvika bullriga QUIC UDP-buffertvarningar i begränsade containrar
-- Ställ in `CLOUDFLARED_PROTOCOL=quic` eller `auto` om du vill åsidosätta det hanterade transportalternativet
-- Ställ in `CLOUDFLARED_BIN` om du föredrar att använda en förinstallerad `cloudflared`-binär istället för den hanterade nedladdningen### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Semantisk cache**— Autocachar icke-strömmande, temperatur=0 svar (förbigå med "X-OmniRoute-No-Cache: true") -**Request Idempotency**— Deduplicerar förfrågningar inom 5s via "Idempotency-Key" eller "X-Request-Id" header -**Progress Tracking**— Opt-in SSE `event: progress`-händelser via `X-OmniRoute-Progress: true` header---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Åtkomst via**Dashboard → Översättare**. Felsöka och visualisera hur OmniRoute översätter API-förfrågningar mellan leverantörer.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Läge | Syfte |
-| ---------------- | ------------------------------------------------------------------------------------------- |
-| **Lekplats** | Välj käll-/målformat, klistra in en begäran och se den översatta utdata direkt |
-| **Chatttestare** | Skicka livechattmeddelanden via proxyn och inspektera hela begäran/svarscykeln |
-| **Testbänk** | Kör batchtester över flera formatkombinationer för att verifiera översättningens korrekthet |
-| **Live Monitor** | Se översättningar i realtid när förfrågningar flödar genom proxyn |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Användningsfall:**
+**Use cases:**
-- Felsök varför en specifik kombination av klient/leverantör misslyckas
-- Verifiera att tanketaggar, verktygsanrop och systemuppmaningar översätts korrekt
-- Jämför formatskillnader mellan OpenAI, Claude, Gemini och Responses API-format---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Konfigurera via**Dashboard → Inställningar → Routing**.
+Configure via **Dashboard → Settings → Routing**.
-| Strategi | Beskrivning |
-| ------------------------------ | -------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Fyll först** | Använder konton i prioritetsordning – primärt konto hanterar alla förfrågningar tills det inte är tillgängligt |
-| **Round Robin** | Går igenom alla konton med en konfigurerbar sticky limit (standard: 3 samtal per konto) |
-| **P2C (Power of Two Choices)** | Väljer 2 slumpmässiga konton och vägar till det friskare — balanserar belastning med medvetenhet om hälsa |
-| **Slumpmässig** | Väljer slumpmässigt ett konto för varje begäran med Fisher-Yates shuffle |
-| **Minst använda** | Rutter till kontot med den äldsta "lastUsedAt"-tidsstämpeln, fördelar trafiken jämnt |
-| **Kostnadsoptimerad** | Rutter till kontot med lägst prioritetsvärde, optimerar för lägsta kostnadsleverantörer | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-För extern sessionsaffinitet (till exempel Claude Code/Codex-agenter bakom omvända proxyservrar), skicka:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute accepterar också `x_session_id` och returnerar den effektiva sessionsnyckeln i `X-OmniRoute-Session-Id`.
+If you use Nginx and send underscore-form headers, enable:
-Om du använder Nginx och skickar understreck-formrubriker, aktivera:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Skapa jokerteckenmönster för att mappa om modellnamn:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Jokertecken stöder `*` (alla tecken) och `?` (enkel tecken).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Definiera globala reservkedjor som gäller för alla förfrågningar:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Konfigurera via**Dashboard → Inställningar → Resilience**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute implementerar motståndskraft på leverantörsnivå med fyra komponenter:
+OmniRoute implements provider-level resilience with four components:
-1.**Provider Profiles**— Konfiguration per leverantör för:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Feltröskel (hur många fel före öppning)
-- Nedkylningstid
-- Känslighet för detektering av hastighetsgräns
-- Exponentiell backoff-parametrar
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Redigerbara hastighetsgränser**— Standardinställningar på systemnivå som kan konfigureras i instrumentpanelen: -**Requests Per Minute (RPM)**— Maximalt antal förfrågningar per minut och konto -**Minsta tid mellan förfrågningar**— Minsta mellanrum i millisekunder mellan förfrågningar -**Max samtidiga förfrågningar**— Maximalt antal samtidiga förfrågningar per konto
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Klicka på**Redigera**för att ändra och sedan på**Spara**eller**Avbryt**. Värden kvarstår via resilience API.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Circuit Breaker**— Spårar fel per leverantör och öppnar automatiskt kretsen när ett tröskelvärde nås: -**STÄNGD**(frisk) — Begäran flyter normalt -**ÖPPEN**— Leverantören är tillfälligt blockerad efter upprepade fel -**HALF_OPEN**— Testar om leverantören har återhämtat sig
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Policy & Locked Identifiers**— Visar strömbrytarens status och låsta identifierare med tvångsupplåsning.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Rate Limit Auto-Detection**— Övervakar rubrikerna "429" och "Retry-After" för att proaktivt undvika att nå leverantörshastighetsgränser.
-
-**Proffstips:**Använd knappen**Återställ alla**för att rensa alla strömbrytare och nedkylningar när en leverantör återhämtar sig efter ett avbrott.---
+---
### Database Export / Import
-Hantera säkerhetskopiering av databas i**Dashboard → Inställningar → System och lagring**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Åtgärd | Beskrivning |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Exportera databas** | Laddar ned den aktuella SQLite-databasen som en `.sqlite`-fil |
-| **Exportera alla (.tar.gz)** | Laddar ner ett fullständigt säkerhetskopieringsarkiv inklusive: databas, inställningar, kombinationer, leverantörsanslutningar (inga referenser), API-nyckelmetadata |
-| **Importera databas** | Ladda upp en `.sqlite`-fil för att ersätta den aktuella databasen. En säkerhetskopia för förimport skapas automatiskt om inte `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Importvalidering:**Den importerade filen är validerad för integritet (SQLite pragmakontroll), obligatoriska tabeller (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) och storlek (max 100MB).
+**Use Cases:**
-**Användningsfall:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Migrera OmniRoute mellan maskiner
-- Skapa externa säkerhetskopior för katastrofåterställning
-- Dela konfigurationer mellan teammedlemmar (exportera alla → dela arkiv)---
+---
### Settings Dashboard
-Inställningssidan är organiserad i 6 flikar för enkel navigering:
+The settings page is organized into 6 tabs for easy navigation:
-| Tab | Innehåll |
-| -------------- | -------------------------------------------------------------------------------------------------------------------- |
-|**Allmänt**| Systemlagringsverktyg, utseendeinställningar, temakontroller och sidofältssynlighet per objekt |
-|**Säkerhet**| Inställningar för inloggning/lösenord, IP-åtkomstkontroll, API-auth för `/modeller` och leverantörsblockering |
-|**Ruttning**| Global routingstrategi (6 alternativ), jokerteckenmodellalias, reservkedjor, kombinationsstandarder |
-|**Resiliens**| Leverantörsprofiler, redigerbara hastighetsgränser, strömbrytarstatus, policyer och låsta identifierare |
-|**AI**| Tänkande budgetkonfiguration, global systempromptinjektion, promptcachestatistik |
-|**Avancerat**| Global proxykonfiguration (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Åtkomst via**Dashboard → Kostnader**.
+Access via **Dashboard → Costs**.
-| Tab | Syfte |
-| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------
-|**Budget**| Ställ in utgiftsgränser per API-nyckel med dagliga/veckovisa/månatliga budgetar och realtidsspårning |
-|**Priser**| Visa och redigera modellprisposter — kostnad per 1000 in-/utdata-tokens per leverantör |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -765,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Kostnadsspårning:**Varje begäran loggar tokenanvändning och beräknar kostnaden med hjälp av pristabellen. Visa uppdelningar i**Dashboard → Användning**efter leverantör, modell och API-nyckel.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute stöder ljudtranskription via den OpenAI-kompatibla slutpunkten:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Tillgängliga leverantörer:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Ljudformat som stöds: "mp3", "wav", "m4a", "flac", "ogg", "webm".---
+---
### Combo Balancing Strategies
-Konfigurera balansering per kombination i**Dashboard → Kombinationer → Skapa/Redigera → Strategi**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Strategi | Beskrivning |
-| ------------------ | ---------------------------------------------------------------------------------- |
-|**Round-Robin**| Roterar genom modeller sekventiellt |
-|**Prioritet**| Försöker alltid den första modellen; faller tillbaka endast på fel |
-|**Slumpmässig**| Väljer en slumpmässig modell från kombinationen för varje begäran |
-|**Viktad**| Rutter proportionellt baserade på tilldelade vikter per modell |
-|**Minst använda**| Rutter till modellen med de minsta senaste förfrågningarna (använder kombinationsmått) |
-|**Kostnadsoptimerad**| Rutter till den billigaste tillgängliga modellen (använder pristabell) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Globala kombinationsstandarder kan ställas in i**Dashboard → Inställningar → Routing → Combo Defaults**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Åtkomst via**Dashboard → Hälsa**. Systemhälsoöversikt i realtid med 6 kort:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Kort | Vad den visar |
-| ---------------------- | ------------------------------------------------------------------ |
-|**Systemstatus**| Drifttid, version, minnesanvändning, datakatalog |
-|**Providers hälsa**| Tillstånd för strömbrytare per leverantör (stängd/öppen/halvöppen) |
-|**Taxegränser**| Aktiva nedkylningar per konto med återstående tid |
-|**Aktiva låsningar**| Leverantörer tillfälligt blockerade av lockoutpolicyn |
-|**Signaturcache**| Dedupliceringscachestatistik (aktiva nycklar, träffhastighet) |
-|**Latens telemetri**| p50/p95/p99 latensaggregation per leverantör |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Proffstips:**Hälsosidan uppdateras automatiskt var tionde sekund. Använd strömbrytarkortet för att identifiera vilka leverantörer som har problem.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute är tillgänglig som en inbyggd skrivbordsapplikation för Windows, macOS och Linux.### Installera
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Installera
```bash
# From the electron directory:
@@ -833,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -845,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Utgång → `elektron/dist-elektron/`### Key Features
+Output → `electron/dist-electron/`
-| Funktion | Beskrivning |
-| ---------------------------- | ------------------------------------------------------------- | ------------------------- |
-| **Serverberedskap** | Omröstningsserver innan fönster visas (ingen tom skärm) |
-| **Systembricka** | Minimera till fack, byt port, avsluta från fackmenyn |
-| **Port Management** | Ändra serverport från facket (startar om servern automatiskt) |
-| **Innehållssäkerhetspolicy** | Restriktiv CSP via sessionsrubriker |
-| **Enstaka instans** | Endast en appinstans kan köras åt gången |
-| **Offlineläge** | Medföljande Next.js-server fungerar utan internet | ### Environment Variables |
+### Key Features
-| Variabel | Standard | Beskrivning |
-| --------------------- | -------- | -------------------------------- |
-| `OMNIROUTE_PORT` | `20128` | Serverport |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap-gräns (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Fullständig dokumentation: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/th/README.md b/docs/i18n/th/README.md
index be6f502550..918075c9ae 100644
--- a/docs/i18n/th/README.md
+++ b/docs/i18n/th/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/th/docs/USER_GUIDE.md b/docs/i18n/th/docs/USER_GUIDE.md
index dbb9111f63..2feed35ffa 100644
--- a/docs/i18n/th/docs/USER_GUIDE.md
+++ b/docs/i18n/th/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-คู่มือฉบับสมบูรณ์สำหรับการกำหนดค่าผู้ให้บริการ การสร้างคอมโบ การผสานรวมเครื่องมือ CLI และการปรับใช้ OmniRoute---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [การกำหนดราคาโดยสรุป](#-การกำหนดราคาโดยสรุป)
-- [กรณีการใช้งาน](#-กรณีการใช้งาน)
-- [การตั้งค่าผู้ให้บริการ](#-การตั้งค่าผู้ให้บริการ)
-- [การรวม CLI](#-การรวม cli)
-- [ปรับใช้](#-ปรับใช้)
-- [รุ่นที่มีจำหน่าย](#-รุ่นที่มีจำหน่าย)
-- [คุณสมบัติขั้นสูง](#-คุณสมบัติขั้นสูง)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 Pricing at a Glance
-| ชั้น | ผู้ให้บริการ | ราคา | รีเซ็ตโควต้า | ดีที่สุดสำหรับ |
-| ------------------ | ---------------- | ---------------- | ------------------- | ---------------------------- |
-| **💳 สมัครสมาชิก** | รหัสคลอดด์ (Pro) | $20/เดือน | 5 ชม. + รายสัปดาห์ | สมัครสมาชิกแล้ว |
-| | Codex (พลัส/โปร) | $20-200/เดือน | 5 ชม. + รายสัปดาห์ | ผู้ใช้ OpenAI |
-| | ราศีเมถุน CLI | **ฟรี** | 180K/เดือน + 1K/วัน | ทุกคน! |
-| | นักบิน GitHub | $10-19/เดือน | รายเดือน | ผู้ใช้ GitHub |
-| **🔑 คีย์ API** | DeepSeek | จ่ายตามการใช้งาน | ไม่มี | การใช้เหตุผลราคาถูก |
-| | กรอค | จ่ายตามการใช้งาน | ไม่มี | การอนุมานที่รวดเร็วเป็นพิเศษ |
-| | xAI (โกรก) | จ่ายตามการใช้งาน | ไม่มี | Grok 4 การใช้เหตุผล |
-| | มิสทรัล | จ่ายตามการใช้งาน | ไม่มี | โมเดลที่โฮสต์โดยสหภาพยุโรป |
-| | ความฉงนสนเท่ห์ | จ่ายตามการใช้งาน | ไม่มี | การค้นหาเสริม |
-| | ร่วมกัน AI | จ่ายตามการใช้งาน | ไม่มี | โมเดลโอเพ่นซอร์ส |
-| | ดอกไม้ไฟ AI | จ่ายตามการใช้งาน | ไม่มี | ภาพ FLUX ที่รวดเร็ว |
-| | สมอง | จ่ายตามการใช้งาน | ไม่มี | ความเร็วระดับเวเฟอร์ |
-| | เชื่อมโยง | จ่ายตามการใช้งาน | ไม่มี | คำสั่ง R+ RAG |
-| | NVIDIA NIM | จ่ายตามการใช้งาน | ไม่มี | โมเดลองค์กร |
-| **💰 ราคาถูก** | 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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 เคล็ดลับสำหรับมืออาชีพ:**เริ่มต้นด้วย Gemini CLI (ฟรี 180,000 ต่อเดือน) + Qoder (ฟรีไม่จำกัด) คอมโบ = ค่าใช้จ่าย $0!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**ปัญหา:**โควต้าหมดอายุโดยไม่ได้ใช้ อัตราจำกัดระหว่างการเขียนโค้ดจำนวนมาก```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**ปัญหา:**ไม่สามารถสมัครสมาชิกได้ ต้องการการเข้ารหัส AI ที่เชื่อถือได้```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**ปัญหา:**กำหนดเวลา ไม่สามารถหยุดการทำงานได้```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**ปัญหา:**ต้องการผู้ช่วย AI ในแอปส่งข้อความ ไม่มีค่าใช้จ่ายใดๆ ทั้งสิ้น```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**เคล็ดลับสำหรับมือโปร:**ใช้ Opus สำหรับงานที่ซับซ้อน และใช้ Sonnet เพื่อความรวดเร็ว โควต้าการติดตาม OmniRoute ต่อรุ่น!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**คุ้มค่าที่สุด:**ระดับฟรีมหาศาล! ใช้สิ่งนี้ก่อนระดับที่ชำระเงิน#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### 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` —**เคล็ดลับสำหรับมือโปร:**แผนการเขียนโค้ดเสนอโควต้า 3× ในราคา 1/7! รีเซ็ตทุกวัน 10.00 น.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. ลงทะเบียน: [MiniMax](https://www.minimax.io/)
-2. รับคีย์ API → แดชบอร์ด → เพิ่มคีย์ API
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**ใช้:**`minimax/MiniMax-M2.1` —**เคล็ดลับสำหรับมือโปร:**ตัวเลือกที่ถูกที่สุดสำหรับบริบทแบบยาว (โทเค็น 1M)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. สมัครสมาชิก: [Moonshot AI](https://platform.moonshot.ai/)
-2. รับคีย์ API → แดชบอร์ด → เพิ่มคีย์ API
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**ใช้:**`kimi/kimi-latest` —**เคล็ดลับสำหรับมือโปร:**แก้ไข $9/เดือนสำหรับโทเค็น 10M = $0.90/ต้นทุนจริง 1M!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-แก้ไข `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Settings → Models → Advanced:
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-แก้ไข `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**หรือใช้แดชบอร์ด:**เครื่องมือ CLI → OpenClaw → กำหนดค่าอัตโนมัติ### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI จะโหลด `.env` โดยอัตโนมัติจาก `~/.omniroute/.env` หรือ `./.env`### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-สำหรับเซิร์ฟเวอร์ที่มี RAM จำกัด ให้ใช้ตัวเลือกขีดจำกัดหน่วยความจำ:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-สร้าง `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,13 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-สำหรับโหมดรวมโฮสต์ที่มีไบนารี CLI โปรดดูส่วนนักเทียบท่าในเอกสารหลัก### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-ผู้ใช้ Void Linux สามารถจัดทำแพ็คเกจและติดตั้ง OmniRoute ได้โดยใช้เฟรมเวิร์กการคอมไพล์ข้าม `xbps-src` สิ่งนี้จะทำให้การสร้าง Node.js แบบสแตนด์อโลนเป็นแบบอัตโนมัติพร้อมกับการเชื่อมโยงแบบเนทีฟ `better-sqlite3` ที่จำเป็น
+### Void Linux (xbps-src)
-<รายละเอียด>
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
-ดูเทมเพลต xbps-src```bash
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -409,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -476,80 +516,85 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| ตัวแปร | ค่าเริ่มต้น | คำอธิบาย |
-| --------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | เคล็ดลับการลงนาม JWT (**การเปลี่ยนแปลงในการผลิต**) |
-| `INITIAL_PASSWORD` | `123456` | รหัสผ่านเข้าสู่ระบบครั้งแรก |
-| `DATA_DIR` | `~/.omniroute` | ไดเร็กทอรีข้อมูล (db, การใช้งาน, บันทึก) |
-| `พอร์ต` | ค่าเริ่มต้นของเฟรมเวิร์ก | พอร์ตบริการ (ในตัวอย่าง `20128`) |
-| `ชื่อโฮสต์` | ค่าเริ่มต้นของเฟรมเวิร์ก | ผูกโฮสต์ (ค่าเริ่มต้นของนักเทียบท่าคือ `0.0.0.0`) |
-| `NODE_ENV` | รันไทม์เริ่มต้น | ตั้งค่า `การผลิต` สำหรับการปรับใช้ |
-| `BASE_URL` | `http://localhost:20128` | URL ฐานภายในฝั่งเซิร์ฟเวอร์ |
-| `CLOUD_URL` | `https://omniroute.dev` | URL ฐานปลายทางการซิงค์บนคลาวด์ |
-| `API_KEY_SECRET` | `จุดสิ้นสุด-พร็อกซี-api-คีย์-ความลับ` | ข้อมูลลับ HMAC สำหรับคีย์ API ที่สร้างขึ้น |
-| `REQUIRE_API_KEY` | `เท็จ` | บังคับใช้คีย์ Bearer API บน `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `เท็จ` | อนุญาตให้ Api Manager คัดลอกคีย์ API แบบเต็มตามต้องการ |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | จังหวะการรีเฟรชฝั่งเซิร์ฟเวอร์สำหรับข้อมูลขีดจำกัดผู้ให้บริการที่แคชไว้ ปุ่มรีเฟรช UI ยังคงทริกเกอร์การซิงค์ด้วยตนเอง |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `เท็จ` | ปิดการใช้งานสแน็ปช็อต SQLite อัตโนมัติก่อนที่จะเขียน/นำเข้า/กู้คืน การสำรองข้อมูลด้วยตนเองยังคงใช้งานได้ |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `เท็จ` | บังคับใช้คุกกี้การตรวจสอบสิทธิ์ 'Secure' (หลังพร็อกซีย้อนกลับ HTTPS) |
-| `CLOUDFLARED_BIN` | ไม่ได้ตั้งค่า | ใช้ไบนารี 'cloudflared' ที่มีอยู่แทนการดาวน์โหลดที่ได้รับการจัดการ |
-| `CLOUDFLARED_PROTOCOL` | `http2` | การขนส่งสำหรับ Quick Tunnels ที่มีการจัดการ (`http2`, `quic` หรือ `auto`) |
-| `OMNIROUTE_MEMORY_MB` | `512` | ขีด จำกัด ฮีปของ Node.js ในหน่วย MB |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | รายการแคชพร้อมท์สูงสุด |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | รายการแคชความหมายสูงสุด |สำหรับการอ้างอิงตัวแปรสภาพแวดล้อมแบบเต็ม โปรดดูที่ [README](../README.md)---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-<รายละเอียด>
-ดูรุ่นที่มีทั้งหมด
+
+View all available models
-**รหัสโคลด (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— ฟรี: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**โปรแกรมควบคุม GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— $0.6/1M: `glm/glm-4.7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— $0.2/1M: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— ฟรี: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— ฟรี: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**คิโระ (`kr/`)**— ฟรี: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
-**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-การใช้เหตุผลอย่างรวดเร็ว`, `xai/grok-code-mini`
+**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
-**มิสทรัล (`มิสทรัล/`)**: `มิสทรัล/มิสทรัล-ใหญ่-2501`, `มิสทรัล/โค้ดสเตรัล-2501`
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**ความงุนงง (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**Together AI (`ร่วมกัน/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**ดอกไม้ไฟ AI (`ดอกไม้ไฟ/`)**: `ดอกไม้ไฟ/บัญชี/ดอกไม้ไฟ/โมเดล/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**สมอง (`สมอง/`)**: `สมอง/llama-3.3-70b`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
-**เชื่อมโยงกัน (`เชื่อมโยงกัน/`)**: `เชื่อมโยงกัน/command-r-plus-08-2024`
+**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -557,7 +602,9 @@ vlicense LICENSE
### Custom Models
-เพิ่ม ID รุ่นใดๆ ให้กับผู้ให้บริการโดยไม่ต้องรอการอัปเดตแอป:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -565,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-หรือใช้แดชบอร์ด:**ผู้ให้บริการ → [ผู้ให้บริการ] → โมเดลที่กำหนดเอง**
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-หมายเหตุ:
+Notes:
-- ผู้ให้บริการที่เข้ากันได้กับ OpenRouter และ OpenAI/Anthropic ได้รับการจัดการจาก**รุ่นที่มีจำหน่าย**เท่านั้น เพิ่ม นำเข้า และซิงค์อัตโนมัติทั้งหมดด้วยตนเองในรายการโมเดลที่มีอยู่เดียวกัน ดังนั้นจึงไม่มีส่วนโมเดลแบบกำหนดเองแยกต่างหากสำหรับผู้ให้บริการเหล่านั้น
-- ส่วน**โมเดลที่กำหนดเอง**มีไว้สำหรับผู้ให้บริการที่ไม่เปิดเผยการนำเข้าโมเดลที่มีอยู่ที่มีการจัดการ### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-กำหนดเส้นทางคำขอโดยตรงไปยังผู้ให้บริการเฉพาะด้วยการตรวจสอบโมเดล:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-คำนำหน้าผู้ให้บริการจะถูกเพิ่มอัตโนมัติหากไม่มี โมเดลที่ไม่ตรงกันส่งคืน "400"### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -595,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**ลำดับความสำคัญ:**เฉพาะคีย์ → เฉพาะคอมโบ → เฉพาะผู้ให้บริการ → ทั่วโลก → สภาพแวดล้อม### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-ส่งคืนโมเดลที่จัดกลุ่มตามผู้ให้บริการที่มีประเภท (`แชท`, `การฝัง`, `รูปภาพ`)### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- ซิงค์ผู้ให้บริการ คอมโบ และการตั้งค่าระหว่างอุปกรณ์ต่างๆ
-- การซิงค์พื้นหลังอัตโนมัติพร้อมการหมดเวลา + ล้มเหลวอย่างรวดเร็ว
-- ต้องการ `BASE_URL`/`CLOUD_URL` ฝั่งเซิร์ฟเวอร์ในการใช้งานจริง### Cloudflare Quick Tunnel
+### Cloud Sync
-- มีอยู่ใน**Dashboard → Endpoints**สำหรับ Docker และการปรับใช้อื่นๆ ที่โฮสต์เอง
-- สร้าง URL `https://*.trycloudflare.com` ชั่วคราวที่ส่งต่อไปยังจุดสิ้นสุด `/v1` ที่เข้ากันได้กับ OpenAI ปัจจุบันของคุณ
-- ขั้นแรกให้เปิดใช้งานการติดตั้ง `cloudflared` เมื่อจำเป็นเท่านั้น รีสตาร์ทในภายหลังนำไบนารีที่ได้รับการจัดการเดิมมาใช้ซ้ำ
-- Quick Tunnels จะไม่ถูกกู้คืนอัตโนมัติหลังจากการรีสตาร์ท OmniRoute หรือคอนเทนเนอร์ เปิดใช้งานอีกครั้งจากแดชบอร์ดเมื่อจำเป็น
-- URL ของอุโมงค์ข้อมูลเป็นแบบชั่วคราวและเปลี่ยนแปลงทุกครั้งที่คุณหยุด/เริ่มต้นอุโมงค์
-- Quick Tunnels ที่มีการจัดการมีค่าเริ่มต้นเป็นการขนส่ง HTTP/2 เพื่อหลีกเลี่ยงคำเตือนบัฟเฟอร์ QUIC UDP ที่มีเสียงดังในคอนเทนเนอร์ที่จำกัด
-- ตั้งค่า `CLOUDFLARED_PROTOCOL=quic` หรือ `auto` หากคุณต้องการแทนที่ตัวเลือกการขนส่งที่มีการจัดการ
-- ตั้งค่า `CLOUDFLARED_BIN` หากคุณต้องการใช้ไบนารี 'cloudflared' ที่ติดตั้งไว้ล่วงหน้าแทนการดาวน์โหลดที่มีการจัดการ### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Semantic Cache**— แคชอัตโนมัติไม่สตรีม อุณหภูมิ=0 การตอบสนอง (บายพาสด้วย `X-OmniRoute-No-Cache: true`) -**คำขอ Idempotency**— กรองคำขอที่ซ้ำกันภายใน 5 วินาทีผ่านส่วนหัว `Idempotency-Key` หรือ `X-Request-Id` -**การติดตามความคืบหน้า**— เลือกใช้เหตุการณ์ `เหตุการณ์: ความคืบหน้า` ของ SSE ผ่านส่วนหัว `X-OmniRoute-Progress: true`---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-เข้าถึงได้ทาง**Dashboard → Translator**แก้ไขข้อบกพร่องและเห็นภาพว่า OmniRoute แปลคำขอ API ระหว่างผู้ให้บริการอย่างไร
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| โหมด | วัตถุประสงค์ |
-| ------------------------- | ---------------------------------------------------------------------------------- |
-| **สนามเด็กเล่น** | เลือกรูปแบบต้นทาง/เป้าหมาย วางคำขอ และดูผลลัพธ์ที่แปลได้ทันที |
-| **เครื่องมือทดสอบการแชท** | ส่งข้อความแชทสดผ่านพร็อกซีและตรวจสอบรอบคำขอ/การตอบกลับทั้งหมด |
-| **ม้านั่งทดสอบ** | เรียกใช้การทดสอบเป็นกลุ่มโดยใช้รูปแบบต่างๆ ร่วมกันเพื่อตรวจสอบความถูกต้องของการแปล |
-| **ถ่ายทอดสด** | ดูการแปลแบบเรียลไทม์ตามคำขอที่ไหลผ่านพร็อกซี |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**กรณีการใช้งาน:**
+**Use cases:**
-- ตรวจแก้จุดบกพร่องว่าทำไมการรวมไคลเอนต์/ผู้ให้บริการเฉพาะจึงล้มเหลว
-- ตรวจสอบว่าแท็กการคิด การเรียกใช้เครื่องมือ และการแจ้งเตือนของระบบแปลอย่างถูกต้อง
-- เปรียบเทียบความแตกต่างของรูปแบบระหว่างรูปแบบ OpenAI, Claude, Gemini และ Responses API---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-กำหนดค่าผ่าน**แดชบอร์ด → การตั้งค่า → การกำหนดเส้นทาง**
+Configure via **Dashboard → Settings → Routing**.
-| กลยุทธ์ | คำอธิบาย |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------- |
-| **กรอกก่อน** | ใช้บัญชีตามลำดับความสำคัญ — บัญชีหลักจะจัดการคำขอทั้งหมดจนกว่าจะไม่พร้อมใช้งาน |
-| **โรบินตัวกลม** | วนรอบบัญชีทั้งหมดด้วยขีดจำกัดที่กำหนดได้ (ค่าเริ่มต้น: 3 สายต่อบัญชี) |
-| **P2C (พลังสองตัวเลือก)** | เลือกบัญชีและเส้นทางแบบสุ่ม 2 บัญชีไปยังบัญชีที่ดีต่อสุขภาพมากขึ้น — สร้างสมดุลระหว่างภาระกับการรับรู้เรื่องสุขภาพ |
-| **สุ่ม** | สุ่มเลือกบัญชีสำหรับแต่ละคำขอโดยใช้ Fisher-Yates shuffle |
-| **ใช้น้อยที่สุด** | กำหนดเส้นทางไปยังบัญชีที่มีการประทับเวลา `lastUsedAt` ที่เก่าที่สุด ซึ่งกระจายการรับส่งข้อมูลอย่างเท่าเทียมกัน |
-| **ปรับต้นทุนให้เหมาะสม** | กำหนดเส้นทางไปยังบัญชีที่มีค่าลำดับความสำคัญต่ำสุด ปรับให้เหมาะสมสำหรับผู้ให้บริการที่มีต้นทุนต่ำที่สุด | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-สำหรับความสัมพันธ์ของเซสชันภายนอก (เช่น เอเจนต์ Claude Code/Codex ที่อยู่หลังพร็อกซีย้อนกลับ) ให้ส่ง:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute ยังยอมรับ `x_session_id` และส่งคืนคีย์เซสชันที่มีผลใน `X-OmniRoute-Session-Id`
+If you use Nginx and send underscore-form headers, enable:
-หากคุณใช้ Nginx และส่งส่วนหัวที่มีรูปแบบขีดล่าง ให้เปิดใช้งาน:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-สร้างรูปแบบไวด์การ์ดเพื่อทำการแมปชื่อโมเดลใหม่:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Wildcard รองรับ `*` (อักขระใดก็ได้) และ `?` (อักขระเดี่ยว)#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-กำหนดห่วงโซ่ทางเลือกส่วนกลางที่ใช้กับคำขอทั้งหมด:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-กำหนดค่าผ่าน**แดชบอร์ด → การตั้งค่า → ความยืดหยุ่น**
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute ใช้ความยืดหยุ่นระดับผู้ให้บริการด้วยองค์ประกอบสี่ประการ:
+OmniRoute implements provider-level resilience with four components:
-1.**โปรไฟล์ผู้ให้บริการ**— การกำหนดค่าต่อผู้ให้บริการสำหรับ:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- เกณฑ์ความล้มเหลว (จำนวนความล้มเหลวก่อนเปิด)
-- ระยะเวลาคูลดาวน์
-- ความไวในการตรวจจับขีด จำกัด อัตรา
-- พารามิเตอร์แบ็คออฟเอ็กซ์โปเนนเชียล
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**ขีดจำกัดอัตราที่แก้ไขได้**— ค่าเริ่มต้นระดับระบบที่กำหนดค่าได้ในแดชบอร์ด: -**คำขอต่อนาที (RPM)**— คำขอสูงสุดต่อนาทีต่อบัญชี -**เวลาขั้นต่ำระหว่างคำขอ**— ช่องว่างขั้นต่ำเป็นมิลลิวินาทีระหว่างคำขอ -**คำขอพร้อมกันสูงสุด**— คำขอพร้อมกันสูงสุดต่อบัญชี
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- คลิก**แก้ไข**เพื่อแก้ไข จากนั้น**บันทึก**หรือ**ยกเลิก**ค่ายังคงมีอยู่ผ่าน API ความยืดหยุ่น
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**เซอร์กิตเบรกเกอร์**— ติดตามความล้มเหลวของผู้ให้บริการแต่ละราย และเปิดวงจรโดยอัตโนมัติเมื่อถึงเกณฑ์: -**ปิด**(สมบูรณ์) — คำขอดำเนินไปตามปกติ -**เปิด**— ผู้ให้บริการถูกบล็อกชั่วคราวหลังจากเกิดข้อผิดพลาดซ้ำแล้วซ้ำอีก -**HALF_OPEN**— ทดสอบว่าผู้ให้บริการฟื้นตัวหรือไม่
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**นโยบายและตัวระบุที่ถูกล็อค**— แสดงสถานะเซอร์กิตเบรกเกอร์และตัวระบุที่ถูกล็อคพร้อมความสามารถในการบังคับปลดล็อค
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**การตรวจจับขีดจำกัดอัตราอัตโนมัติ**— ตรวจสอบส่วนหัว `429` และ `Retry-After` เพื่อหลีกเลี่ยงไม่ให้เกินขีดจำกัดอัตราของผู้ให้บริการในเชิงรุก
-
-**เคล็ดลับสำหรับมือโปร:**ใช้ปุ่ม**รีเซ็ตทั้งหมด**เพื่อล้างเซอร์กิตเบรกเกอร์และคูลดาวน์ทั้งหมดเมื่อผู้ให้บริการฟื้นตัวจากการหยุดทำงาน---
+---
### Database Export / Import
-จัดการการสำรองฐานข้อมูลใน**แดชบอร์ด → การตั้งค่า → ระบบและที่เก็บข้อมูล**
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| การกระทำ | คำอธิบาย |
-| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **ฐานข้อมูลการส่งออก** | ดาวน์โหลดฐานข้อมูล SQLite ปัจจุบันเป็นไฟล์ `.sqlite` |
-| **ส่งออกทั้งหมด (.tar.gz)** | ดาวน์โหลดไฟล์เก็บถาวรการสำรองข้อมูลแบบเต็ม รวมถึง: ฐานข้อมูล การตั้งค่า คอมโบ การเชื่อมต่อของผู้ให้บริการ (ไม่มีข้อมูลประจำตัว) ข้อมูลเมตาของคีย์ API |
-| **นำเข้าฐานข้อมูล** | อัปโหลดไฟล์ `.sqlite` เพื่อแทนที่ฐานข้อมูลปัจจุบัน ข้อมูลสำรองล่วงหน้าที่นำเข้าจะถูกสร้างขึ้นโดยอัตโนมัติ เว้นแต่ `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**การตรวจสอบการนำเข้า:**ไฟล์ที่นำเข้าได้รับการตรวจสอบความสมบูรณ์ (การตรวจสอบ SQLite Pragma), ตารางที่จำเป็น (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) และขนาด (สูงสุด 100MB)
+**Use Cases:**
-**กรณีการใช้งาน:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- โยกย้าย OmniRoute ระหว่างเครื่อง
-- สร้างการสำรองข้อมูลภายนอกสำหรับการกู้คืนระบบ
-- แบ่งปันการกำหนดค่าระหว่างสมาชิกในทีม (ส่งออกทั้งหมด → แชร์ไฟล์เก็บถาวร)---
+---
### Settings Dashboard
-หน้าการตั้งค่าแบ่งออกเป็น 6 แท็บเพื่อให้ง่ายต่อการนำทาง:
+The settings page is organized into 6 tabs for easy navigation:
-| แท็บ | สารบัญ |
-| -------------- | -------------------------------------------------------------------------------------------------- |
-|**ทั่วไป**| เครื่องมือจัดเก็บข้อมูลระบบ การตั้งค่าลักษณะที่ปรากฏ การควบคุมธีม และการมองเห็นแถบด้านข้างต่อรายการ
-|**ความปลอดภัย**| การตั้งค่าการเข้าสู่ระบบ/รหัสผ่าน, การควบคุมการเข้าถึง IP, การตรวจสอบสิทธิ์ API สำหรับ `/models` และการบล็อกผู้ให้บริการ |
-|**การกำหนดเส้นทาง**| กลยุทธ์การกำหนดเส้นทางทั่วโลก (6 ตัวเลือก), นามแฝงโมเดลไวด์การ์ด, เชนทางเลือก, ค่าเริ่มต้นคอมโบ |
-|**ความยืดหยุ่น**| โปรไฟล์ผู้ให้บริการ ขีดจำกัดอัตราที่แก้ไขได้ สถานะเซอร์กิตเบรกเกอร์ นโยบาย และตัวระบุที่ถูกล็อค |
-|**เอไอ**| คิดการกำหนดค่างบประมาณ, การแทรกพร้อมท์ของระบบทั่วโลก, สถิติแคชพร้อมต์ |
-|**ขั้นสูง**| การกำหนดค่าพร็อกซีส่วนกลาง (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-เข้าถึงได้ผ่าน**แดชบอร์ด → ค่าใช้จ่าย**
+Access via **Dashboard → Costs**.
-| แท็บ | วัตถุประสงค์ |
-| ----------- | -------------------------------------------------------------------------------------------- |
-|**งบประมาณ**| กำหนดขีดจำกัดการใช้จ่ายต่อคีย์ API ด้วยงบประมาณรายวัน/รายสัปดาห์/รายเดือนและการติดตามแบบเรียลไทม์ |
-|**ราคา**| ดูและแก้ไขรายการการกำหนดราคาโมเดล — ต้นทุนต่อโทเค็นอินพุต/เอาท์พุต 1K ต่อผู้ให้บริการ |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -766,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**การติดตามต้นทุน:**ทุกคำขอจะบันทึกการใช้โทเค็นและคำนวณต้นทุนโดยใช้ตารางราคา ดูรายละเอียดใน**แดชบอร์ด → การใช้งาน**ตามผู้ให้บริการ รุ่น และคีย์ API---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute รองรับการถอดเสียงผ่านปลายทางที่เข้ากันได้กับ OpenAI:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-ผู้ให้บริการที่มีอยู่:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`)
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-รูปแบบเสียงที่รองรับ: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`---
+---
### Combo Balancing Strategies
-กำหนดค่าการปรับสมดุลต่อคอมโบใน**แดชบอร์ด → คอมโบ → สร้าง/แก้ไข → กลยุทธ์**
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| กลยุทธ์ | คำอธิบาย |
-| ------------------ | ---------------------------------------------------------------------------- |
-|**โรบินตัวกลม**| หมุนเวียนไปตามโมเดลต่างๆ ตามลำดับ |
-|**ลำดับความสำคัญ**| ลองใช้โมเดลแรกเสมอ ถอยกลับเฉพาะข้อผิดพลาด |
-|**สุ่ม**| เลือกโมเดลแบบสุ่มจากคอมโบสำหรับแต่ละคำขอ |
-|**ถ่วงน้ำหนัก**| เส้นทางตามสัดส่วนตามน้ำหนักที่กำหนดต่อรุ่น |
-|**ใช้งานน้อยที่สุด**| กำหนดเส้นทางไปยังโมเดลที่มีคำขอล่าสุดน้อยที่สุด (ใช้เมตริกผสม) |
-|**การเพิ่มประสิทธิภาพต้นทุน**| เส้นทางไปยังรุ่นที่ถูกที่สุด (ใช้ตารางราคา) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-ค่าเริ่มต้นคอมโบสากลสามารถตั้งค่าได้ใน**แดชบอร์ด → การตั้งค่า → การกำหนดเส้นทาง → ค่าเริ่มต้นคอมโบ**---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-เข้าถึงได้ทาง**Dashboard → Health**ภาพรวมความสมบูรณ์ของระบบเรียลไทม์พร้อมการ์ด 6 ใบ:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| บัตร | มันแสดงอะไร |
-| --------------------- | --------------------------------------------------------------- |
-|**สถานะระบบ**| สถานะการออนไลน์ เวอร์ชัน การใช้หน่วยความจำ ไดเร็กทอรีข้อมูล |
-|**สุขภาพของผู้ให้บริการ**| สถานะเซอร์กิตเบรกเกอร์ต่อผู้ให้บริการ (ปิด/เปิด/เปิดครึ่ง) |
-|**จำกัดอัตรา**| คูลดาวน์จำกัดอัตราที่ใช้งานอยู่ต่อบัญชีพร้อมเวลาที่เหลืออยู่ |
-|**การล็อกที่ใช้งานอยู่**| ผู้ให้บริการถูกบล็อกชั่วคราวโดยนโยบายการล็อค |
-|**แคชลายเซ็น**| สถิติแคชการขจัดข้อมูลซ้ำซ้อน (คีย์ที่ใช้งานอยู่ อัตราการเข้าถึง) |
-|**การวัดระยะไกลแบบหน่วงเวลา**| การรวมเวลาแฝง p50/p95/p99 ต่อผู้ให้บริการ |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**เคล็ดลับสำหรับมือโปร:**หน้าสุขภาพจะรีเฟรชอัตโนมัติทุกๆ 10 วินาที ใช้การ์ดเซอร์กิตเบรกเกอร์เพื่อระบุว่าผู้ให้บริการรายใดกำลังประสบปัญหา---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute มีให้บริการในรูปแบบแอปพลิเคชันเดสก์ท็อปดั้งเดิมสำหรับ Windows, macOS และ Linux### ติดตั้ง
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### ติดตั้ง
```bash
# From the electron directory:
@@ -834,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -846,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-เอาท์พุต → `อิเล็กตรอน/ดิส-อิเล็กตรอน/`### Key Features
+Output → `electron/dist-electron/`
-| คุณสมบัติ | คำอธิบาย |
-| ------------------------------- | ------------------------------------------------------------ | ------------------------- |
-| **ความพร้อมของเซิร์ฟเวอร์** | สำรวจเซิร์ฟเวอร์ก่อนแสดงหน้าต่าง (ไม่มีหน้าจอว่าง) |
-| **ถาดระบบ** | ย่อเล็กสุดไปที่ถาด เปลี่ยนพอร์ต ออกจากเมนูถาด |
-| **การจัดการท่าเรือ** | เปลี่ยนพอร์ตเซิร์ฟเวอร์จากถาด (เซิร์ฟเวอร์รีสตาร์ทอัตโนมัติ) |
-| **นโยบายความปลอดภัยของเนื้อหา** | CSP ที่จำกัดผ่านส่วนหัวของเซสชัน |
-| **อินสแตนซ์เดียว** | รันได้ครั้งละหนึ่งอินสแตนซ์ของแอปเท่านั้น |
-| **โหมดออฟไลน์** | เซิร์ฟเวอร์ Next.js ที่แถมมาทำงานโดยไม่ใช้อินเทอร์เน็ต | ### Environment Variables |
+### Key Features
-| ตัวแปร | ค่าเริ่มต้น | คำอธิบาย |
-| --------------------- | ----------- | ------------------------------------ |
-| `OMNIROUTE_PORT` | `20128` | พอร์ตเซิร์ฟเวอร์ |
-| `OMNIROUTE_MEMORY_MB` | `512` | ขีดจำกัดฮีปของ Node.js (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 เอกสารฉบับเต็ม: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/tr/README.md b/docs/i18n/tr/README.md
index b49a265442..69f04f8b21 100644
--- a/docs/i18n/tr/README.md
+++ b/docs/i18n/tr/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/tr/docs/USER_GUIDE.md b/docs/i18n/tr/docs/USER_GUIDE.md
index 1326a863dd..75a0ffbb5d 100644
--- a/docs/i18n/tr/docs/USER_GUIDE.md
+++ b/docs/i18n/tr/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Sağlayıcıları yapılandırmak, kombinasyonlar oluşturmak, CLI araçlarını entegre etmek ve OmniRoute'u dağıtmak için eksiksiz kılavuz.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Bir Bakışta Fiyatlandırma](#-bir bakışta fiyatlandırma)
-- [Kullanım Durumları](#-use-cases)
-- [Sağlayıcı Kurulumu](#-provider-setup)
-- [CLI Entegrasyonu](#-cli-entegrasyonu)
-- [Dağıtım](#-dağıtım)
-- [Mevcut Modeller](#-mevcut-modeller)
-- [Gelişmiş Özellikler](#-gelişmiş-özellikler)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 Pricing at a Glance
-| Seviye | Sağlayıcı | Maliyet | Kota Sıfırlama | En İyisi |
-| ------------------ | ---------------------- | --------------------- | ------------------ | ----------------------------------- |
-| **💳 ABONELİK** | Claude Kodu (Pro) | 20$/ay | 5 saat + haftalık | Zaten abone oldum |
-| | Kodeks (Artı/Pro) | 20-200$/ay | 5 saat + haftalık | OpenAI kullanıcıları |
-| | İkizler CLI | **ÜCRETSİZ** | 180K/ay + 1K/gün | Herkes! |
-| | GitHub Yardımcı Pilotu | 10-19$/ay | Aylık | GitHub kullanıcıları |
-| **🔑API ANAHTARI** | Derin Arama | Kullanım başına ödeme | Yok | Ucuz muhakeme |
-| | Büyük | Kullanım başına ödeme | Yok | Ultra hızlı çıkarım |
-| | xAI (Grok) | Kullanım başına ödeme | Yok | Grok 4 muhakeme |
-| | Mistral | Kullanım başına ödeme | Yok | AB tarafından barındırılan modeller |
-| | Şaşkınlık | Kullanım başına ödeme | Yok | Arama-artırılmış |
-| | Birlikte AI | Kullanım başına ödeme | Yok | Açık kaynaklı modeller |
-| | Havai Fişek Yapay Zeka | Kullanım başına ödeme | Yok | Hızlı FLUX resimleri |
-| | Beyinler | Kullanım başına ödeme | Yok | Gofret ölçekli hız |
-| | Tutarlı | Kullanım başına ödeme | Yok | Komut R+ RAG |
-| | NVIDIA NIM | Kullanım başına ödeme | Yok | Kurumsal modeller |
-| **💰 UCUZ** | GLM-4.7 | 0,6 $/1 milyon $ | Günlük 10:00 | Bütçe yedekleme |
-| | MiniMax M2.1 | 0,2$/1 milyon $ | 5 saatlik ilerleme | En ucuz seçenek |
-| | Kimi K2 | 9$/ay düz | 10 milyon token/ay | Tahmin edilebilir maliyet |
-| **🆓 ÜCRETSİZ** | Kod | 0$ | Sınırsız | 8 model ücretsiz |
-| | Qwen | 0 $ | Sınırsız | 3 model ücretsiz |
-| | Kiro | 0$ | Sınırsız | Claude ücretsiz |
+| 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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Profesyonel İpucu:**Gemini CLI (180.000 ücretsiz/ay) + Qoder (sınırsız ücretsiz) kombinasyonu = 0 ABD doları maliyetle başlayın!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Sorun:**Kullanılmayan kota sona eriyor, yoğun kodlama sırasında hız sınırları```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Sorun:**Abonelik ücretini ödeyemiyorum, güvenilir yapay zeka kodlamasına ihtiyaç var```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Sorun:**Son teslim tarihleri, kesintileri göze alamamak```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Sorun:**Mesajlaşma uygulamalarında yapay zeka asistanına ihtiyaç var, tamamen ücretsiz```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**Profesyonel İpucu:**Karmaşık görevler için Opus'u, hız için Sonnet'i kullanın. OmniRoute model başına kotayı takip eder!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**En İyi Değer:**Devasa ücretsiz katman! Bunu ücretli katmanlardan önce kullanın.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### GLM-4.7 (Daily reset, $0.6/1M)
-1. Kaydolun: [Zhipu AI](https://open.bigmodel.cn/)
-2. Kodlama Planından API anahtarını alın
-3. Kontrol Paneli → API Anahtarı Ekle: Sağlayıcı: `glm`, API Anahtarı: `anahtarınız`
+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`
-**Kullanım:**`glm/glm-4.7` —**Profesyonel İpucu:**Kodlama Planı, 1/7 maliyetle 3 kat kota sunar! Her gün sabah 10:00'a sıfırlayın.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Kaydolun: [MiniMax](https://www.minimax.io/)
-2. API anahtarını alın → Kontrol Paneli → API Anahtarı Ekle
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Kullanım:**`minimax/MiniMax-M2.1` —**Profesyonel İpucu:**Uzun bağlam için en ucuz seçenek (1 milyon jeton)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Abone olun: [Moonshot AI](https://platform.moonshot.ai/)
-2. API anahtarını alın → Kontrol Paneli → API Anahtarı Ekle
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Kullanım:**`kimi/kimi-latest` —**Profesyonel İpucu:**10 milyon token için ayda sabit 9 ABD doları = 0,90 ABD doları/1 milyon etkin maliyet!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-'~/.claude/config.json'ı düzenleyin:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Settings → Models → Advanced:
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-'~/.openclaw/openclaw.json'ı düzenleyin:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Veya Kontrol Panelini kullanın:**CLI Araçları → OpenClaw → Otomatik yapılandırma### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI, `~/.omniroute/.env` veya `./.env`den `.env`yi otomatik olarak yükler.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-Sınırlı RAM'e sahip sunucular için bellek sınırı seçeneğini kullanın:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-'ecosystem.config.js'yi oluşturun:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,12 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-CLI ikili dosyalarıyla ana bilgisayarla tümleşik mod için ana belgelerdeki Docker bölümüne bakın.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Void Linux kullanıcıları OmniRoute'u "xbps-src" çapraz derleme çerçevesini kullanarak yerel olarak paketleyebilir ve kurabilir. Bu, gerekli "better-sqlite3" yerel bağlamalarıyla birlikte Node.js'nin bağımsız yapısını otomatikleştirir.
+### Void Linux (xbps-src)
-
-xbps-src şablonunu görüntüleyin```bash
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
+
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -408,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -475,80 +516,85 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Değişken | Varsayılan | Açıklama |
+| Variable | Default | Description |
| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| 'JWT_SECRET' | `omniroute-varsayılan-gizli-değişim-beni' | JWT imzalama sırrı (**üretimdeki değişiklik**) |
-| `INITIAL_PASSWORD` | '123456' | İlk giriş şifresi |
-| 'DATA_DIR' | `~/.omniroute` | Veri dizini (db, kullanım, günlükler) |
-| 'LİMAN' | çerçeve varsayılanı | Hizmet bağlantı noktası (örneklerde '20128') |
-| `ANA SAHİBİN ADI' | çerçeve varsayılanı | Ana bilgisayarı bağlayın (Docker varsayılan olarak "0.0.0.0"dır) |
-| 'NODE_ENV' | çalışma zamanı varsayılanı | Dağıtım için "üretim"i ayarlayın |
-| 'BASE_URL' | 'http://localhost:20128' | Sunucu tarafı dahili temel URL'si |
-| 'BULUT_URL' | `https://omniroute.dev` | Bulut senkronizasyonu uç noktası temel URL'si |
-| 'API_KEY_SECRET' | 'uç nokta-proxy-api-anahtar-sırrı' | Oluşturulan API anahtarları için HMAC sırrı |
-| `REQUIRE_API_KEY` | 'yanlış' | Taşıyıcı API anahtarını `/v1/*` üzerinde zorunlu kılın |
-| 'ALLOW_API_KEY_REVEAL' | 'yanlış' | API Yöneticisinin talep üzerine tam API anahtarlarını kopyalamasına izin verin |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | '70' | Önbelleğe alınan Sağlayıcı Sınırları verileri için sunucu tarafı yenileme temposu; Kullanıcı arayüzü yenileme düğmeleri hala manuel senkronizasyonu tetikliyor |
-| `DISABLE_SQLITE_AUTO_BACKUP` | 'yanlış' | Yazma/içe aktarma/geri yükleme öncesinde otomatik SQLite anlık görüntülerini devre dışı bırakın; manuel yedeklemeler hâlâ çalışıyor |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | 'yanlış' | 'Güvenli' kimlik doğrulama çerezini zorla (HTTPS ters proxy'nin arkasında) |
-| `CLOUDFLARED_BIN` | ayarlanmamış | Yönetilen indirme yerine mevcut bir "cloudflared" ikili programını kullanın |
-| `CLOUDFLARED_PROTOCOL` | 'http2' | Yönetilen Hızlı Tüneller için Aktarım (`http2`, `quic` veya `auto`) |
-| `OMNIROUTE_MEMORY_MB` | '512' | MB cinsinden Node.js yığın sınırı |
-| `PROMPT_CACHE_MAX_SIZE` | '50' | Maksimum bilgi istemi önbellek girişi |
-| `SEMANTIC_CACHE_MAX_SIZE` | '100' | Maksimum anlamsal önbellek girişi |Ortam değişkeni referansının tamamı için [README](../README.md) dosyasına bakın.---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Mevcut tüm modelleri görüntüleyin
+
+View all available models
-**Claude Kodu ('cc/')**— Pro/Maks: 'cc/claude-opus-4-6', 'cc/claude-sonnet-4-5-20250929', 'cc/claude-haiku-4-5-20251001'
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex ('cx/')**— Plus/Pro: 'cx/gpt-5.2-codex', 'cx/gpt-5.1-codex-max'
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI ('gc/')**— ÜCRETSİZ: 'gc/gemini-3-flash-preview', 'gc/gemini-2.5-pro'
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**GitHub Yardımcı Pilot ('gh/')**: 'gh/gpt-5', 'gh/claude-4.5-sonnet'
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM ('glm/')**— 0,6 ABD doları/1 milyon: 'glm/glm-4,7'
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMaks ("minimaks/")**— 0,2 ABD doları/1 milyon: "minimaks/MiniMax-M2,1"
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder ('if/')**— ÜCRETSİZ: 'if/kimi-k2-thinking', 'if/qwen3-coder-plus', 'if/deepseek-r1'
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen ('qw/')**— ÜCRETSİZ: 'qw/qwen3-coder-plus', 'qw/qwen3-coder-flash'
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro ('kr/')**— ÜCRETSİZ: 'kr/claude-sonnet-4.5', 'kr/claude-haiku-4.5'
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
-**DeepSeek ('ds/')**: 'ds/deepseek-chat', 'ds/deepseek-reasoner'
+**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
-**Groq ('groq/')**: 'groq/llama-3.3-70b-versatile', 'groq/llama-4-maverick-17b-128e-instruct'
+**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
-**xAI ('xai/')**: 'xai/grok-4', 'xai/grok-4-0709-fast-reasoning', 'xai/grok-code-mini'
+**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
-**Mistral ("mistral/")**: "mistral/mistral-büyük-2501", "mistral/codestral-2501"
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Şaşkınlık ('pplx/')**: 'pplx/sonar-pro', 'pplx/sonar'
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**Birlikte AI ('birlikte/')**: 'birlikte/meta-llama/Llama-3.3-70B-Instruct-Turbo'
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**Fireworks AI ('fireworks/')**: 'fireworks/accounts/fireworks/models/deepseek-v3p1'
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**Beyinler ('beyinler/')**: 'beyinler/llama-3.3-70b'
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
-**Tutarlı ('tutarlı/')**: `cohere/command-r-plus-08-2024'
+**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM ('nvidia/')**: 'nvidia/nvidia/llama-3.3-70b-instruct'
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -556,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Uygulama güncellemesini beklemeden herhangi bir sağlayıcıya herhangi bir model kimliğini ekleyin:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -564,22 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Veya Kontrol Panelini kullanın:**Sağlayıcılar → [Sağlayıcı] → Özel Modeller**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Notlar:
+Notes:
-- OpenRouter ve OpenAI/Anthropic uyumlu sağlayıcılar yalnızca**Mevcut Modeller**üzerinden yönetilir. Tümü manuel olarak ekleme, içe aktarma ve otomatik senkronizasyon aynı mevcut model listesinde yer alır; dolayısıyla bu sağlayıcılar için ayrı bir Özel Modeller bölümü yoktur. -**Özel Modeller**bölümü, yönetilen kullanılabilir model içe aktarmalarını göstermeyen sağlayıcılara yöneliktir.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Model doğrulamayla istekleri doğrudan belirli bir sağlayıcıya yönlendirin:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Sağlayıcı öneki eksikse otomatik olarak eklenir. Eşleşmeyen modeller "400" değerini döndürür.### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -593,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Öncelik:**Anahtara özel → Kombineye özel → Sağlayıcıya özel → Genel → Çevre.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Sağlayıcıya göre türlerle ('sohbet', 'yerleştirme', 'resim') gruplandırılmış modelleri döndürür.### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Sağlayıcıları, kombinasyonları ve ayarları cihazlar arasında senkronize edin
-- Zaman aşımı + hızlı arıza ile otomatik arka plan senkronizasyonu
-- Üretimde sunucu tarafı `BASE_URL`/`CLOUD_URL`yi tercih edin### Cloudflare Quick Tunnel
+### Cloud Sync
-- Docker ve diğer kendi kendine barındırılan dağıtımlar için**Kontrol Paneli → Uç Noktalar**'da mevcuttur
-- Mevcut OpenAI uyumlu `/v1` uç noktanıza ileten geçici bir `https://*.trycloudflare.com` URL'si oluşturur
-- İlk olarak yalnızca ihtiyaç duyulduğunda "cloudflared" yüklemelerini etkinleştirin; daha sonra yeniden başlatmalar aynı yönetilen ikili dosyayı yeniden kullanır
-- Hızlı Tüneller, OmniRoute veya konteyner yeniden başlatıldıktan sonra otomatik olarak geri yüklenmez; gerektiğinde bunları kontrol panelinden yeniden etkinleştirin
-- Tünel URL'leri geçicidir ve tüneli her durdurduğunuzda/başlattığınızda değişir
-- Kısıtlı kapsayıcılarda gürültülü QUIC UDP arabellek uyarılarını önlemek için Yönetilen Hızlı Tüneller varsayılan olarak HTTP/2 aktarımını kullanır
-- Yönetilen aktarım seçeneğini geçersiz kılmak istiyorsanız `CLOUDFLARED_PROTOCOL=quic` veya `auto` seçeneğini ayarlayın
-- Yönetilen indirme yerine önceden yüklenmiş bir "cloudflared" ikili programı kullanmayı tercih ediyorsanız "CLOUDFLARED_BIN"i ayarlayın### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Semantik Önbellek**— Akış dışı, sıcaklık=0 yanıtları otomatik olarak önbelleğe alır ('X-OmniRoute-No-Cache: true' ile atlama) -**Request Idempotency**— "Idempotency-Key" veya "X-Request-Id" başlığı aracılığıyla 5 saniye içinde istekleri tekilleştirir -**İlerleme Takibi**— "X-OmniRoute-Progress: true" başlığı aracılığıyla SSE "etkinliği: ilerleme" olaylarını etkinleştirme---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-**Kontrol Paneli → Çevirmen**aracılığıyla erişim. OmniRoute'un sağlayıcılar arasında API isteklerini nasıl çevirdiğini hata ayıklayın ve görselleştirin.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Modu | Amaç |
-| --------------------- | ----------------------------------------------------------------------------------------------- |
-| **Oyun Alanı** | Kaynak/hedef formatlarını seçin, bir istek yapıştırın ve çevrilmiş çıktıyı anında görün |
-| **Sohbet Test Aracı** | Proxy aracılığıyla canlı sohbet mesajları gönderin ve istek/yanıt döngüsünün tamamını inceleyin |
-| **Test Tezgahı** | Çeviri doğruluğunu doğrulamak için birden fazla format kombinasyonunda toplu testler yapın |
-| **Canlı Monitör** | İstekler proxy üzerinden akarken gerçek zamanlı çevirileri izleyin |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Kullanım durumları:**
+**Use cases:**
-- Belirli bir istemci/sağlayıcı kombinasyonunun neden başarısız olduğunu ayıklayın
-- Düşünme etiketlerinin, araç çağrılarının ve sistem istemlerinin doğru şekilde tercüme edildiğini doğrulayın
-- OpenAI, Claude, Gemini ve Responses API formatları arasındaki format farklarını karşılaştırın---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-**Kontrol Paneli → Ayarlar → Yönlendirme**aracılığıyla yapılandırın.
+Configure via **Dashboard → Settings → Routing**.
-| Strateji | Açıklama |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Önce Doldur** | Hesapları öncelik sırasına göre kullanır — birincil hesap, kullanılamayana kadar tüm istekleri yönetir |
-| **Yuvarlak Robin** | Yapılandırılabilir bir sabit limitle tüm hesaplar arasında geçiş yapar (varsayılan: hesap başına 3 çağrı) |
-| **P2C (İki Seçimin Gücü)** | Rastgele 2 hesap seçer ve daha sağlıklı olana yönlendirir — yükü sağlık farkındalığıyla dengeler |
-| **Rastgele** | Fisher-Yates shuffle'ı kullanarak her istek için rastgele bir hesap seçer |
-| **En Az Kullanılan** | En eski "lastUsedAt" zaman damgasına sahip hesaba yönlendirme yaparak trafiği eşit şekilde dağıtır |
-| **Maliyet Optimize Edilmiş** | En düşük maliyetli sağlayıcılar için optimizasyon yaparak en düşük öncelik değerine sahip hesaba giden rotalar | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Harici oturum benzeşimi için (örneğin, ters proxy'lerin arkasındaki Claude Code/Codex aracıları) şunu gönderin:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute ayrıca "x_session_id"yi kabul eder ve "X-OmniRoute-Session-Id"de etkin oturum anahtarını döndürür.
+If you use Nginx and send underscore-form headers, enable:
-Nginx kullanıyorsanız ve alt çizgi biçiminde başlıklar gönderiyorsanız şunları etkinleştirin:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Model adlarını yeniden eşlemek için joker karakter desenleri oluşturun:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Joker karakterler `*` (herhangi bir karakter) ve `?` (tek karakter) destekler.#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Tüm istekler için geçerli olan genel geri dönüş zincirlerini tanımlayın:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-**Kontrol Paneli → Ayarlar → Dayanıklılık**aracılığıyla yapılandırın.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute, sağlayıcı düzeyinde esnekliği dört bileşenle uygular:
+OmniRoute implements provider-level resilience with four components:
-1.**Sağlayıcı Profilleri**— Aşağıdakiler için sağlayıcı başına yapılandırma:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Arıza eşiği (açılmadan önce kaç arıza)
-- Bekleme süresi
-- Hız sınırı algılama hassasiyeti
-- Üstel geri çekilme parametreleri
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Düzenlenebilir Hız Sınırları**— Kontrol panelinde yapılandırılabilen sistem düzeyinde varsayılanlar: -**Dakika Başına İstek (RPM)**— Hesap başına dakika başına maksimum istek -**İstekler Arasındaki Minimum Süre**— İstekler arasındaki milisaniye cinsinden minimum boşluk -**Maksimum Eşzamanlı İstekler**— Hesap başına maksimum eşzamanlı istekler
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Değiştirmek için**Düzenle**'yi ve ardından**Kaydet**veya**İptal**'i tıklayın. Değerler, esneklik API'si aracılığıyla korunur.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Devre Kesici**— Sağlayıcı başına arızaları izler ve bir eşiğe ulaşıldığında devreyi otomatik olarak açar: -**KAPALI**(Sağlıklı) — İstekler normal şekilde akıyor -**AÇIK**— Tekrarlanan hatalardan sonra sağlayıcı geçici olarak engellenir -**HALF_OPEN**— Sağlayıcının iyileşip iyileşmediği test ediliyor
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**İlkeler ve Kilitli Tanımlayıcılar**— Zorunlu kilit açma özelliğiyle devre kesici durumunu ve kilitli tanımlayıcıları gösterir.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Otomatik Hız Sınırı Algılama**— Sağlayıcının hız sınırlarına ulaşmayı proaktif olarak önlemek için "429" ve "Sonra Yeniden Dene" başlıklarını izler.
-
-**Profesyonel İpucu:**Sağlayıcı bir kesintiden kurtulduğunda tüm devre kesicileri ve bekleme sürelerini temizlemek için**Tümünü Sıfırla**düğmesini kullanın.---
+---
### Database Export / Import
-**Kontrol Paneli → Ayarlar → Sistem ve Depolama**bölümünden veritabanı yedeklemelerini yönetin.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Eylem | Açıklama |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Veritabanını Dışa Aktar** | Geçerli SQLite veritabanını `.sqlite` dosyası olarak indirir |
-| **Tümünü Dışa Aktar (.tar.gz)** | Aşağıdakileri içeren tam bir yedekleme arşivini indirir: veritabanı, ayarlar, kombinasyonlar, sağlayıcı bağlantıları (kimlik bilgileri yok), API anahtarı meta verileri |
-| **Veritabanını İçe Aktar** | Mevcut veritabanını değiştirmek için bir `.sqlite` dosyası yükleyin. `DISABLE_SQLITE_AUTO_BACKUP=true` olmadığı sürece içe aktarma öncesi yedekleme otomatik olarak oluşturulur | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**İçe Aktarma Doğrulaması:**İçe aktarılan dosyanın bütünlüğü (SQLite pragma kontrolü), gerekli tablolar (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) ve boyutu (maks. 100MB) açısından doğrulanır.
+**Use Cases:**
-**Kullanım Durumları:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- OmniRoute'u makineler arasında taşıyın
-- Felaket kurtarma için harici yedeklemeler oluşturun
-- Yapılandırmaları ekip üyeleri arasında paylaşın (tümünü dışa aktar → arşivi paylaş)---
+---
### Settings Dashboard
-Ayarlar sayfası, kolay gezinme için 6 sekme halinde düzenlenmiştir:
+The settings page is organized into 6 tabs for easy navigation:
-| Sekme | İçindekiler |
+| Tab | Contents |
| -------------- | ---------------------------------------------------------------------------------------------- |
-|**Genel**| Sistem depolama araçları, görünüm ayarları, tema kontrolleri ve öğe başına kenar çubuğu görünürlüğü |
-|**Güvenlik**| Oturum Açma/Şifre ayarları, IP Erişim Kontrolü, `/models` için API kimlik doğrulaması ve Sağlayıcı Engelleme |
-|**Yönlendirme**| Küresel yönlendirme stratejisi (6 seçenek), joker karakter modeli takma adları, geri dönüş zincirleri, birleşik varsayılanlar |
-|**Dayanıklılık**| Sağlayıcı profilleri, düzenlenebilir hız limitleri, devre kesici durumu, politikalar ve kilitli tanımlayıcılar |
-|**AI**| Bütçe yapılandırmasını düşünme, küresel sistem istemi enjeksiyonu, istem önbellek istatistikleri |
-|**Gelişmiş**| Genel proxy yapılandırması (HTTP/SOCKS5) |---
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-**Kontrol Paneli → Maliyetler**üzerinden erişim.
+Access via **Dashboard → Costs**.
-| Sekme | Amaç |
-| ----------- | ----------------------------------------------------------------------------- |
-|**Bütçe**| Günlük/haftalık/aylık bütçeler ve gerçek zamanlı izleme ile API anahtarı başına harcama sınırlarını belirleyin |
-|**Fiyatlandırma**| Model fiyatlandırma girişlerini görüntüleyin ve düzenleyin - sağlayıcı başına 1.000 giriş/çıkış jetonu başına maliyet |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -764,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Maliyet Takibi:**Her istek, jeton kullanımını günlüğe kaydeder ve fiyatlandırma tablosunu kullanarak maliyeti hesaplar. Sağlayıcıya, modele ve API anahtarına göre**Kontrol Paneli → Kullanım**bölümündeki dökümleri görüntüleyin.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute, OpenAI uyumlu uç nokta aracılığıyla ses transkripsiyonunu destekler:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Mevcut sağlayıcılar:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Desteklenen ses formatları: 'mp3', 'wav', 'm4a', 'flac', 'ogg', 'webm'.---
+---
### Combo Balancing Strategies
-**Kombo başına dengelemeyi**Kontrol Paneli → Kombinasyonlar → Oluştur/Düzenle → Strateji**bölümünde yapılandırın.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Strateji | Açıklama |
-| ------------------ | ------------------------------------------------------------- |
-|**Round-Robin**| Modeller arasında sırayla döner |
-|**Öncelik**| Daima ilk modeli dener; yalnızca hata durumunda geri çekilir |
-|**Rastgele**| Her istek için kombodan rastgele bir model seçer |
-|**Ağırlıklı**| Model başına atanan ağırlıklara göre orantılı olarak rotalar |
-|**En Az Kullanılan**| En az yeni isteğin bulunduğu modele yönlendirmeler (birleşik metrikleri kullanır) |
-|**Maliyet Optimize Edilmiş**| Mevcut en ucuz modele giden yollar (fiyat tablosunu kullanır) |
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Genel birleşik varsayılanlar**Kontrol Paneli → Ayarlar → Yönlendirme → Birleşik Varsayılanlar**bölümünden ayarlanabilir.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-**Kontrol Paneli → Sağlık**üzerinden erişim. 6 kartla gerçek zamanlı sistem sağlığına genel bakış:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Kart | Ne Gösteriyor |
-| --------------------- | ------------------------------------------------- |
-|**Sistem Durumu**| Çalışma süresi, sürüm, bellek kullanımı, veri dizini |
-|**Sağlayıcı Sağlığı**| Sağlayıcı başına devre kesici durumu (Kapalı/Açık/Yarı Açık) |
-|**Oran Sınırları**| Kalan süreyle birlikte hesap başına aktif oran sınırı bekleme süreleri |
-|**Etkin Kilitlemeler**| Sağlayıcılar kilitleme politikası nedeniyle geçici olarak engellendi |
-|**İmza Önbelleği**| Veri tekilleştirme önbellek istatistikleri (etkin anahtarlar, isabet oranı) |
-|**Gecikme Telemetrisi**| sağlayıcı başına p50/p95/p99 gecikme toplamı |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Profesyonel İpucu:**Sağlık sayfası her 10 saniyede bir otomatik olarak yenilenir. Hangi sağlayıcıların sorun yaşadığını belirlemek için devre kesici kartını kullanın.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute, Windows, macOS ve Linux için yerel bir masaüstü uygulaması olarak mevcuttur.### Kurulum
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Kurulum
```bash
# From the electron directory:
@@ -832,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -844,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Çıkış → 'elektron/uzak-elektron/'### Key Features
+Output → `electron/dist-electron/`
-| Özellik | Açıklama |
-| ------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------- |
-| **Sunucu Hazırlığı** | Pencereyi göstermeden önce anket sunucusu (boş ekran yok) |
-| **Sistem Tepsisi** | Tepsiye küçültün, bağlantı noktasını değiştirin, tepsi menüsünden çıkın |
-| **Liman Yönetimi** | Sunucu bağlantı noktasını tepsiden değiştirin (sunucuyu otomatik olarak yeniden başlatır) |
-| **İçerik Güvenliği Politikası** | Oturum başlıkları aracılığıyla kısıtlayıcı CSP |
-| **Tek Örnek** | Aynı anda yalnızca bir uygulama örneği çalıştırılabilir |
-| **Çevrimdışı Mod** | Birlikte verilen Next.js sunucusu internet olmadan çalışır | ### Environment Variables |
+### Key Features
-| Değişken | Varsayılan | Açıklama |
-| --------------------- | ---------- | ---------------------------------- |
-| `OMNIROUTE_PORT` | '20128' | Sunucu bağlantı noktası |
-| `OMNIROUTE_MEMORY_MB` | '512' | Node.js yığın sınırı (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Tüm belgeler: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/uk-UA/README.md b/docs/i18n/uk-UA/README.md
index 643cac24e7..81ed764ffe 100644
--- a/docs/i18n/uk-UA/README.md
+++ b/docs/i18n/uk-UA/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/uk-UA/docs/USER_GUIDE.md b/docs/i18n/uk-UA/docs/USER_GUIDE.md
index 183e2f00ad..0787eb5c1f 100644
--- a/docs/i18n/uk-UA/docs/USER_GUIDE.md
+++ b/docs/i18n/uk-UA/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Повний посібник із налаштування постачальників, створення комбінацій, інтеграції інструментів CLI та розгортання OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Ціни з першого погляду](#-pricing-at-a-glance)
-- [Випадки використання](#-випадків використання)
-- [Налаштування постачальника](#-provider-setup)
-- [Інтеграція CLI](#-cli-integration)
-- [Розгортання](#-розгортання)
-- [Доступні моделі](#-available-models)
-- [Розширені функції](#-advanced-features)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 Pricing at a Glance
-| Рівень | Постачальник | Вартість | Скидання квоти | Найкраще для |
-| ------------------ | ---------------- | ------------------------ | ----------------------------- | --------------------------- |
-| **💳 ПІДПИСКА** | Клод Код (Pro) | 20 доларів США на місяць | 5 годин + щотижня | Вже підписані |
-| | Codex (Plus/Pro) | $20-200/міс | 5 годин + щотижня | Користувачі OpenAI |
-| | Gemini CLI | **БЕЗКОШТОВНО** | 180 тис./місяць + 1 тис./день | всі! |
-| | Копілот GitHub | $10-19/міс | Щомісяця | Користувачі GitHub |
-| **🔑 КЛЮЧ API** | DeepSeek | Оплата за використання | Жодного | Дешеві міркування |
-| | Groq | Оплата за використання | Жодного | Надшвидкий висновок |
-| | xAI (Грок) | Оплата за використання | Жодного | Грок 4 міркування |
-| | Містраль | Оплата за використання | Жодного | Моделі, розміщені в ЄС |
-| | Розгубленість | Оплата за використання | Жодного | Search-augmented |
-| | Разом AI | Оплата за використання | Жодного | Моделі з відкритим кодом |
-| | Феєрверк AI | Оплата за використання | Жодного | Швидкі зображення FLUX |
-| | Головний мозок | Оплата за використання | Жодного | Швидкість вафельної шкали |
-| | Cohere | Оплата за використання | Жодного | Команда R+ RAG |
-| | NVIDIA NIM | Оплата за використання | Жодного | Моделі підприємства |
-| **💰 ДЕШЕВО** | GLM-4.7 | $0,6/1 млн | Щодня о 10 ранку | Резервне копіювання бюджету |
-| | MiniMax M2.1 | $0,2/1 млн | 5-годинний роликовий | Найдешевший варіант |
-| | Кімі К2 | 9 $/міс квартира | 10 млн токенів/міс | Передбачувана вартість |
-| **🆓 БЕЗКОШТОВНО** | Qoder | $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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Порада професіонала:**Почніть із Gemini CLI (180 тис. безкоштовно/місяць) + Qoder (необмежено безкоштовно) = вартість 0 доларів США!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Проблема:**Квота закінчується невикористаною, обмеження швидкості під час інтенсивного кодування```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Проблема:**не можу дозволити собі підписку, потрібне надійне кодування ШІ```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Проблема:**Дедлайни, не можу дозволити собі простої```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Проблема:**потрібен помічник штучного інтелекту в програмах для обміну повідомленнями, повністю безкоштовний```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**Професійна порада:**Використовуйте Opus для складних завдань, Sonnet для швидкості. OmniRoute відстежує квоту на модель!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**Найкраще:**Величезний безкоштовний рівень! Використовуйте це перед платними рівнями.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### 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` —**Професійна порада:**План кодування пропонує 3× квоту за 1/7 вартості! Скидання щодня о 10:00.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Зареєструйтеся: [MiniMax](https://www.minimax.io/)
-2. Отримати ключ API → Інформаційна панель → Додати ключ API
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Використовуйте:**`minimax/MiniMax-M2.1` —**Порада:**Найдешевший варіант для довгого контексту (1 млн токенів)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Підпишіться: [Moonshot AI](https://platform.moonshot.ai/)
-2. Отримати ключ API → Інформаційна панель → Додати ключ API
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Використовуйте:**`kimi/kimi-latest` —**Порада професіонала:**Фіксовані 9 доларів США на місяць за 10 мільйонів токенів = 0,90 доларів США за 1 млн фактичних витрат!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Відредагуйте `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Settings → Models → Advanced:
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Відредагуйте `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Або скористайтеся інформаційною панеллю:**Інструменти CLI → OpenClaw → Auto-config### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI автоматично завантажує `.env` з `~/.omniroute/.env` або `./.env`.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-Для серверів з обмеженою оперативною пам’яттю використовуйте опцію обмеження пам’яті:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Створіть `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,13 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-Для інтегрованого режиму з двійковими файлами CLI дивіться розділ Docker в основних документах.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Користувачі Void Linux можуть запакувати та інсталювати OmniRoute нативно за допомогою фреймворку крос-компіляції `xbps-src`. Це автоматизує окрему збірку Node.js разом із необхідними нативними зв’язками `better-sqlite3`.
+### Void Linux (xbps-src)
-<подробиці>
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
-Переглянути шаблон xbps-src```bash
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -409,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -476,60 +516,63 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Змінна | За замовчуванням | Опис |
-| ----------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | Секрет підпису JWT (**зміни у виробництві**) |
-| `ПОЧАТКОВИЙ_ПАРОЛЬ` | `123456` | Перший пароль для входу |
-| `DATA_DIR` | `~/.omniroute` | Каталог даних (база даних, використання, журнали) |
-| `ПОРТ` | рамка за замовчуванням | Сервісний порт («20128» у прикладах) |
-| `ІМ'Я ХОСТУ` | рамка за замовчуванням | Прив’язати хост (Docker за замовчуванням `0.0.0.0`) |
-| `NODE_ENV` | виконання за замовчуванням | Встановіть `виробництво` для розгортання |
-| `BASE_URL` | `http://localhost:20128` | Внутрішня базова URL-адреса на стороні сервера |
-| `CLOUD_URL` | `https://omniroute.dev` | Базова URL-адреса кінцевої точки хмарної синхронізації |
-| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Секрет HMAC для згенерованих ключів API |
-| `REQUIRE_API_KEY` | `false` | Примусово застосувати ключ API носія на `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `false` | Дозволити Api Manager копіювати повні ключі API на вимогу |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Частота оновлення на стороні сервера для кешованих даних про обмеження постачальника; Кнопки оновлення інтерфейсу досі запускають ручну синхронізацію |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Вимкнути автоматичні знімки SQLite перед записом/імпортом/відновленням; ручне резервне копіювання все ще працює |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `false` | Примусово `Secure` автентифікація cookie (за зворотним проксі HTTPS) |
-| `CLOUDFLARED_BIN` | не встановлено | Використовуйте існуючий двійковий файл `cloudflared` замість керованого завантаження |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Транспорт для керованих швидких тунелів (`http2`, `quic` або `auto`) |
-| `OMNIROUTE_MEMORY_MB` | `512` | Обмеження купи Node.js у МБ |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | Максимальна кількість записів кешу запитів |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Максимальна кількість записів семантичного кешу |Щоб отримати повну інформацію про змінні середовища, перегляньте [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-<подробиці>
-Переглянути всі доступні моделі
+
+View all available models
-**Claude Code (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— БЕЗКОШТОВНО: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— $0,6/1 млн: `glm/glm-4,7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— $0,2/1 млн: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— БЕЗКОШТОВНО: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— БЕЗКОШТОВНО: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— БЕЗКОШТОВНО: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
@@ -537,9 +580,9 @@ vlicense LICENSE
**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
-**Містраль (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Перплексність (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
@@ -549,7 +592,9 @@ vlicense LICENSE
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -557,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Додайте будь-який ідентифікатор моделі до будь-якого постачальника, не чекаючи оновлення програми:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -565,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Або скористайтеся інформаційною панеллю:**Постачальники → [Постачальник] → Спеціальні моделі**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Примітки:
+Notes:
-- OpenRouter і OpenAI/Anthropic-сумісні провайдери керуються лише з**Доступних моделей**. Додавання, імпорт і автоматична синхронізація вручну все потрапляє в той самий список доступних моделей, тому для цих постачальників немає окремого розділу «Користувацькі моделі».
-- Розділ**Користувацькі моделі**призначений для постачальників, які не надають імпорт керованих доступних моделей.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Направляйте запити безпосередньо до конкретного постачальника з перевіркою моделі:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Якщо префікс провайдера відсутній, додається автоматично. Невідповідні моделі повертають "400".### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -595,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Пріоритет:**Специфічний ключ → Специфічний комбінований → Специфічний постачальник → Глобальний → Середовище.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Повертає моделі, згруповані за постачальником із типами (`чат`, `вбудовування`, `зображення`).### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Синхронізація постачальників, комбінацій і налаштувань на всіх пристроях
-- Автоматична фонова синхронізація з тайм-аутом + швидка відмова
-- Надавайте перевагу серверним `BASE_URL`/`CLOUD_URL` у виробництві### Cloudflare Quick Tunnel
+### Cloud Sync
-- Доступно в**Інформаційна панель → Кінцеві точки**для Docker та інших самостійних розгортань
-- Створює тимчасову URL-адресу `https://*.trycloudflare.com`, яка пересилає вашу поточну кінцеву точку `/v1`, сумісну з OpenAI
-- Спочатку ввімкніть установку `cloudflared` лише за потреби; пізніші перезапуски повторно використовують той самий керований двійковий файл
-- Швидкі тунелі не відновлюються автоматично після перезапуску OmniRoute або контейнера; за потреби повторно ввімкніть їх на інформаційній панелі
-- URL-адреси тунелів є ефемерними та змінюються кожного разу, коли ви зупиняєте/запускаєте тунель
-- У керованих швидких тунелях за замовчуванням використовується транспорт HTTP/2, щоб уникнути шумових попереджень буфера QUIC UDP у обмежених контейнерах.
-- Встановіть `CLOUDFLARED_PROTOCOL=quic` або `auto`, якщо ви хочете змінити вибір керованого транспорту
-- Установіть `CLOUDFLARED_BIN`, якщо ви віддаєте перевагу використанню попередньо встановленого двійкового файлу `cloudflared` замість керованого завантаження### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Семантичний кеш**— автоматично кешує непотокові відповіді, температура=0 (обхід за допомогою `X-OmniRoute-No-Cache: true`) -**Request Idempotency**— видаляє дублікати запитів протягом 5 секунд через заголовок `Idempotency-Key` або `X-Request-Id` -**Відстеження прогресу**— увімкнення події SSE `event: progress` через заголовок `X-OmniRoute-Progress: true`---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Доступ через**Інформаційна панель → Перекладач**. Налагодьте та візуалізуйте, як OmniRoute перекладає запити API між постачальниками.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Режим | Призначення |
-| ------------------------ | ---------------------------------------------------------------------------------------------- |
-| **Дитячий майданчик** | Виберіть вихідний/цільовий формати, вставте запит і миттєво перегляньте перекладений результат |
-| **Тестувальник чату** | Надсилайте повідомлення чату через проксі та перевіряйте повний цикл запитів/відповідей |
-| **Випробувальний стенд** | Виконайте пакетні тести для кількох комбінацій форматів, щоб перевірити правильність перекладу |
-| **Живий монітор** | Переглядайте переклади в реальному часі, коли запити проходять через проксі |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Приклади використання:**
+**Use cases:**
-- Налагодження причин невдачі певної комбінації клієнт/постачальник
-- Переконайтеся, що теги мислення, виклики інструментів і системні підказки перекладаються правильно
-- Порівняйте відмінності форматів між форматами OpenAI, Claude, Gemini та Responses API---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Налаштувати через**Інформаційна панель → Налаштування → Маршрутизація**.
+Configure via **Dashboard → Settings → Routing**.
-| Стратегія | Опис |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Спочатку заповніть** | Використовує облікові записи в пріоритетному порядку — основний обліковий запис обробляє всі запити, поки не стане доступним |
-| **Кругова система** | Переглядає всі облікові записи з настроюваним лімітом (за замовчуванням: 3 виклики на обліковий запис) |
-| **P2C (Power of Two Choices)** | Вибирає 2 випадкові облікові записи та направляє до більш здорового — балансує навантаження з усвідомленням здоров’я |
-| **Випадкове** | Випадково вибирає обліковий запис для кожного запиту за допомогою перемішування Фішера-Єйтса |
-| **Найменш використовуваний** | Маршрути до облікового запису з найстарішою міткою часу `lastUsedAt`, рівномірно розподіляючи трафік |
-| **Оптимізація вартості** | Маршрути до облікового запису з найнижчим значенням пріоритету, оптимізуючи для найнижчих постачальників | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Для спорідненості зовнішнього сеансу (наприклад, агенти Claude Code/Codex за зворотними проксі-серверами) надішліть:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute також приймає `x_session_id` і повертає ефективний ключ сеансу в `X-OmniRoute-Session-Id`.
+If you use Nginx and send underscore-form headers, enable:
-Якщо ви використовуєте Nginx і надсилаєте заголовки форми підкреслення, увімкніть:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Створіть шаблони символів підстановки, щоб змінити назви моделей:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Символи підстановки підтримують `*` (будь-які символи) і `?` (один символ).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Визначте глобальні резервні ланцюжки, які застосовуються до всіх запитів:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Налаштуйте за допомогою**Інформаційна панель → Налаштування → Стійкість**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute реалізує стійкість на рівні постачальника за допомогою чотирьох компонентів:
+OmniRoute implements provider-level resilience with four components:
-1.**Профілі постачальників**— конфігурація кожного постачальника для:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Поріг відмови (скільки відмов до відкриття)
-- Тривалість відновлення
-- Чутливість визначення межі швидкості
-- Експоненціальні параметри відставання
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Обмеження швидкості, які можна редагувати**— параметри системного рівня, які можна налаштувати на інформаційній панелі: -**Запитів за хвилину (RPM)**— максимальна кількість запитів за хвилину на обліковий запис -**Мінімальний час між запитами**— мінімальний проміжок у мілісекундах між запитами -**Max Concurrent Requests**— максимальна кількість одночасних запитів на обліковий запис
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Натисніть**Редагувати**, щоб змінити, потім**Зберегти**або**Скасувати**. Значення зберігаються через API стійкості.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Circuit Breaker**— відстежує збої кожного постачальника та автоматично розмикає ланцюг, коли досягається порогове значення: -**ЗАКРИТО**(справний) — запити надходять нормально -**OPEN**— Провайдер тимчасово заблоковано після повторних збоїв -**HALF_OPEN**— Перевірка, якщо провайдер відновився
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Політики та заблоковані ідентифікатори**— показує статус автоматичного вимикача та заблоковані ідентифікатори з можливістю примусового розблокування.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Автовизначення ліміту швидкості**— відстежує заголовки `429` і `Retry-After`, щоб завчасно уникнути перевищення обмежень постачальника.
-
-**Порада:**Використовуйте кнопку**Скинути все**, щоб очистити всі автоматичні вимикачі та часи відновлення, коли постачальник відновиться після збою.---
+---
### Database Export / Import
-Керуйте резервними копіями бази даних у**Інформаційна панель → Налаштування → Система та сховище**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Дія | Опис |
-| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Експорт бази даних** | Завантажує поточну базу даних SQLite як файл `.sqlite` |
-| **Експортувати все (.tar.gz)** | Завантажує повний резервний архів, включаючи: базу даних, налаштування, комбінації, з’єднання провайдера (без облікових даних), метадані ключа API |
-| **Імпорт бази даних** | Завантажте файл `.sqlite`, щоб замінити поточну базу даних. Резервна копія перед імпортом створюється автоматично, якщо `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Перевірка імпорту:**Імпортований файл перевіряється на цілісність (перевірка прагми SQLite), необхідні таблиці (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) і розмір (макс. 100 МБ).
+**Use Cases:**
-**Випадки використання:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Перенос OmniRoute між машинами
-- Створення зовнішніх резервних копій для аварійного відновлення
-- Спільний доступ до конфігурацій між членами команди (експортувати все → надати доступ до архіву)---
+---
### Settings Dashboard
-Для зручності навігації сторінка налаштувань складається з 6 вкладок:
+The settings page is organized into 6 tabs for easy navigation:
-| Вкладка | Зміст |
+| Tab | Contents |
| -------------- | ---------------------------------------------------------------------------------------------- |
-|**Загальне**| Інструменти системного зберігання, налаштування зовнішнього вигляду, елементи керування темою та видимість бічної панелі для кожного елемента |
-|**Безпека**| Налаштування логіна/пароля, контроль IP-доступу, автентифікація API для `/models` і блокування постачальника |
-|**Маршрутизація**| Глобальна стратегія маршрутизації (6 варіантів), псевдоніми моделей із підстановкою, резервні ланцюжки, комбіновані параметри за замовчуванням |
-|**Стійкість**| Профілі постачальників, обмеження швидкості, які можна редагувати, статус автоматичного вимикача, політики та заблоковані ідентифікатори |
-|**AI**| Продумана конфігурація бюджету, впровадження глобальної системної підказки, швидка статистика кешу |
-|**Розширений**| Глобальна конфігурація проксі (HTTP/SOCKS5) |---
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Доступ через**Інформаційна панель → Витрати**.
+Access via **Dashboard → Costs**.
-| Вкладка | Призначення |
+| Tab | Purpose |
| ----------- | ---------------------------------------------------------------------------------------- |
-|**Бюджет**| Встановіть ліміти витрат на ключ API за допомогою щоденних/тижневих/місячних бюджетів і відстеження в реальному часі |
-|**Ціни**| Перегляд і редагування записів моделі ціноутворення — вартість 1 тис. токенів вводу/виводу на постачальника |```bash
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -766,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Відстеження вартості:**кожен запит реєструє використання токенів і розраховує вартість за допомогою таблиці цін. Перегляньте розбивку в**Інформаційна панель → Використання**за постачальником, моделлю та ключем API.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute підтримує транскрипцію аудіо через кінцеву точку, сумісну з OpenAI:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Доступні постачальники:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Підтримувані аудіоформати: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.---
+---
### Combo Balancing Strategies
-Налаштуйте балансування за комбо в**Інформаційна панель → Комбо → Створити/Редагувати → Стратегія**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Стратегія | Опис |
+| Strategy | Description |
| ------------------ | ------------------------------------------------------------------------ |
-|**Кругова система**| Обертає моделі послідовно |
-|**Пріоритет**| Завжди пробує першу модель; повертається лише в разі помилки |
-|**Випадкове**| Вибирає випадкову модель із комбо для кожного запиту |
-|**Зважений**| Маршрути пропорційно на основі призначеної ваги для моделі |
-|**Найменш використовуваний**| Маршрути до моделі з найменшою кількістю останніх запитів (використовує комбіновані показники) |
-|**Оптимізовано за витратами**| Маршрути до найдешевшої доступної моделі (використовується таблиця цін) |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Глобальні стандартні параметри комбінованих маршрутів можна встановити в**Інформаційна панель → Налаштування → Маршрутизація → Стандартні параметри комбінованих маршрутів**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Доступ через**Інформаційна панель → Здоров’я**. Огляд стану системи в реальному часі з 6 картками:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Картка | Що це показує |
-| --------------------- | ------------------------------------------------------------ |
-|**Стан системи**| Час роботи, версія, використання пам’яті, каталог даних |
-|**Здоров’я постачальника**| Стан автоматичного вимикача для кожного постачальника (замкнуто/розімкнуто/напіврозімкнуто) |
-|**Обмеження швидкості**| Обмеження активної швидкості перезарядки на обліковий запис із часом, що залишився |
-|**Активні блокування**| Провайдери, тимчасово заблоковані політикою блокування |
-|**Кеш підпису**| Статистика кешу дедуплікації (активні ключі, частота звернень) |
-|**Телеметрія затримки**| Агрегація затримок p50/p95/p99 для кожного провайдера |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Професійна порада.**Сторінка «Здоров’я» автоматично оновлюється кожні 10 секунд. Використовуйте картку автоматичного вимикача, щоб визначити, які постачальники мають проблеми.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute доступний як рідна настільна програма для Windows, macOS і Linux.### Встановити
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Встановити
```bash
# From the electron directory:
@@ -834,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -846,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Вивід → `electron/dist-electron/`### Key Features
+Output → `electron/dist-electron/`
-| Особливість | Опис |
-| --------------------------- | ----------------------------------------------------------------- | ------------------------- |
-| **Готовність сервера** | Опитує сервер перед показом вікна (без порожнього екрана) |
-| **Системний трей** | Згорнути в трей, змінити порт, вийти з меню трея |
-| **Керування портами** | Змінити порт сервера з трея (сервер автоматично перезапускається) |
-| **Політика безпеки вмісту** | Обмежувальний CSP через заголовки сеансу |
-| **Один екземпляр** | Одночасно може працювати лише один екземпляр програми |
-| **Автономний режим** | Поєднаний сервер Next.js працює без Інтернету | ### Environment Variables |
+### Key Features
-| Змінна | За замовчуванням | Опис |
-| --------------------- | ---------------- | ------------------------------------ |
-| `OMNIROUTE_PORT` | `20128` | Порт сервера |
-| `OMNIROUTE_MEMORY_MB` | `512` | Обмеження купи Node.js (64–16384 МБ) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Повна документація: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/vi/README.md b/docs/i18n/vi/README.md
index 53af6319fb..1557bb3159 100644
--- a/docs/i18n/vi/README.md
+++ b/docs/i18n/vi/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/vi/docs/USER_GUIDE.md b/docs/i18n/vi/docs/USER_GUIDE.md
index c2062fccc7..0e9418f215 100644
--- a/docs/i18n/vi/docs/USER_GUIDE.md
+++ b/docs/i18n/vi/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-Hướng dẫn đầy đủ về cách định cấu hình nhà cung cấp, tạo tổ hợp, tích hợp công cụ CLI và triển khai OmniRoute.---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [Tóm tắt giá](#-giá trong nháy mắt)
-- [Các trường hợp sử dụng](#-use-case)
-- [Thiết lập nhà cung cấp](#-provider-setup)
-- [Tích hợp CLI](#-cli-integration)
-- [Triển khai](#-triển khai)
-- [Các mẫu có sẵn](#-available-models)
-- [Tính năng nâng cao](#-advanced-features)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 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** | DeepSeek | Trả tiền cho mỗi lần sử dụng | Không có | Lý luận giá rẻ |
-| | Groq | Trả tiền cho mỗi lần sử dụng | Không có | Suy luận cực nhanh |
-| | xAI (Grok) | Trả tiền cho mỗi lần sử dụng | Không có | Lý luận Grok 4 |
-| | Mistral | Trả tiền cho mỗi lần sử dụng | Không có | Các mô hình do EU đăng cai |
-| | Lúng túng | Trả tiền cho mỗi lần sử dụng | Không có | Tăng cường tìm kiếm |
-| | Cùng AI | Trả tiền cho mỗi lần sử dụng | Không có | Mô hình nguồn mở |
-| | Pháo hoa AI | Trả tiền cho mỗi lần sử dụng | Không có | Hình ảnh FLUX nhanh |
-| | Não | Trả tiền cho mỗi lần sử dụng | Không có | Tốc độ quy mô wafer |
-| | Kết hợp | Trả tiền cho mỗi lần sử dụng | Không có | Lệnh R+ RAG |
-| | NVIDIA NIM | Trả tiền cho mỗi lần sử dụng | Không có | Mô hình doanh nghiệp |
-| **💰 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Í** | Qoder | $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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡 Mẹo chuyên nghiệp:**Bắt đầu với Gemini CLI (180K miễn phí/tháng) + combo Qoder (miễn phí không giới hạn) = chi phí $0!---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**Vấn đề:**Hạn ngạch hết hạn không được sử dụng, giới hạn tốc độ trong quá trình mã hóa nặng```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**Vấn đề:**Không đủ khả năng đăng ký, cần mã hóa AI đáng tin cậy```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**Vấn đề:**Thời hạn, không đủ khả năng cho thời gian ngừng hoạt động```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**Vấn đề:**Cần trợ lý AI trong ứng dụng nhắn tin, hoàn toàn miễn phí```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ 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!#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,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í.#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,21 +175,27 @@ Models:
#### 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` —**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.#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. Đăng ký: [MiniMax](https://www.minimax.io/)
-2. Nhận khóa API → Bảng điều khiển → Thêm khóa API
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**Sử dụng:**`minimax/MiniMax-M2.1` —**Mẹo chuyên nghiệp:**Tùy chọn rẻ nhất cho bối cảnh dài (1 triệu mã thông báo)!#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1. Đăng ký: [Moonshot AI](https://platform.moonshot.ai/)
-2. Nhận khóa API → Bảng điều khiển → Thêm khóa API
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**Sử dụng:**`kimi/kimi-latest` —**Mẹo chuyên nghiệp:**Đã sửa lỗi 9 USD/tháng cho 10 triệu token = 0,90 USD/1 triệu chi phí hiệu quả!### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -203,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -244,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-Chỉnh sửa `~/.claude/config.json`:```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -258,41 +283,42 @@ Chỉnh sửa `~/.claude/config.json`:```json
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-Chỉnh sửa `~/.openclaw/openclaw.json`:```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**Hoặc sử dụng Bảng điều khiển:**Công cụ CLI → OpenClaw → Tự động cấu hình### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -313,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI tự động tải `.env` từ `~/.omniroute/.env` hoặc `./.env`.### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -336,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-Đối với các máy chủ có RAM hạn chế, hãy sử dụng tùy chọn giới hạn bộ nhớ:```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-Tạo `ecosystem.config.js`:```javascript
+```javascript
module.exports = {
apps: [
{
@@ -370,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -382,13 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-Để biết chế độ tích hợp máy chủ với các tệp nhị phân CLI, hãy xem phần Docker trong tài liệu chính.### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Người dùng Void Linux có thể đóng gói và cài đặt OmniRoute nguyên bản bằng cách sử dụng khung biên dịch chéo `xbps-src`. Điều này tự động hóa bản dựng độc lập của Node.js cùng với các liên kết gốc `better-sqlite3` được yêu cầu.
+### Void Linux (xbps-src)
-
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
-Xem mẫu xbps-src```bash
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -409,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -476,60 +516,63 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-| Biến | Mặc định | Mô tả |
-| ------------------------------ | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `JWT_BÍ MẬT` | `omniroute-default-secret-change-me` | Bí mật ký kết JWT (**thay đổi trong sản xuất**) |
-| `INITIAL_PASSWORD` | `123456` | Mật khẩu đăng nhập lần đầu |
-| `DỮ LIỆU_DIR` | `~/.omniroute` | Thư mục dữ liệu (db, cách sử dụng, nhật ký) |
-| `CỔNG` | mặc định khung | Cổng dịch vụ (ví dụ: `20128`) |
-| `TÊN MÁY CHỦ` | mặc định khung | Máy chủ liên kết (Docker mặc định là `0.0.0.0`) |
-| `NODE_ENV` | mặc định thời gian chạy | Đặt `sản xuất` để triển khai |
-| `CƠ SỞ_URL` | `http://localhost:20128` | URL cơ sở nội bộ phía máy chủ |
-| `CLOUD_URL` | `https://omniroute.dev` | URL cơ sở điểm cuối đồng bộ hóa đám mây |
-| `API_KEY_BÍ MẬT` | `điểm cuối-proxy-api-key-secret` | Bí mật HMAC cho các khóa API được tạo |
-| `REQUIRE_API_KEY` | `sai` | Thực thi khóa API Bearer trên `/v1/*` |
-| `ALLOW_API_KEY_REVEAL` | `sai` | Cho phép Api Manager sao chép toàn bộ khóa API theo yêu cầu |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Nhịp làm mới phía máy chủ cho dữ liệu Giới hạn nhà cung cấp được lưu trong bộ nhớ đệm; Nút làm mới giao diện người dùng vẫn kích hoạt đồng bộ hóa thủ công |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `sai` | Vô hiệu hóa ảnh chụp nhanh SQLite tự động trước khi ghi/nhập/khôi phục; sao lưu thủ công vẫn hoạt động |
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
-| `AUTH_COOKIE_SECURE` | `sai` | Buộc cookie xác thực `Secure` (đằng sau proxy ngược HTTPS) |
-| `CLOUDFLARED_BIN` | bỏ đặt | Sử dụng tệp nhị phân `cloudflared` hiện có thay vì tải xuống được quản lý |
-| `CLOUDFLARED_PROTOCOL` | `http2` | Vận chuyển cho Đường hầm nhanh được quản lý (`http2`, `quic` hoặc `auto`) |
-| `OMNIROUTE_MEMORY_MB` | `512` | Giới hạn vùng nhớ heap của Node.js tính bằng MB |
-| `PROMPT_CACHE_MAX_SIZE` | `50` | Các mục bộ đệm nhắc nhở tối đa |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Các mục bộ đệm ngữ nghĩa tối đa |Để biết tham chiếu đầy đủ về biến môi trường, hãy xem [README](../README.md).---
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-
-Xem tất cả các mẫu có sẵn
+
+View all available models
-**Mã Claude (`cc/`)**— Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— MIỄN PHÍ: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— 0,6 USD/1 triệu: `glm/glm-4,7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— 0,2 USD/1 triệu: `minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— MIỄN PHÍ: `if/kimi-k2-thinking`, `if/qwen3-code-plus`, `if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— MIỄN PHÍ: `qw/qwen3-code-plus`, `qw/qwen3-code-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— MIỄN PHÍ: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
@@ -539,17 +582,19 @@ vlicense LICENSE
**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**Sự bối rối (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**Cùng nhau AI (`cùng nhau/`)**: `cùng nhau/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**Pháo hoa AI (`pháo hoa/`)**: `pháo hoa/tài khoản/pháo hoa/mô hình/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**Não (`cerebras/`)**: `cerebras/llama-3.3-70b`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -557,7 +602,9 @@ vlicense LICENSE
### Custom Models
-Thêm bất kỳ ID mẫu nào vào bất kỳ nhà cung cấp nào mà không cần chờ cập nhật ứng dụng:```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -565,23 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-Hoặc sử dụng Trang tổng quan:**Nhà cung cấp → [Nhà cung cấp] → Mô hình tùy chỉnh**.
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-Ghi chú:
+Notes:
-- Các nhà cung cấp tương thích với OpenRouter và OpenAI/Anthropic chỉ được quản lý từ**Mô hình có sẵn**. Thêm, nhập và tự động đồng bộ hóa thủ công tất cả các vùng trong cùng một danh sách mô hình có sẵn, do đó không có phần Mô hình tùy chỉnh riêng cho các nhà cung cấp đó.
-- Phần**Mô hình tùy chỉnh**dành cho các nhà cung cấp không hiển thị nội dung nhập mô hình có sẵn được quản lý.### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-Định tuyến các yêu cầu trực tiếp đến một nhà cung cấp cụ thể với xác thực mô hình:```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-Tiền tố nhà cung cấp được tự động thêm vào nếu thiếu. Các mô hình không khớp trả về `400`.### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -595,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**Ưu tiên:**Dành riêng cho khóa → Dành riêng cho tổ hợp → Dành riêng cho nhà cung cấp → Toàn cầu → Môi trường.### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-Trả về các mô hình được nhóm theo nhà cung cấp với các loại (`chat`, `embedding`, `image`).### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- Đồng bộ hóa nhà cung cấp, combo và cài đặt trên các thiết bị
-- Đồng bộ hóa nền tự động với thời gian chờ + không nhanh
-- Ưu tiên `BASE_URL`/`CLOUD_URL` phía máy chủ trong quá trình sản xuất### Cloudflare Quick Tunnel
+### Cloud Sync
-- Có sẵn trong**Bảng điều khiển → Điểm cuối**cho Docker và các hoạt động triển khai tự lưu trữ khác
-- Tạo URL `https://*.trycloudflare.com` tạm thời chuyển tiếp đến điểm cuối `/v1` tương thích với OpenAI hiện tại của bạn
-- Trước tiên chỉ bật cài đặt `cloudflared` khi cần; sau đó khởi động lại, sử dụng lại cùng một tệp nhị phân được quản lý
-- Đường hầm nhanh không được tự động khôi phục sau khi khởi động lại OmniRoute hoặc vùng chứa; kích hoạt lại chúng từ bảng điều khiển khi cần
-- URL đường hầm là nhất thời và thay đổi mỗi khi bạn dừng/bắt đầu đường hầm
-- Đường hầm nhanh được quản lý mặc định vận chuyển HTTP/2 để tránh cảnh báo bộ đệm QUIC UDP ồn ào trong các vùng chứa bị hạn chế
-- Đặt `CLOUDFLARED_PROTOCOL=quic` hoặc `auto` nếu bạn muốn ghi đè lựa chọn vận chuyển được quản lý
-- Đặt `CLOUDFLARED_BIN` nếu bạn thích sử dụng tệp nhị phân `cloudflared` được cài đặt sẵn thay vì tải xuống được quản lý### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**Bộ đệm ngữ nghĩa**— Tự động lưu vào bộ đệm không phát trực tuyến, phản hồi nhiệt độ=0 (bỏ qua bằng `X-OmniRoute-No-Cache: true`) -**Yêu cầu Idempotency**— Loại bỏ các yêu cầu trùng lặp trong vòng 5 giây thông qua tiêu đề `Idempotency-Key` hoặc `X-Request-Id` -**Theo dõi tiến trình**— Chọn tham gia các sự kiện `event: Progress` SSE thông qua tiêu đề `X-OmniRoute-Progress: true`---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-Truy cập qua**Bảng điều khiển → Trình dịch**. Gỡ lỗi và trực quan hóa cách OmniRoute dịch các yêu cầu API giữa các nhà cung cấp.
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| Chế độ | Mục đích |
-| ----------------------------- | ---------------------------------------------------------------------------------------------- |
-| **Sân chơi** | Chọn định dạng nguồn/đích, dán yêu cầu và xem bản dịch ngay lập tức |
-| **Người kiểm tra trò chuyện** | Gửi tin nhắn trò chuyện trực tiếp qua proxy và kiểm tra toàn bộ chu trình yêu cầu/phản hồi |
-| **Bàn thử nghiệm** | Chạy thử nghiệm hàng loạt trên nhiều kết hợp định dạng để xác minh tính chính xác của bản dịch |
-| **Màn hình trực tiếp** | Xem các bản dịch theo thời gian thực khi các yêu cầu chuyển qua proxy |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**Trường hợp sử dụng:**
+**Use cases:**
-- Gỡ lỗi tại sao kết hợp khách hàng/nhà cung cấp cụ thể không thành công
-- Xác minh rằng thẻ tư duy, lệnh gọi công cụ và lời nhắc hệ thống được dịch chính xác
-- So sánh sự khác biệt về định dạng giữa các định dạng API OpenAI, Claude, Gemini và Responses---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-Định cấu hình qua**Bảng điều khiển → Cài đặt → Định tuyến**.
+Configure via **Dashboard → Settings → Routing**.
-| Chiến lược | Mô tả |
-| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| **Điền đầu tiên** | Sử dụng các tài khoản theo thứ tự ưu tiên - tài khoản chính xử lý tất cả các yêu cầu cho đến khi không có sẵn |
-| **Vòng tròn** | Xoay vòng qua tất cả các tài khoản với giới hạn cố định có thể định cấu hình (mặc định: 3 cuộc gọi cho mỗi tài khoản) |
-| **P2C (Sức mạnh của hai lựa chọn)** | Chọn 2 tài khoản ngẫu nhiên và hướng đến tài khoản lành mạnh hơn — cân bằng tải trọng với nhận thức về sức khỏe |
-| **Ngẫu nhiên** | Chọn ngẫu nhiên một tài khoản cho mỗi yêu cầu bằng cách sử dụng tính năng ngẫu nhiên Fisher-Yates |
-| **Ít sử dụng nhất** | Định tuyến đến tài khoản có dấu thời gian `lastUsedAt` cũ nhất, phân bổ lưu lượng truy cập đồng đều |
-| **Tối ưu hóa chi phí** | Định tuyến đến tài khoản có giá trị ưu tiên thấp nhất, tối ưu hóa cho nhà cung cấp có chi phí thấp nhất | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-Đối với mối quan hệ phiên bên ngoài (ví dụ: tác nhân Claude Code/Codex đằng sau proxy ngược), hãy gửi:```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute cũng chấp nhận `x_session_id` và trả về khóa phiên hiệu quả trong `X-OmniRoute-Session-Id`.
+If you use Nginx and send underscore-form headers, enable:
-Nếu bạn sử dụng Nginx và gửi tiêu đề dạng gạch dưới, hãy bật:```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-Tạo các mẫu ký tự đại diện để ánh xạ lại tên mô hình:```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-Ký tự đại diện hỗ trợ `*` (bất kỳ ký tự nào) và `?` (ký tự đơn).#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-Xác định chuỗi dự phòng toàn cầu áp dụng cho tất cả các yêu cầu:```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-Định cấu hình qua**Bảng điều khiển → Cài đặt → Khả năng phục hồi**.
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute triển khai khả năng phục hồi cấp nhà cung cấp với bốn thành phần:
+OmniRoute implements provider-level resilience with four components:
-1.**Hồ sơ nhà cung cấp**— Cấu hình cho mỗi nhà cung cấp cho:
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- Ngưỡng thất bại (có bao nhiêu lần thất bại trước khi mở)
-- Thời gian hồi chiêu
-- Độ nhạy phát hiện giới hạn tốc độ
-- Thông số backoff theo cấp số nhân
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**Giới hạn tỷ lệ có thể chỉnh sửa**— Giá trị mặc định ở cấp hệ thống có thể định cấu hình trong trang tổng quan: -**Số yêu cầu mỗi phút (RPM)**— Số yêu cầu tối đa mỗi phút cho mỗi tài khoản -**Thời gian tối thiểu giữa các yêu cầu**— Khoảng cách tối thiểu tính bằng mili giây giữa các yêu cầu -**Số yêu cầu đồng thời tối đa**— Số yêu cầu đồng thời tối đa cho mỗi tài khoản
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- Nhấp vào**Chỉnh sửa**để sửa đổi, sau đó nhấp vào**Lưu**hoặc**Hủy**. Các giá trị vẫn tồn tại thông qua API khả năng phục hồi.
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**Bộ ngắt mạch**— Theo dõi lỗi của mỗi nhà cung cấp và tự động mở mạch khi đạt đến ngưỡng: -**ĐÃ ĐÓNG**(Khỏe mạnh) — Yêu cầu diễn ra bình thường -**OPEN**— Nhà cung cấp bị chặn tạm thời sau nhiều lần thất bại -**HALF_OPEN**— Kiểm tra xem nhà cung cấp đã phục hồi chưa
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**Chính sách & Mã định danh bị khóa**— Hiển thị trạng thái cầu dao và mã định danh bị khóa với khả năng buộc mở khóa.
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**Tự động phát hiện giới hạn tốc độ**— Giám sát tiêu đề `429` và `Thử lại sau` để chủ động tránh đạt giới hạn tốc độ của nhà cung cấp.
-
-**Mẹo chuyên nghiệp:**Sử dụng nút**Đặt lại tất cả**để xóa tất cả cầu dao và thời gian hồi chiêu khi nhà cung cấp khôi phục sau khi ngừng hoạt động.---
+---
### Database Export / Import
-Quản lý sao lưu cơ sở dữ liệu trong**Bảng điều khiển → Cài đặt → Hệ thống & Bộ lưu trữ**.
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| Hành động | Mô tả |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| **Xuất cơ sở dữ liệu** | Tải xuống cơ sở dữ liệu SQLite hiện tại dưới dạng tệp `.sqlite` |
-| **Xuất tất cả (.tar.gz)** | Tải xuống kho lưu trữ sao lưu đầy đủ bao gồm: cơ sở dữ liệu, cài đặt, tổ hợp, kết nối nhà cung cấp (không có thông tin xác thực), siêu dữ liệu khóa API |
-| **Nhập cơ sở dữ liệu** | Tải lên tệp `.sqlite` để thay thế cơ sở dữ liệu hiện tại. Bản sao lưu trước khi nhập sẽ được tạo tự động trừ khi `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**Xác thực nhập:**Tệp đã nhập được xác thực về tính toàn vẹn (kiểm tra pragma SQLite), các bảng bắt buộc (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) và kích thước (tối đa 100MB).
+**Use Cases:**
-**Trường hợp sử dụng:**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- Di chuyển OmniRoute giữa các máy
-- Tạo bản sao lưu bên ngoài để khắc phục thảm họa
-- Chia sẻ cấu hình giữa các thành viên trong nhóm (xuất tất cả → chia sẻ kho lưu trữ)---
+---
### Settings Dashboard
-Trang cài đặt được tổ chức thành 6 tab để dễ dàng điều hướng:
+The settings page is organized into 6 tabs for easy navigation:
-| Tab | Nội dung |
-| -------------- | -------------------------------------------------------------------------------------------------------------- |
-|**Chung**| Công cụ lưu trữ hệ thống, cài đặt giao diện, điều khiển chủ đề và khả năng hiển thị thanh bên cho mỗi mục |
-|**An ninh**| Cài đặt đăng nhập/mật khẩu, Kiểm soát truy cập IP, xác thực API cho `/models` và Chặn nhà cung cấp |
-|**Định tuyến**| Chiến lược định tuyến toàn cầu (6 tùy chọn), bí danh mô hình ký tự đại diện, chuỗi dự phòng, mặc định kết hợp |
-|**Khả năng phục hồi**| Hồ sơ nhà cung cấp, giới hạn tỷ lệ có thể chỉnh sửa, trạng thái ngắt mạch, chính sách và số nhận dạng bị khóa |
-|**AI**| Suy nghĩ về cấu hình ngân sách, tiêm nhắc hệ thống toàn cầu, thống kê bộ nhớ đệm nhanh chóng |
-|**Nâng cao**| Cấu hình proxy toàn cầu (HTTP/SOCKS5) |---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-Truy cập qua**Bảng điều khiển → Chi phí**.
+Access via **Dashboard → Costs**.
-| Tab | Mục đích |
+| Tab | Purpose |
| ----------- | ---------------------------------------------------------------------------------------- |
-|**Ngân sách**| Đặt giới hạn chi tiêu cho mỗi khóa API với ngân sách hàng ngày/hàng tuần/hàng tháng và theo dõi thời gian thực |
-|**Giá**| Xem và chỉnh sửa các mục định giá mô hình — chi phí cho mỗi 1K mã thông báo đầu vào/đầu ra cho mỗi nhà cung cấp |```bash
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -766,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**Theo dõi chi phí:**Mọi yêu cầu đều ghi lại việc sử dụng mã thông báo và tính toán chi phí bằng bảng giá. Xem thông tin chi tiết trong**Trang tổng quan → Mức sử dụng**theo nhà cung cấp, kiểu máy và khóa API.---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute hỗ trợ phiên âm âm thanh thông qua điểm cuối tương thích với OpenAI:```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-Các nhà cung cấp hiện có:**Deepgram**(`deepgram/`),**AssemblyAI**(`assemblyai/`).
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-Các định dạng âm thanh được hỗ trợ: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.---
+---
### Combo Balancing Strategies
-Định cấu hình cân bằng trên mỗi kết hợp trong**Bảng điều khiển → Tổ hợp → Tạo/Chỉnh sửa → Chiến lược**.
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-| Chiến lược | Mô tả |
+| Strategy | Description |
| ------------------ | ------------------------------------------------------------------------ |
-|**Vòng tròn**| Xoay qua các mô hình một cách tuần tự |
-|**Ưu tiên**| Luôn thử mẫu đầu tiên; chỉ quay lại khi có lỗi |
-|**Ngẫu nhiên**| Chọn một mô hình ngẫu nhiên từ combo cho mỗi yêu cầu |
-|**Có trọng số**| Các tuyến đường tương ứng dựa trên trọng số được chỉ định cho mỗi mô hình |
-|**Ít được sử dụng nhất**| Định tuyến đến mô hình có ít yêu cầu gần đây nhất (sử dụng số liệu kết hợp) |
-|**Tối ưu hóa chi phí**| Hướng đến mô hình có sẵn rẻ nhất (sử dụng bảng giá) |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-Mặc định kết hợp chung có thể được đặt trong**Bảng điều khiển → Cài đặt → Định tuyến → Mặc định kết hợp**.---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-Truy cập qua**Bảng điều khiển → Sức khỏe**. Tổng quan về tình trạng hệ thống theo thời gian thực với 6 thẻ:
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-| Thẻ | Nó hiển thị những gì |
-| --------------------- | ---------------------------------------------------------------------- |
-|**Trạng thái hệ thống**| Thời gian hoạt động, phiên bản, mức sử dụng bộ nhớ, thư mục dữ liệu |
-|**Sức khỏe của nhà cung cấp**| Trạng thái ngắt mạch của mỗi nhà cung cấp (Đóng/Mở/Nửa mở) |
-|**Giới hạn tỷ lệ**| Thời gian hồi chiêu giới hạn tốc độ kích hoạt cho mỗi tài khoản với thời gian còn lại |
-|**Khóa hoạt động**| Nhà cung cấp bị chặn tạm thời bởi chính sách khóa |
-|**Bộ nhớ đệm chữ ký**| Số liệu thống kê bộ đệm chống trùng lặp (khóa hoạt động, tỷ lệ truy cập) |
-|**Từ xa độ trễ**| tổng hợp độ trễ p50/p95/p99 cho mỗi nhà cung cấp |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**Mẹo chuyên nghiệp:**Trang Sức khỏe tự động làm mới sau mỗi 10 giây. Sử dụng thẻ ngắt mạch để xác định nhà cung cấp nào đang gặp sự cố.---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute có sẵn dưới dạng ứng dụng máy tính để bàn gốc dành cho Windows, macOS và Linux.### Cài đặt
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### Cài đặt
```bash
# From the electron directory:
@@ -834,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -846,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-Đầu ra → `electron/dist-electron/`### Key Features
+Output → `electron/dist-electron/`
-| Tính năng | Mô tả |
-| ------------------------------- | ------------------------------------------------------------------- | ------------------------- |
-| **Sẵn sàng cho máy chủ** | Máy chủ thăm dò trước khi hiển thị cửa sổ (không có màn hình trống) |
-| **Khay hệ thống** | Thu nhỏ về khay, thay đổi cổng, thoát khỏi menu khay |
-| **Quản lý cảng** | Thay đổi cổng máy chủ từ khay (máy chủ tự động khởi động lại) |
-| **Chính sách bảo mật nội dung** | CSP hạn chế thông qua tiêu đề phiên |
-| **Phiên bản đơn** | Mỗi lần chỉ có thể chạy một phiên bản ứng dụng |
-| **Chế độ ngoại tuyến** | Máy chủ Next.js đi kèm hoạt động mà không cần internet | ### Environment Variables |
+### Key Features
-| Biến | Mặc định | Mô tả |
-| --------------------- | -------- | ------------------------------------------------ |
-| `OMNIROUTE_PORT` | `20128` | Cổng máy chủ |
-| `OMNIROUTE_MEMORY_MB` | `512` | Giới hạn vùng nhớ heap của Node.js (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 Tài liệu đầy đủ: [`electron/README.md`](../electron/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)
diff --git a/docs/i18n/zh-CN/README.md b/docs/i18n/zh-CN/README.md
index 9c35c398a6..db9dcc8461 100644
--- a/docs/i18n/zh-CN/README.md
+++ b/docs/i18n/zh-CN/README.md
@@ -4,6 +4,7 @@
---
+
### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._
@@ -490,6 +491,7 @@ Developers who want all responses in a specific language, with a specific tone,
- **9 Routing Strategies** — Global strategies that determine how requests are distributed
- **Wildcard Router** — `provider/*` patterns route dynamically to any provider
- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard
+- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite
- **Provider Toggle** — Enable/disable all connections for a provider with one click
- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
@@ -778,6 +780,17 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
+### 2) Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
### Long-Running Streaming Timeouts
For most deployments, you only need:
diff --git a/docs/i18n/zh-CN/docs/USER_GUIDE.md b/docs/i18n/zh-CN/docs/USER_GUIDE.md
index 1cef41e5cf..a3446df58e 100644
--- a/docs/i18n/zh-CN/docs/USER_GUIDE.md
+++ b/docs/i18n/zh-CN/docs/USER_GUIDE.md
@@ -4,64 +4,74 @@
---
-有关配置提供商、创建组合、集成 CLI 工具和部署 OmniRoute 的完整指南。---
+
+
+Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
+
+---
## Table of Contents
-- [定价一览](#-pricing-at-a-glance)
-- [用例](#-use-cases)
-- [提供商设置](#-provider-setup)
-- [CLI 集成](#-cli-integration)
-- [部署](#-部署)
-- [可用型号](#-available-models)
-- [高级功能](#-advanced-features)---
+- [Pricing at a Glance](#-pricing-at-a-glance)
+- [Use Cases](#-use-cases)
+- [Provider Setup](#-provider-setup)
+- [CLI Integration](#-cli-integration)
+- [Deployment](#-deployment)
+- [Available Models](#-available-models)
+- [Advanced Features](#-advanced-features)
+
+---
## 💰 Pricing at a Glance
-| 等级 | 供应商 | 成本 | 配额重置 | 最适合 |
-| --------------- | ---------------------- | ------------------- | --------------- | -------------- |
-| **💳 订阅** | 克劳德代码（专业版） | $20/月 | 5 小时+ 每周 | 已经订阅 |
-| | Codex（增强版/专业版） | $20-200/月 | 5 小时+ 每周 | OpenAI 用户 |
-| | 双子座 CLI | **免费** | 180K/月 + 1K/天 | 每个人！ |
-| | GitHub 副驾驶 | $10-19/月 | 每月 | GitHub 用户 |
-| **🔑 API 密钥** | 深度搜索 | 按使用付费 | 无 | 廉价推理 |
-| | 格罗克 | 按使用付费 | 无 | 超快速推理 |
-| | xAI (Grok) | 按使用付费 | 无 | Grok 4 推理 |
-| | 米斯特拉尔 | 按使用付费 | 无 | 欧盟主办的模型 |
-| | 困惑 | 按使用付费 | 无 | 搜索增强 |
-| | 一起人工智能 | 按使用付费 | 无 | 开源模型 |
-| | 烟花人工智能 | 按使用付费 | 无 | 快速通量图像 |
-| | 大脑 | 按使用付费 | 无 | 晶圆级速度 |
-| | 连贯 | 按使用付费 | 无 | 命令 R+ RAG |
-| | NVIDIA NIM | 按使用付费 | 无 | 企业典范 |
-| **💰便宜** | GLM-4.7 | 0.6 美元/100 万美元 | 每日上午 10 点 | 预算备份 |
-| | 迷你最大M2.1 | 0.2 美元/100 万美元 | 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** | DeepSeek | Pay per use | None | Cheap reasoning |
+| | Groq | Pay per use | None | Ultra-fast inference |
+| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
+| | Mistral | Pay per use | None | EU-hosted models |
+| | Perplexity | Pay per use | None | Search-augmented |
+| | Together AI | Pay per use | None | Open-source models |
+| | Fireworks AI | Pay per use | None | Fast FLUX images |
+| | Cerebras | Pay per use | None | Wafer-scale speed |
+| | Cohere | Pay per use | None | Command R+ RAG |
+| | NVIDIA NIM | Pay per use | None | Enterprise models |
+| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
+| **🆓 FREE** | Qoder | $0 | Unlimited | 8 models free |
+| | Qwen | $0 | Unlimited | 3 models free |
+| | Kiro | $0 | Unlimited | Claude free |
-**💡专业提示：**从 Gemini CLI（180K 免费/月）+ Qoder（无限免费）组合开始 = 0 美元成本！---
+**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!
+
+---
## 🎯 Use Cases
### Case 1: "I have Claude Pro subscription"
-**问题：**未使用的配额过期，繁重编码期间的速率限制```
-Combo: "maximize-claude"
+**Problem:** Quota expires unused, rate limits during heavy coding
-1. cc/claude-opus-4-6 (use subscription fully)
-2. glm/glm-4.7 (cheap backup when quota out)
-3. if/kimi-k2-thinking (free emergency fallback)
+```
+Combo: "maximize-claude"
+ 1. cc/claude-opus-4-6 (use subscription fully)
+ 2. glm/glm-4.7 (cheap backup when quota out)
+ 3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
-
-````
+```
### Case 2: "I want zero cost"
-**问题：**无力订阅，需要可靠的人工智能编码```
+**Problem:** Can't afford subscriptions, need reliable AI coding
+
+```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
@@ -69,27 +79,29 @@ Combo: "free-forever"
Monthly cost: $0
Quality: Production-ready models
-````
+```
### Case 3: "I need 24/7 coding, no interruptions"
-**问题：**截止日期，无法承受停机时间```
-Combo: "always-on"
+**Problem:** Deadlines, can't afford downtime
-1. cc/claude-opus-4-6 (best quality)
-2. cx/gpt-5.2-codex (second subscription)
-3. glm/glm-4.7 (cheap, resets daily)
-4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
-5. if/kimi-k2-thinking (free unlimited)
+```
+Combo: "always-on"
+ 1. cc/claude-opus-4-6 (best quality)
+ 2. cx/gpt-5.2-codex (second subscription)
+ 3. glm/glm-4.7 (cheap, resets daily)
+ 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
+ 5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
-
-````
+```
### Case 4: "I want FREE AI in OpenClaw"
-**问题：**需要在消息应用程序中使用人工智能助手，完全免费```
+**Problem:** Need AI assistant in messaging apps, completely free
+
+```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
@@ -97,7 +109,7 @@ Combo: "openclaw-free"
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
-````
+```
---
@@ -118,7 +130,9 @@ Models:
cc/claude-haiku-4-5-20251001
```
-**专业提示：**使用 Opus 来完成复杂的任务，使用 Sonnet 来提高速度。 OmniRoute 跟踪每个模型的配额！#### OpenAI Codex (Plus/Pro)
+**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
+
+#### OpenAI Codex (Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
@@ -142,7 +156,9 @@ Models:
gc/gemini-2.5-pro
```
-**最超值：**巨大的免费套餐！在付费等级之前使用此功能。#### GitHub Copilot
+**Best Value:** Huge free tier! Use this before paid tiers.
+
+#### GitHub Copilot
```bash
Dashboard → Providers → Connect GitHub
@@ -159,17 +175,27 @@ Models:
#### GLM-4.7 (Daily reset, $0.6/1M)
-1、注册：【智普AI】(https://open.bigmodel.cn/) 2. 从 Coding Plan 获取 API 密钥 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` —**专业提示：**Coding Plan 以 1/7 的成本提供 3× 配额！每天上午 10:00 重置。#### MiniMax M2.1 (5h reset, $0.20/1M)
+**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
-1. 注册：[MiniMax](https://www.minimax.io/) 2.获取API密钥→仪表板→添加API密钥
+#### MiniMax M2.1 (5h reset, $0.20/1M)
-**使用：**`minimax/MiniMax-M2.1` —**专业提示：**长上下文的最便宜选择（1M 令牌）！#### Kimi K2 ($9/month flat)
+1. Sign up: [MiniMax](https://www.minimax.io/)
+2. Get API key → Dashboard → Add API Key
-1.订阅：【Moonshot AI】(https://platform.moonshot.ai/) 2.获取API密钥→仪表板→添加API密钥
+**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
-**使用：**`kimi/kimi-latest` —**专业提示：**固定 9 美元/月 1000 万个代币 = 0.90 美元/100 万有效成本！### 🆓 FREE Providers
+#### Kimi K2 ($9/month flat)
+
+1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
+2. Get API key → Dashboard → Add API Key
+
+**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
+
+### 🆓 FREE Providers
#### Qoder (8 FREE models)
@@ -199,6 +225,8 @@ Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
## 🎨 Combos
+You can reorder combo cards directly in **Dashboard → Combos** by dragging the handle on each card. The order is stored in SQLite and restored on reload.
+
### Example 1: Maximize Subscription → Cheap Backup
```
@@ -240,13 +268,14 @@ Settings → Models → Advanced:
### Claude Code
-编辑`~/.claude/config.json`：```json
-{
-"anthropic_api_base": "http://localhost:20128/v1",
-"anthropic_api_key": "your-omniroute-api-key"
-}
+Edit `~/.claude/config.json`:
-````
+```json
+{
+ "anthropic_api_base": "http://localhost:20128/v1",
+ "anthropic_api_key": "your-omniroute-api-key"
+}
+```
### Codex CLI
@@ -254,41 +283,42 @@ Settings → Models → Advanced:
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
-````
+```
### OpenClaw
-编辑`~/.openclaw/openclaw.json`：```json
+Edit `~/.openclaw/openclaw.json`:
+
+```json
{
-"agents": {
-"defaults": {
-"model": { "primary": "omniroute/if/glm-4.7" }
+ "agents": {
+ "defaults": {
+ "model": { "primary": "omniroute/if/glm-4.7" }
+ }
+ },
+ "models": {
+ "providers": {
+ "omniroute": {
+ "baseUrl": "http://localhost:20128/v1",
+ "apiKey": "your-omniroute-api-key",
+ "api": "openai-completions",
+ "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
+ }
+ }
+ }
}
-},
-"models": {
-"providers": {
-"omniroute": {
-"baseUrl": "http://localhost:20128/v1",
-"apiKey": "your-omniroute-api-key",
-"api": "openai-completions",
-"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
-}
-}
-}
-}
-
```
-**或使用仪表板：**CLI 工具 → OpenClaw → 自动配置### Cline / Continue / RooCode
+**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
+
+### Cline / Continue / RooCode
```
-
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
-
-````
+```
---
@@ -309,9 +339,22 @@ cp .env.example ~/.omniroute/.env
omniroute
# Or with custom port:
omniroute --port 3000
-````
+```
-CLI 自动从 `~/.omniroute/.env` 或 `./.env` 加载 `.env`。### VPS Deployment
+The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.
+
+### Uninstalling
+
+When you no longer need OmniRoute, we provide two quick scripts for a clean removal:
+
+| Command | Action |
+| --- | --- |
+| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |
+| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |
+
+> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`.
+
+### VPS Deployment
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
@@ -332,23 +375,22 @@ npm run start
### PM2 Deployment (Low Memory)
-对于 RAM 有限的服务器，请使用内存限制选项：```bash
+For servers with limited RAM, use the memory limit option:
+```bash
# With 512MB limit (default)
-
pm2 start npm --name omniroute -- start
# Or with custom memory limit
-
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start
# Or using ecosystem.config.js
-
pm2 start ecosystem.config.js
+```
-````
+Create `ecosystem.config.js`:
-创建 `ecosystem.config.js`：```javascript
+```javascript
module.exports = {
apps: [
{
@@ -366,7 +408,7 @@ module.exports = {
},
],
};
-````
+```
### Docker
@@ -378,13 +420,16 @@ docker build -t omniroute:cli .
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
-对于使用 CLI 二进制文件的主机集成模式，请参阅主文档中的 Docker 部分。### Void Linux (xbps-src)
+For host-integrated mode with CLI binaries, see the Docker section in the main docs.
-Void Linux 用户可以使用“xbps-src”交叉编译框架本地打包和安装 OmniRoute。这会自动执行 Node.js 独立构建以及所需的“better-sqlite3”本机绑定。
+### Void Linux (xbps-src)
-<详情>
+Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings.
-查看xbps-src模板```bash
+
+View xbps-src template
+
+```bash
# Template file for 'omniroute'
pkgname=omniroute
version=3.2.4
@@ -405,62 +450,61 @@ export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false
-do_build() { # Determine target CPU arch for node-gyp
-local \_gyp_arch
-case "$XBPS_TARGET_MACHINE" in
-aarch64*) \_gyp_arch=arm64 ;;
-armv7*|armv6*) \_gyp_arch=arm ;;
-i686*) \_gyp_arch=ia32 ;;
-\*) \_gyp_arch=x64 ;;
-esac
+do_build() {
+ # Determine target CPU arch for node-gyp
+ local _gyp_arch
+ case "$XBPS_TARGET_MACHINE" in
+ aarch64*) _gyp_arch=arm64 ;;
+ armv7*|armv6*) _gyp_arch=arm ;;
+ i686*) _gyp_arch=ia32 ;;
+ *) _gyp_arch=x64 ;;
+ esac
- # 1) Install all deps – skip scripts
- NODE_ENV=development npm ci --ignore-scripts
+ # 1) Install all deps – skip scripts
+ NODE_ENV=development npm ci --ignore-scripts
- # 2) Build the Next.js standalone bundle
- npm run build
+ # 2) Build the Next.js standalone bundle
+ npm run build
- # 3) Copy static assets into standalone
- cp -r .next/static .next/standalone/.next/static
- [ -d public ] && cp -r public .next/standalone/public || true
+ # 3) Copy static assets into standalone
+ cp -r .next/static .next/standalone/.next/static
+ [ -d public ] && cp -r public .next/standalone/public || true
- # 4) Compile better-sqlite3 native binding
- local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
- (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
+ # 4) Compile better-sqlite3 native binding
+ local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
+ (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")
- # 5) Place the compiled binding into the standalone bundle
- local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
- mkdir -p "$_bs3_release"
- cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
+ # 5) Place the compiled binding into the standalone bundle
+ local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
+ mkdir -p "$_bs3_release"
+ cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"
- # 6) Remove arch-specific sharp bundles
- rm -rf .next/standalone/node_modules/@img
-
- # 7) Copy pino runtime deps omitted by Next.js static analysis:
- for _mod in pino-abstract-transport split2 process-warning; do
- cp -r "node_modules/$_mod" .next/standalone/node_modules/
- done
+ # 6) Remove arch-specific sharp bundles
+ rm -rf .next/standalone/node_modules/@img
+ # 7) Copy pino runtime deps omitted by Next.js static analysis:
+ for _mod in pino-abstract-transport split2 process-warning; do
+ cp -r "node_modules/$_mod" .next/standalone/node_modules/
+ done
}
do_check() {
-npm run test:unit
+ npm run test:unit
}
do_install() {
-vmkdir usr/lib/omniroute/.next
-vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
+ vmkdir usr/lib/omniroute/.next
+ vcopy .next/standalone/. usr/lib/omniroute/.next/standalone
- # Prevent removal of empty Next.js app router dirs by the post-install hook
- for _d in \
- .next/standalone/.next/server/app/dashboard \
- .next/standalone/.next/server/app/dashboard/settings \
- .next/standalone/.next/server/app/dashboard/providers; do
- touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
- done
-
- cat > "${WRKDIR}/omniroute" <<'EOF'
+ # Prevent removal of empty Next.js app router dirs by the post-install hook
+ for _d in \
+ .next/standalone/.next/server/app/dashboard \
+ .next/standalone/.next/server/app/dashboard/settings \
+ .next/standalone/.next/server/app/dashboard/providers; do
+ touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
+ done
+ cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
@@ -472,80 +516,85 @@ EOF
}
post_install() {
-vlicense LICENSE
+ vlicense LICENSE
}
-
-````
+```
### Environment Variables
-|变量|默认 |描述 |
-| --------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
-| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT 签名秘密（**生产变更**）|
-| `初始密码` | `123456` |首次登录密码 |
-| `DATA_DIR` | `~/.omniroute` |数据目录（数据库、使用情况、日志）|
-| `端口` |框架默认|服务端口（示例中为“20128”）|
-| `主机名` |框架默认|绑定主机（Docker 默认为 `0.0.0.0`） |
-| `NODE_ENV` |运行时默认 |设置“生产”以进行部署 |
-| `BASE_URL` | `http://localhost:20128` |服务器端内部基本 URL |
-| `CLOUD_URL` | `https://omniroute.dev` |云同步端点基本 URL |
-| `API_KEY_SECRET` | `端点代理 API 密钥秘密` |生成的 API 密钥的 HMAC 秘密 |
-| `REQUIRE_API_KEY` | `假` |在 `/v1/*` 上强制执行 Bearer API 密钥 |
-| `ALLOW_API_KEY_REVEAL` | `假` |允许 Api Manager 按需复制完整的 API 密钥 |
-| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` |缓存的提供商限制数据的服务器端刷新节奏； UI 刷新按钮仍会触发手动同步 |
-| `DISABLE_SQLITE_AUTO_BACKUP` | `假` |在写入/导入/恢复之前禁用自动 SQLite 快照；手动备份仍然有效|
-| `启用请求日志` | `假` |启用请求/响应日志 |
-| `AUTH_COOKIE_SECURE` | `假` |强制“安全”身份验证 cookie（在 HTTPS 反向代理后面）|
-| `CLOUDFLARED_BIN` |取消设置 |使用现有的“cloudflared”二进制文件而不是托管下载 |
-| `CLOUDFLARED_PROTOCOL` | `http2` |托管快速隧道的传输（“http2”、“quic”或“auto”）|
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js 堆限制 (MB) |
-| `PROMPT_CACHE_MAX_SIZE` | `50` |最大提示缓存条目 |
-| `SEMANTIC_CACHE_MAX_SIZE` | `100` |最大语义缓存条目 |有关完整的环境变量参考，请参阅 [README](../README.md)。---
+| Variable | Default | Description |
+| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
+| `INITIAL_PASSWORD` | `123456` | First login password |
+| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
+| `PORT` | framework default | Service port (`20128` in examples) |
+| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
+| `NODE_ENV` | runtime default | Set `production` for deploy |
+| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
+| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
+| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
+| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
+| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |
+| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |
+| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |
+| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |
+| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
+| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |
+| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |
+| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |
+| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |
+
+For the full environment variable reference, see the [README](../README.md).
+
+---
## 📊 Available Models
-<详情>
-查看所有可用型号
+
+View all available models
-**克劳德代码 (`cc/`)**— Pro/Max：`cc/claude-opus-4-6`、`cc/claude-sonnet-4-5-20250929`、`cc/claude-haiku-4-5-20251001`
+**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
-**Codex (`cx/`)**— Plus/Pro：`cx/gpt-5.2-codex`、`cx/gpt-5.1-codex-max`
+**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
-**Gemini CLI (`gc/`)**— 免费：`gc/gemini-3-flash-preview`、`gc/gemini-2.5-pro`
+**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
-**GitHub Copilot (`gh/`)**：`gh/gpt-5`、`gh/claude-4.5-sonnet`
+**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
-**GLM (`glm/`)**— 0.6 美元/100 万美元：`glm/glm-4.7`
+**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
-**MiniMax (`minimax/`)**— $0.2/1M：`minimax/MiniMax-M2.1`
+**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
-**Qoder (`if/`)**— 免费：`if/kimi-k2-thinking`、`if/qwen3-coder-plus`、`if/deepseek-r1`
+**Qoder (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
-**Qwen (`qw/`)**— 免费：`qw/qwen3-coder-plus`、`qw/qwen3-coder-flash`
+**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
-**Kiro (`kr/`)**— 免费：`kr/claude-sonnet-4.5`、`kr/claude-haiku-4.5`
+**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
-**DeepSeek (`ds/`)**：`ds/deepseek-chat`、`ds/deepseek-reasoner`
+**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
-**Groq (`groq/`)**：`groq/llama-3.3-70b-versatile`、`groq/llama-4-maverick-17b-128e-instruct`
+**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
-**xAI (`xai/`)**：`xai/grok-4`、`xai/grok-4-0709-fast-reasoning`、`xai/grok-code-mini`
+**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
-**米斯特拉尔（`米斯特拉尔/`）**：`米斯特拉尔/米斯特拉尔-大-2501`，`米斯特拉尔/codestral-2501`
+**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
-**困惑（`pplx/`）**：`pplx/sonar-pro`、`pplx/sonar`
+**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
-**一起AI（`一起/`）**：`一起/meta-llama/Llama-3.3-70B-Instruct-Turbo`
+**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
-**Fireworks AI (`fireworks/`)**：`fireworks/accounts/fireworks/models/deepseek-v3p1`
+**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
-**Cerebras (`cerebras/`)**：`cerebras/llama-3.3-70b`
+**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
-**Cohere (`cohere/`)**：`cohere/command-r-plus-08-2024`
+**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
-**NVIDIA NIM (`nvidia/`)**：`nvidia/nvidia/llama-3.3-70b-instruct`
+**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
+
+
---
@@ -553,7 +602,9 @@ vlicense LICENSE
### Custom Models
-将任何模型 ID 添加到任何提供商，无需等待应用程序更新：```bash
+Add any model ID to any provider without waiting for an app update:
+
+```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
@@ -561,22 +612,28 @@ curl -X POST http://localhost:20128/api/provider-models \
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
-````
+```
-或者使用仪表板：**提供商 → [提供商] → 自定义模型**。
+Or use Dashboard: **Providers → [Provider] → Custom Models**.
-注意事项：
+Notes:
-- OpenRouter 和 OpenAI/Anthropic 兼容提供程序仅通过**可用模型**进行管理。手动添加、导入和自动同步都位于同一可用模型列表中，因此这些提供程序没有单独的自定义模型部分。-**自定义模型**部分适用于不公开托管可用模型导入的提供商。### Dedicated Provider Routes
+- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers.
+- The **Custom Models** section is intended for providers that do not expose managed available-model imports.
-通过模型验证将请求直接路由到特定提供者：```bash
+### Dedicated Provider Routes
+
+Route requests directly to a specific provider with model validation:
+
+```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
+```
-````
+The provider prefix is auto-added if missing. Mismatched models return `400`.
-如果缺少提供商前缀，则会自动添加。不匹配的模型返回“400”。### Network Proxy Configuration
+### Network Proxy Configuration
```bash
# Set global proxy
@@ -590,170 +647,203 @@ curl -X PUT http://localhost:20128/api/settings/proxy \
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
-````
+```
-**优先级：**特定于键→特定于组合→特定于提供者→全局→环境。### Model Catalog API
+**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
+
+### Model Catalog API
```bash
curl http://localhost:20128/api/models/catalog
```
-返回按类型（“聊天”、“嵌入”、“图像”）提供者分组的模型。### Cloud Sync
+Returns models grouped by provider with types (`chat`, `embedding`, `image`).
-- 跨设备同步提供商、组合和设置
-- 自动后台同步，带超时+快速失败
-- 在生产中更喜欢服务器端`BASE_URL`/`CLOUD_URL`### Cloudflare Quick Tunnel
+### Cloud Sync
-- 适用于 Docker 和其他自托管部署的**仪表板 → 端点**
-- 创建一个临时的“https://\*.trycloudflare.com” URL，转发到当前与 OpenAI 兼容的“/v1”端点
-- 首先启用仅在需要时安装“cloudflared”；稍后重新启动，重用相同的托管二进制文件
-- OmniRoute 或容器重新启动后，快速隧道不会自动恢复；需要时从仪表板重新启用它们
-- 隧道 URL 是短暂的，每次停止/启动隧道时都会发生变化
-- 托管快速隧道默认采用 HTTP/2 传输，以避免受限容器中出现嘈杂的 QUIC UDP 缓冲区警告
-- 如果您想覆盖托管传输选择，请设置“CLOUDFLARED_PROTOCOL=quic”或“auto”
-- 如果您更喜欢使用预安装的“cloudflared”二进制文件而不是托管下载，请设置“CLOUDFLARED_BIN”### LLM Gateway Intelligence (Phase 9)
+- Sync providers, combos, and settings across devices
+- Automatic background sync with timeout + fail-fast
+- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
--**语义缓存**— 自动缓存非流式传输、温度=0 响应（使用“X-OmniRoute-No-Cache: true”绕过）-**请求幂等性**— 通过“Idempotency-Key”或“X-Request-Id”标头在 5 秒内删除重复请求 -**进度跟踪**— 通过“X-OmniRoute-Progress: true”标头选择加入 SSE“event:progress”事件---
+### Cloudflare Quick Tunnel
+
+- Available in **Dashboard → Endpoints** for Docker and other self-hosted deployments
+- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint
+- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary
+- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed
+- Tunnel URLs are ephemeral and change every time you stop/start the tunnel
+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers
+- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice
+- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download
+
+### LLM Gateway Intelligence (Phase 9)
+
+- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
+- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
+- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
+
+---
### Translator Playground
-通过**仪表板 → 翻译器**访问。调试并可视化 OmniRoute 如何在提供者之间转换 API 请求。
+Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
-| 模式 | 目的 |
-| -------------- | ------------------------------------------------- |
-| **游乐场** | 选择源/目标格式，粘贴请求，然后立即查看翻译的输出 |
-| **聊天测试仪** | 通过代理发送实时聊天消息并检查完整的请求/响应周期 |
-| **测试台** | 跨多种格式组合运行批量测试以验证翻译的正确性 |
-| **实时监控** | 当请求流经代理时观看实时翻译 |
+| Mode | Purpose |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
+| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
+| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
+| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
-**使用案例：**
+**Use cases:**
-- 调试特定客户端/提供商组合失败的原因
-- 验证思维标签、工具调用和系统提示是否正确翻译
-- 比较 OpenAI、Claude、Gemini 和 Responses API 格式之间的格式差异---
+- Debug why a specific client/provider combination fails
+- Verify that thinking tags, tool calls, and system prompts translate correctly
+- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
+
+---
### Routing Strategies
-通过**仪表板→设置→路由**进行配置。
+Configure via **Dashboard → Settings → Routing**.
-| 战略 | 描述 |
-| ------------------------- | ------------------------------------------------------------------- | ----------------------------------- |
-| **先填写** | 按优先级顺序使用帐户 — 主帐户处理所有请求，直到不可用为止 |
-| **循环赛** | 循环浏览所有帐户，并具有可配置的粘性限制（默认：每个帐户 3 次调用） |
-| **P2C（两种选择的力量）** | 随机选择 2 个账户并选择更健康的账户 — 平衡负荷与健康意识 |
-| **随机** | 使用 Fisher-Yates shuffle 为每个请求随机选择一个帐户 |
-| **最少使用** | 路由到具有最早的“lastUsedAt”时间戳的帐户，均匀分配流量 |
-| **成本优化** | 路由至具有最低优先级值的帐户，针对成本最低的提供商进行优化 | #### External Sticky Session Header |
+| Strategy | Description |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
+| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
+| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
+| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
+| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
+| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
-对于外部会话关联（例如，反向代理后面的 Claude Code/Codex 代理），发送：```http
+#### External Sticky Session Header
+
+For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:
+
+```http
X-Session-Id: your-session-key
+```
-````
+OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.
-OmniRoute 还接受“x_session_id”并在“X-OmniRoute-Session-Id”中返回有效会话密钥。
+If you use Nginx and send underscore-form headers, enable:
-如果您使用 Nginx 并发送下划线形式的标头，请启用：```nginx
+```nginx
underscores_in_headers on;
-````
+```
#### Wildcard Model Aliases
-创建通配符模式来重新映射模型名称：```
-Pattern: claude-sonnet-_ → Target: cc/claude-sonnet-4-5-20250929
-Pattern: gpt-_ → Target: gh/gpt-5.1-codex
+Create wildcard patterns to remap model names:
-````
+```
+Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
+Pattern: gpt-* → Target: gh/gpt-5.1-codex
+```
-通配符支持“*”（任何字符）和“?”（单个字符）。#### Fallback Chains
+Wildcards support `*` (any characters) and `?` (single character).
-定义适用于所有请求的全局后备链：```
+#### Fallback Chains
+
+Define global fallback chains that apply across all requests:
+
+```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
-````
+```
---
### Resilience & Circuit Breakers
-通过**仪表板→设置→弹性**进行配置。
+Configure via **Dashboard → Settings → Resilience**.
-OmniRoute 通过四个组件实现提供商级弹性：
+OmniRoute implements provider-level resilience with four components:
-1.**提供商配置文件**— 每个提供商的配置：
+1. **Provider Profiles** — Per-provider configuration for:
+ - Failure threshold (how many failures before opening)
+ - Cooldown duration
+ - Rate limit detection sensitivity
+ - Exponential backoff parameters
-- 失败阈值（打开前有多少次失败）
-- 冷却时间
-- 速率限制检测灵敏度
-- 指数退避参数
+2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
+ - **Requests Per Minute (RPM)** — Maximum requests per minute per account
+ - **Min Time Between Requests** — Minimum gap in milliseconds between requests
+ - **Max Concurrent Requests** — Maximum simultaneous requests per account
+ - Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
- 2.**可编辑的速率限制**— 可在仪表板中配置的系统级默认值：-**每分钟请求数 (RPM)**— 每个帐户每分钟最大请求数 -**请求之间的最小时间**— 请求之间的最小间隔（以毫秒为单位）-**最大并发请求**— 每个帐户的最大并发请求数
+3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
+ - **CLOSED** (Healthy) — Requests flow normally
+ - **OPEN** — Provider is temporarily blocked after repeated failures
+ - **HALF_OPEN** — Testing if provider has recovered
-- 点击**编辑**进行修改，然后点击**保存**或**取消**。价值通过弹性 API 得以保留。
+4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
- 3.**断路器**— 跟踪每个提供商的故障并在达到阈值时自动打开电路：-**CLOSED**（健康）— 请求正常流动 -**OPEN**— 提供商在多次失败后被暂时阻止 -**HALF_OPEN**— 测试提供商是否已恢复
+5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
- 4.**策略和锁定标识符**— 显示断路器状态和具有强制解锁功能的锁定标识符。
+**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
- 5.**速率限制自动检测**— 监控“429”和“Retry-After”标头，以主动避免达到提供商速率限制。
-
-**专业提示：**当提供商从中断中恢复时，使用**全部重置**按钮可以清除所有断路器和冷却时间。---
+---
### Database Export / Import
-在**仪表板→设置→系统和存储**中管理数据库备份。
+Manage database backups in **Dashboard → Settings → System & Storage**.
-| 行动 | 描述 |
-| ---------------------- | -------------------------------------------------------------------------------------------------- | ------- |
-| **导出数据库** | 将当前 SQLite 数据库下载为“.sqlite”文件 |
-| **全部导出 (.tar.gz)** | 下载完整的备份存档，包括：数据库、设置、组合、提供商连接（无凭据）、API 密钥元数据 |
-| **导入数据库** | 上传`.sqlite`文件来替换当前数据库。除非`DISABLE_SQLITE_AUTO_BACKUP=true`，否则会自动创建导入前备份 | ```bash |
+| Action | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
+| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
+| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |
+```bash
# API: Export database
-
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
-
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
-
curl -X POST http://localhost:20128/api/db-backups/import \
- -F "file=@backup.sqlite"
+ -F "file=@backup.sqlite"
+```
-````
+**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
-**导入验证：**验证导入文件的完整性（SQLite 编译指示检查）、所需表（“provider_connections”、“provider_nodes”、“combos”、“api_keys”）和大小（最大 100MB）。
+**Use Cases:**
-**使用案例：**
+- Migrate OmniRoute between machines
+- Create external backups for disaster recovery
+- Share configurations between team members (export all → share archive)
-- 在机器之间迁移 OmniRoute
-- 创建外部备份以进行灾难恢复
-- 在团队成员之间共享配置（导出全部→共享存档）---
+---
### Settings Dashboard
-设置页面分为 6 个选项卡，以便于导航：
+The settings page is organized into 6 tabs for easy navigation:
-|选项卡|内容 |
-| -------------- | ---------------------------------------------------------------------------------------------------------- |
-|**一般**|系统存储工具、外观设置、主题控件和每个项目的侧边栏可见性 |
-|**安全**|登录/密码设置、IP 访问控制、`/models` 的 API 身份验证和提供商阻止 |
-|**路由**|全局路由策略（6 个选项）、通配符模型别名、后备链、组合默认值 |
-|**弹性**|提供商资料、可编辑的速率限制、断路器状态、策略和锁定标识符 |
-|**人工智能**|思维预算配置、全局系统提示注入、提示缓存统计|
-|**高级**|全局代理配置（HTTP/SOCKS5）|---
+| Tab | Contents |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |
+| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |
+| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
+| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
+| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
+| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
+
+---
### Costs & Budget Management
-通过**仪表板 → 成本**访问。
+Access via **Dashboard → Costs**.
-|选项卡|目的|
-| ----------- | ---------------------------------------------------------------------------------------------------- |
-|**预算**|通过每日/每周/每月预算和实时跟踪设置每个 API 密钥的支出限额 |
-|**定价**|查看和编辑模型定价条目 - 每个提供商每 1K 输入/输出代币的成本 |```bash
+| Tab | Purpose |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
+| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
+
+```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
@@ -761,63 +851,73 @@ curl -X POST http://localhost:20128/api/usage/budget \
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
-````
+```
-**成本跟踪：**每个请求都会记录令牌使用情况并使用定价表计算成本。按提供商、型号和 API 密钥查看**仪表板 → 使用情况**中的细分。---
+**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
+
+---
### Audio Transcription
-OmniRoute 支持通过 OpenAI 兼容端点进行音频转录：```bash
+OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
+
+```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
-
curl -X POST http://localhost:20128/v1/audio/transcriptions \
- -H "Authorization: Bearer your-api-key" \
- -F "file=@audio.mp3" \
- -F "model=deepgram/nova-3"
+ -H "Authorization: Bearer your-api-key" \
+ -F "file=@audio.mp3" \
+ -F "model=deepgram/nova-3"
+```
-````
+Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
-可用的提供程序：**Deepgram**(`deepgram/`)、**AssemblyAI**(`assembleai/`)。
+Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
-支持的音频格式：`mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm`。---
+---
### Combo Balancing Strategies
-在**仪表板→组合→创建/编辑→策略**中配置每个组合的平衡。
+Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
-|战略|描述 |
-| ------------------ | ------------------------------------------------------------------------------------ |
-|**循环赛**|按顺序轮换模型 |
-|**优先**|总是尝试第一个模型；仅在错误时才回退 |
-|**随机**|为每个请求从组合中选择一个随机模型 |
-|**加权**|根据每个模型分配的权重按比例路由 |
-|**最少使用**|路由到最近请求最少的模型（使用组合指标）|
-|**成本优化**|通往最便宜可用型号的路线（使用定价表）|
+| Strategy | Description |
+| ------------------ | ------------------------------------------------------------------------ |
+| **Round-Robin** | Rotates through models sequentially |
+| **Priority** | Always tries the first model; falls back only on error |
+| **Random** | Picks a random model from the combo for each request |
+| **Weighted** | Routes proportionally based on assigned weights per model |
+| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
+| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
-全局组合默认值可以在**仪表板→设置→路由→组合默认值**中设置。---
+Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
+
+---
### Health Dashboard
-通过**仪表板→健康**访问。 6张卡实时系统健康概览：
+Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
-|卡|它显示了什么 |
-| -------------------- | ----------------------------------------------------------- |
-|**系统状态**|正常运行时间、版本、内存使用情况、数据目录 |
-|**提供者健康**|每个提供商的断路器状态（闭合/打开/半开）|
-|**速率限制**|每个帐户的活动速率限制冷却时间和剩余时间 |
-|**主动锁定**| Providers temporarily blocked by the lockout policy |
-|**签名缓存**|重复数据删除缓存统计信息（活动键、命中率）|
-|**延迟遥测**|每个提供商的 p50/p95/p99 延迟聚合 |
+| Card | What It Shows |
+| --------------------- | ----------------------------------------------------------- |
+| **System Status** | Uptime, version, memory usage, data directory |
+| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
+| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
+| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
+| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
+| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
-**专业提示：**健康页面每 10 秒自动刷新一次。使用断路器卡来识别哪些提供商遇到问题。---
+**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
+
+---
## 🖥️ Desktop Application (Electron)
-OmniRoute 可作为 Windows、macOS 和 Linux 的本机桌面应用程序使用。### 安装
+OmniRoute is available as a native desktop application for Windows, macOS, and Linux.
+
+### 安装
```bash
# From the electron directory:
@@ -829,7 +929,7 @@ npm run dev
# Production mode (uses standalone build):
npm start
-````
+```
### Building Installers
@@ -841,20 +941,24 @@ npm run build:mac # macOS (.dmg universal)
npm run build:linux # Linux (.AppImage)
```
-输出 → `电子/离散电子/`### Key Features
+Output → `electron/dist-electron/`
-|特色|描述 |
-| ------------------------ | | ---------------------------------------------------------------- |
-|**服务器准备情况**|在显示窗口之前轮询服务器（无空白屏幕）|
-|**系统托盘**|最小化到托盘、更改端口、从托盘菜单退出 |
-|**港口管理**|从托盘更改服务器端口（自动重新启动服务器）|
-|**内容安全政策**|通过会话标头限制性 CSP |
-|**单实例**|一次只能运行一个应用程序实例 |
-|**离线模式**|捆绑的 Next.js 服务器无需互联网即可工作 |### Environment Variables
+### Key Features
-| 变量 | 默认 | 描述 |
-| --------------------- | ------- | ---------------------------- |
-| `OMNIROUTE_PORT` | `20128` | 服务器端口 |
-| `OMNIROUTE_MEMORY_MB` | `512` | Node.js 堆限制 (64–16384 MB) |
+| Feature | Description |
+| --------------------------- | ---------------------------------------------------- |
+| **Server Readiness** | Polls server before showing window (no blank screen) |
+| **System Tray** | Minimize to tray, change port, quit from tray menu |
+| **Port Management** | Change server port from tray (auto-restarts server) |
+| **Content Security Policy** | Restrictive CSP via session headers |
+| **Single Instance** | Only one app instance can run at a time |
+| **Offline Mode** | Bundled Next.js server works without internet |
-📖 完整文档：[`电子/README.md`](../电子/README.md)
+### Environment Variables
+
+| Variable | Default | Description |
+| --------------------- | ------- | -------------------------------- |
+| `OMNIROUTE_PORT` | `20128` | Server port |
+| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64–16384 MB) |
+
+📖 Full documentation: [`electron/README.md`](../electron/README.md)