{"repo": "calicksfoxs-droid/smart-api-gateway-omni", "files": {"tests/snapshots/provider/translate-path.json": {"df4fa8e65b6d5e5876dcecd5a0eec84928b2be31": {"t": 1785674319.67871, "n": 133845, "h": "1589b9224009e066", "c": "{\n \"adapta-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://agent.adapta.one/api/chat/stream/v1\",\n \"stream\": \"https://agent.adapta.one/api/chat/stream/v1\"\n }\n },\n \"agentrouter\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"claude-cli/2.1.207 (external, sdk-cli)\",\n \"X-Stainless-Arch\": \"\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-OS\": \"MacOS\",\n \"X-Stainless-Package-Version\": \"0.94.0\",\n \"X-Stainless-Retry-Count\": \"0\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"v24.3.0\",\n \"X-Stainless-Timeout\": \"600\",\n \"accept-encoding\": \"gzip, deflate, br, zstd\",\n \"anthropic-beta\": \"claude-code-20250219,interleaved-thinking-2025-05-14,effort-2025-11-24\",\n \"anthropic-dangerous-direct-browser-access\": \"true\",\n \"anthropic-version\": \"2023-06-01\",\n \"x-api-key\": \"\",\n \"x-app\": \"cli\"\n },\n \"nonStream\": {\n \"Accept\": \"application/json\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"claude-cli/2.1.207 (external, sdk-cli)\",\n \"X-Stainless-Arch\": \"\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-OS\": \"MacOS\",\n \"X-Stainless-Package-Version\": \"0.94.0\",\n \"X-Stainless-Retry-Count\": \"0\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"v24.3.0\",\n \"X-Stainless-Timeout\": \"600\",\n \"accept-encoding\": \"gzip, deflate, br, zstd\",\n \"anthropic-beta\": \"claude-code-20250219,interleaved-thinking-2025-05-14,effort-2025-11-24\",\n \"anthropic-dangerous-direct-browser-access\": \"true\",\n \"anthropic-version\": \"2023-06-01\",\n \"x-api-key\": \"\",\n \"x-app\": \"cli\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"claude-cli/2.1.207 (external, sdk-cli)\",\n \"X-Stainless-Arch\": \"\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-OS\": \"MacOS\",\n \"X-Stainless-Package-Version\": \"0.94.0\",\n \"X-Stainless-Retry-Count\": \"0\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"v24.3.0\",\n \"X-Stainless-Timeout\": \"600\",\n \"accept-encoding\": \"gzip, deflate, br, zstd\",\n \"anthropic-beta\": \"claude-code-20250219,interleaved-thinking-2025-05-14,effort-2025-11-24\",\n \"anthropic-dangerous-direct-browser-access\": \"true\",\n \"anthropic-version\": \"2023-06-01\",\n \"x-api-key\": \"\",\n \"x-app\": \"cli\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://agentrouter.org/v1/messages?beta=true\",\n \"stream\": \"https://agentrouter.org/v1/messages?beta=true\"\n }\n },\n \"agy\": {\n \"format\": \"antigravity\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Antigravity/4.2.0 () Chrome/142.0.7444.175 Electron/39.2.3\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Antigravity/4.2.0 () Chrome/142.0.7444.175 Electron/39.2.3\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Antigravity/4.2.0 () Chrome/142.0.7444.175 Electron/39.2.3\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://daily-cloudcode-pa.googleapis.com/v1internal:generateContent\",\n \"stream\": \"https://daily-cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse\"\n }\n },\n \"ai21\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.ai21.com/studio/v1/chat/completions\",\n \"stream\": \"https://api.ai21.com/studio/v1/chat/completions\"\n }\n },\n \"aimlapi\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.aimlapi.com/v1/chat/completions\",\n \"stream\": \"https://api.aimlapi.com/v1/chat/completions\"\n }\n },\n \"alibaba\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions\",\n \"stream\": \"https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions\"\n }\n },\n \"alibaba-cn\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions\",\n \"stream\": \"https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions\"\n }\n },\n \"anthropic\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Beta\": \"claude-code-20250219,interleaved-thinking-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28,advisor-tool-2026-03-01,extended-cache-ttl-2025-04-11,cache-diagnosis-2026-04-07\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n },\n \"nonStream\": {\n \"Anthropic-Beta\": \"claude-code-20250219,interleaved-thinking-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28,advisor-tool-2026-03-01,extended-cache-ttl-2025-04-11,cache-diagnosis-2026-04-07\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Beta\": \"claude-code-20250219,interleaved-thinking-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28,advisor-tool-2026-03-01,extended-cache-ttl-2025-04-11,cache-diagnosis-2026-04-07\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.anthropic.com/v1/messages?beta=true\",\n \"stream\": \"https://api.anthropic.com/v1/messages?beta=true\"\n }\n },\n \"antigravity\": {\n \"format\": \"antigravity\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Antigravity/4.2.0 () Chrome/142.0.7444.175 Electron/39.2.3\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Antigravity/4.2.0 () Chrome/142.0.7444.175 Electron/39.2.3\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Antigravity/4.2.0 () Chrome/142.0.7444.175 Electron/39.2.3\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://daily-cloudcode-pa.googleapis.com/v1internal:generateContent\",\n \"stream\": \"https://daily-cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse\"\n }\n },\n \"api-airforce\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.airforce/v1/chat/completions\",\n \"stream\": \"https://api.airforce/v1/chat/completions\"\n }\n },\n \"auggie\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"auggie://cli/stdio\",\n \"stream\": \"auggie://cli/stdio\"\n }\n },\n \"bai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.b.ai/v1/chat/completions\",\n \"stream\": \"https://api.b.ai/v1/chat/completions\"\n }\n },\n \"baichuan\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.baichuan-ai.com/v1/chat/completions\",\n \"stream\": \"https://api.baichuan-ai.com/v1/chat/completions\"\n }\n },\n \"baidu\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://qianfan.baidubce.com/v2/chat/completions\",\n \"stream\": \"https://qianfan.baidubce.com/v2/chat/completions\"\n }\n },\n \"bailian-coding-plan\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n },\n \"nonStream\": {\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://coding-intl.dashscope.aliyuncs.com/apps/anthropic/v1\",\n \"stream\": \"https://coding-intl.dashscope.aliyuncs.com/apps/anthropic/v1\"\n }\n },\n \"baseten\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://inference.baseten.co/v1/chat/completions\",\n \"stream\": \"https://inference.baseten.co/v1/chat/completions\"\n }\n },\n \"bazaarlink\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://bazaarlink.ai/api/v1/chat/completions\",\n \"stream\": \"https://bazaarlink.ai/api/v1/chat/completions\"\n }\n },\n \"bedrock\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {}\n },\n \"blackbox\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.blackbox.ai/v1/chat/completions\",\n \"stream\": \"https://api.blackbox.ai/v1/chat/completions\"\n }\n },\n \"blackbox-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://app.blackbox.ai/api/chat\",\n \"stream\": \"https://app.blackbox.ai/api/chat\"\n }\n },\n \"bluesminds\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.bluesminds.com/v1/chat/completions\",\n \"stream\": \"https://api.bluesminds.com/v1/chat/completions\"\n }\n },\n \"byteplus\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://ark.ap-southeast.bytepluses.com/api/v3/chat/completions\",\n \"stream\": \"https://ark.ap-southeast.bytepluses.com/api/v3/chat/completions\"\n }\n },\n \"bytez\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.bytez.com/models/v2/openai/v1/chat/completions\",\n \"stream\": \"https://api.bytez.com/models/v2/openai/v1/chat/completions\"\n }\n },\n \"cerebras\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.cerebras.ai/v1/chat/completions\",\n \"stream\": \"https://api.cerebras.ai/v1/chat/completions\"\n }\n },\n \"charm-hyper\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://hyper.charm.land/v1/chat/completions\",\n \"stream\": \"https://hyper.charm.land/v1/chat/completions\"\n }\n },\n \"chatgpt-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://chatgpt.com/backend-api/conversation\",\n \"stream\": \"https://chatgpt.com/backend-api/conversation\"\n }\n },\n \"chipotle\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://amelia.chipotle.com\",\n \"stream\": \"https://amelia.chipotle.com\"\n }\n },\n \"chutes\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.chutesai.com/v1/chat/completions\",\n \"stream\": \"https://api.chutesai.com/v1/chat/completions\"\n }\n },\n \"claude\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Beta\": \"claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28,advisor-tool-2026-03-01,extended-cache-ttl-2025-04-11,cache-diagnosis-2026-04-07\",\n \"Anthropic-Dangerous-Direct-Browser-Access\": \"true\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"claude-cli/2.1.207 (external, cli)\",\n \"X-App\": \"cli\",\n \"X-Stainless-Arch\": \"\",\n \"X-Stainless-Helper-Method\": \"stream\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-Os\": \"\",\n \"X-Stainless-Package-Version\": \"0.94.0\",\n \"X-Stainless-Retry-Count\": \"0\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"v24.3.0\",\n \"X-Stainless-Timeout\": \"600\",\n \"x-api-key\": \"\"\n },\n \"nonStream\": {\n \"Anthropic-Beta\": \"claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28,advisor-tool-2026-03-01,extended-cache-ttl-2025-04-11,cache-diagnosis-2026-04-07\",\n \"Anthropic-Dangerous-Direct-Browser-Access\": \"true\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"claude-cli/2.1.207 (external, cli)\",\n \"X-App\": \"cli\",\n \"X-Stainless-Arch\": \"\",\n \"X-Stainless-Helper-Method\": \"stream\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-Os\": \"\",\n \"X-Stainless-Package-Version\": \"0.94.0\",\n \"X-Stainless-Retry-Count\": \"0\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"v24.3.0\",\n \"X-Stainless-Timeout\": \"600\",\n \"x-api-key\": \"\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Beta\": \"claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,structured-outputs-2025-12-15,fast-mode-2026-02-01,redact-thinking-2026-02-12,token-efficient-tools-2026-03-28,advisor-tool-2026-03-01,extended-cache-ttl-2025-04-11,cache-diagnosis-2026-04-07\",\n \"Anthropic-Dangerous-Direct-Browser-Access\": \"true\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"claude-cli/2.1.207 (external, cli)\",\n \"X-App\": \"cli\",\n \"X-Stainless-Arch\": \"\",\n \"X-Stainless-Helper-Method\": \"stream\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-Os\": \"\",\n \"X-Stainless-Package-Version\": \"0.94.0\",\n \"X-Stainless-Retry-Count\": \"0\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"v24.3.0\",\n \"X-Stainless-Timeout\": \"600\",\n \"x-api-key\": \"\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.anthropic.com/v1/messages?beta=true\",\n \"stream\": \"https://api.anthropic.com/v1/messages?beta=true\"\n }\n },\n \"claude-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://claude.ai/api/organizations\",\n \"stream\": \"https://claude.ai/api/organizations\"\n }\n },\n \"cline\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://cline.bot\",\n \"User-Agent\": \"OmniRoute/\",\n \"X-CLIENT-TYPE\": \"omniroute\",\n \"X-CLIENT-VERSION\": \"\",\n \"X-CORE-VERSION\": \"\",\n \"X-IS-MULTIROOT\": \"false\",\n \"X-PLATFORM\": \"\",\n \"X-PLATFORM-VERSION\": \"\",\n \"X-Title\": \"Cline\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://cline.bot\",\n \"User-Agent\": \"OmniRoute/\",\n \"X-CLIENT-TYPE\": \"omniroute\",\n \"X-CLIENT-VERSION\": \"\",\n \"X-CORE-VERSION\": \"\",\n \"X-IS-MULTIROOT\": \"false\",\n \"X-PLATFORM\": \"\",\n \"X-PLATFORM-VERSION\": \"\",\n \"X-Title\": \"Cline\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://cline.bot\",\n \"User-Agent\": \"OmniRoute/\",\n \"X-CLIENT-TYPE\": \"omniroute\",\n \"X-CLIENT-VERSION\": \"\",\n \"X-CORE-VERSION\": \"\",\n \"X-IS-MULTIROOT\": \"false\",\n \"X-PLATFORM\": \"\",\n \"X-PLATFORM-VERSION\": \"\",\n \"X-Title\": \"Cline\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.cline.bot/api/v1/chat/completions\",\n \"stream\": \"https://api.cline.bot/api/v1/chat/completions\"\n }\n },\n \"clinepass\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://cline.bot\",\n \"X-Title\": \"Cline\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://cline.bot\",\n \"X-Title\": \"Cline\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://cline.bot\",\n \"X-Title\": \"Cline\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.cline.bot/api/v1/chat/completions\",\n \"stream\": \"https://api.cline.bot/api/v1/chat/completions\"\n }\n },\n \"cloudflare-ai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.cloudflare.com/client/v4/accounts\",\n \"stream\": \"https://api.cloudflare.com/client/v4/accounts\"\n }\n },\n \"codebuddy-cn\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"CLI/2.108.1 CodeBuddy/2.108.1\",\n \"X-IDE-Name\": \"CLI\",\n \"X-IDE-Type\": \"CLI\",\n \"X-Product\": \"SaaS\",\n \"x-codebuddy-request\": \"1\",\n \"x-requested-with\": \"XMLHttpRequest\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"CLI/2.108.1 CodeBuddy/2.108.1\",\n \"X-IDE-Name\": \"CLI\",\n \"X-IDE-Type\": \"CLI\",\n \"X-Product\": \"SaaS\",\n \"x-codebuddy-request\": \"1\",\n \"x-requested-with\": \"XMLHttpRequest\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"CLI/2.108.1 CodeBuddy/2.108.1\",\n \"X-IDE-Name\": \"CLI\",\n \"X-IDE-Type\": \"CLI\",\n \"X-Product\": \"SaaS\",\n \"x-codebuddy-request\": \"1\",\n \"x-requested-with\": \"XMLHttpRequest\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://copilot.tencent.com/v2/chat/completions\",\n \"stream\": \"https://copilot.tencent.com/v2/chat/completions\"\n }\n },\n \"codestral\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://codestral.mistral.ai/v1/chat/completions\",\n \"stream\": \"https://codestral.mistral.ai/v1/chat/completions\"\n }\n },\n \"codex\": {\n \"format\": \"openai-responses\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"Openai-Beta\": \"responses=experimental\",\n \"User-Agent\": \"codex-cli/0.144.1 (; )\",\n \"Version\": \"0.144.1\",\n \"X-Codex-Beta-Features\": \"responses_websockets\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"Openai-Beta\": \"responses=experimental\",\n \"User-Agent\": \"codex-cli/0.144.1 (; )\",\n \"Version\": \"0.144.1\",\n \"X-Codex-Beta-Features\": \"responses_websockets\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"Openai-Beta\": \"responses=experimental\",\n \"User-Agent\": \"codex-cli/0.144.1 (; )\",\n \"Version\": \"0.144.1\",\n \"X-Codex-Beta-Features\": \"responses_websockets\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://chatgpt.com/backend-api/codex/responses\",\n \"stream\": \"https://chatgpt.com/backend-api/codex/responses\"\n }\n },\n \"cohere\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.cohere.com/compatibility/v1/chat/completions\",\n \"stream\": \"https://api.cohere.com/compatibility/v1/chat/completions\"\n }\n },\n \"command-code\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.commandcode.ai\",\n \"stream\": \"https://api.commandcode.ai\"\n }\n },\n \"copilot-m365-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"wss://substrate.office.com/m365Copilot/Chathub\",\n \"stream\": \"wss://substrate.office.com/m365Copilot/Chathub\"\n }\n },\n \"copilot-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"wss://copilot.microsoft.com/c/api/chat?api-version=2\",\n \"stream\": \"wss://copilot.microsoft.com/c/api/chat?api-version=2\"\n }\n },\n \"coze\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.coze.com/v1/chat/completions\",\n \"stream\": \"https://api.coze.com/v1/chat/completions\"\n }\n },\n \"crof\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://crof.ai/v1/chat/completions\",\n \"stream\": \"https://crof.ai/v1/chat/completions\"\n }\n },\n \"cursor\": {\n \"format\": \"cursor\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/connect+proto\",\n \"User-Agent\": \"Cursor/3.9\",\n \"connect-accept-encoding\": \"gzip\",\n \"connect-protocol-version\": \"1\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/connect+proto\",\n \"User-Agent\": \"Cursor/3.9\",\n \"connect-accept-encoding\": \"gzip\",\n \"connect-protocol-version\": \"1\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/connect+proto\",\n \"User-Agent\": \"Cursor/3.9\",\n \"connect-accept-encoding\": \"gzip\",\n \"connect-protocol-version\": \"1\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api2.cursor.sh\",\n \"stream\": \"https://api2.cursor.sh\"\n }\n },\n \"databricks\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://adb-0000000000000000.0.azuredatabricks.net/serving-endpoints\",\n \"stream\": \"https://adb-0000000000000000.0.azuredatabricks.net/serving-endpoints\"\n }\n },\n \"deepinfra\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.deepinfra.com/v1/openai/chat/completions\",\n \"stream\": \"https://api.deepinfra.com/v1/openai/chat/completions\"\n }\n },\n \"deepseek\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.deepseek.com/v1/chat/completions\",\n \"stream\": \"https://api.deepseek.com/v1/chat/completions\"\n }\n },\n \"deepseek-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://chat.deepseek.com/api/v0/chat/completion\",\n \"stream\": \"https://chat.deepseek.com/api/v0/chat/completion\"\n }\n },\n \"devin-cli\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"devin://acp/stdio\",\n \"stream\": \"devin://acp/stdio\"\n }\n },\n \"dgrid\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.dgrid.ai/v1/chat/completions\",\n \"stream\": \"https://api.dgrid.ai/v1/chat/completions\"\n }\n },\n \"dify\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.dify.ai/v1/chat/completions\",\n \"stream\": \"https://api.dify.ai/v1/chat/completions\"\n }\n },\n \"digitalocean\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://inference.do-ai.run/v1/chat/completions\",\n \"stream\": \"https://inference.do-ai.run/v1/chat/completions\"\n }\n },\n \"dit\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.dit.ai/v1/chat/completions\",\n \"stream\": \"https://api.dit.ai/v1/chat/completions\"\n }\n },\n \"doubao\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://ark.cn-beijing.volces.com/api/v3/chat/completions\",\n \"stream\": \"https://ark.cn-beijing.volces.com/api/v3/chat/completions\"\n }\n },\n \"doubao-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://www.dola.com/chat/completion\",\n \"stream\": \"https://www.dola.com/chat/completion\"\n }\n },\n \"duckduckgo-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://duckduckgo.com/duckchat/v1/chat\",\n \"stream\": \"https://duckduckgo.com/duckchat/v1/chat\"\n }\n },\n \"factory\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.factory.ai/v1/chat/completions\",\n \"stream\": \"https://api.factory.ai/v1/chat/completions\"\n }\n },\n \"featherless-ai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.featherless.ai/v1/chat/completions\",\n \"stream\": \"https://api.featherless.ai/v1/chat/completions\"\n }\n },\n \"fireworks\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.fireworks.ai/inference/v1/chat/completions\",\n \"stream\": \"https://api.fireworks.ai/inference/v1/chat/completions\"\n }\n },\n \"freeaiapikey\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://freeaiapikey.com/v1/chat/completions\",\n \"stream\": \"https://freeaiapikey.com/v1/chat/completions\"\n }\n },\n \"freemodel-dev\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.freemodel.dev/v1/chat/completions\",\n \"stream\": \"https://api.freemodel.dev/v1/chat/completions\"\n }\n },\n \"friendliai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.friendli.ai/serverless/v1/chat/completions\",\n \"stream\": \"https://api.friendli.ai/serverless/v1/chat/completions\"\n }\n },\n \"galadriel\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.galadriel.ai/v1/chat/completions\",\n \"stream\": \"https://api.galadriel.ai/v1/chat/completions\"\n }\n },\n \"gemini\": {\n \"format\": \"gemini\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Content-Type\": \"application/json\",\n \"x-goog-api-key\": \"\"\n },\n \"nonStream\": {\n \"Content-Type\": \"application/json\",\n \"x-goog-api-key\": \"\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://generativelanguage.googleapis.com/v1beta/models/test-model:generateContent\",\n \"stream\": \"https://generativelanguage.googleapis.com/v1beta/models/test-model:streamGenerateContent?alt=sse\"\n }\n },\n \"gemini-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://gemini.google.com/app\",\n \"stream\": \"https://gemini.google.com/app\"\n }\n },\n \"gigachat\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://gigachat.devices.sberbank.ru/api/v1\",\n \"stream\": \"https://gigachat.devices.sberbank.ru/api/v1\"\n }\n },\n \"github\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"X-Initiator\": \"user\",\n \"copilot-integration-id\": \"vscode-chat\",\n \"editor-plugin-version\": \"copilot-chat/0.54.0\",\n \"editor-version\": \"vscode/1.126.0\",\n \"openai-intent\": \"conversation-panel\",\n \"user-agent\": \"GitHubCopilotChat/0.54.0\",\n \"x-github-api-version\": \"2026-06-01\",\n \"x-request-id\": \"\",\n \"x-vscode-user-agent-library-version\": \"electron-fetch\"\n },\n \"nonStream\": {\n \"Accept\": \"application/json\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"X-Initiator\": \"user\",\n \"copilot-integration-id\": \"vscode-chat\",\n \"editor-plugin-version\": \"copilot-chat/0.54.0\",\n \"editor-version\": \"vscode/1.126.0\",\n \"openai-intent\": \"conversation-panel\",\n \"user-agent\": \"GitHubCopilotChat/0.54.0\",\n \"x-github-api-version\": \"2026-06-01\",\n \"x-request-id\": \"\",\n \"x-vscode-user-agent-library-version\": \"electron-fetch\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"X-Initiator\": \"user\",\n \"copilot-integration-id\": \"vscode-chat\",\n \"editor-plugin-version\": \"copilot-chat/0.54.0\",\n \"editor-version\": \"vscode/1.126.0\",\n \"openai-intent\": \"conversation-panel\",\n \"user-agent\": \"GitHubCopilotChat/0.54.0\",\n \"x-github-api-version\": \"2026-06-01\",\n \"x-request-id\": \"\",\n \"x-vscode-user-agent-library-version\": \"electron-fetch\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.githubcopilot.com/chat/completions\",\n \"stream\": \"https://api.githubcopilot.com/chat/completions\"\n }\n },\n \"github-models\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"X-GitHub-Api-Version\": \"2022-11-28\"\n },\n \"nonStream\": {\n \"Accept\": \"application/vnd.github+json\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"X-GitHub-Api-Version\": \"2022-11-28\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"X-GitHub-Api-Version\": \"2022-11-28\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://models.github.ai/inference/chat/completions\",\n \"stream\": \"https://models.github.ai/inference/chat/completions\"\n }\n },\n \"gitlab-duo\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://gitlab.com/api/v4/code_suggestions/completions\",\n \"stream\": \"https://gitlab.com/api/v4/code_suggestions/completions\"\n }\n },\n \"gitlawb\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://github.com/Gitlawb/openclaude\",\n \"User-Agent\": \"OpenClaude/1.0 (; )\",\n \"X-Title\": \"OpenClaude CLI\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://github.com/Gitlawb/openclaude\",\n \"User-Agent\": \"OpenClaude/1.0 (; )\",\n \"X-Title\": \"OpenClaude CLI\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://github.com/Gitlawb/openclaude\",\n \"User-Agent\": \"OpenClaude/1.0 (; )\",\n \"X-Title\": \"OpenClaude CLI\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://opengateway.gitlawb.com/v1/xiaomi-mimo\",\n \"stream\": \"https://opengateway.gitlawb.com/v1/xiaomi-mimo\"\n }\n },\n \"gitlawb-gmi\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://github.com/Gitlawb/openclaude\",\n \"User-Agent\": \"OpenClaude/1.0 (; )\",\n \"X-Title\": \"OpenClaude CLI\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://github.com/Gitlawb/openclaude\",\n \"User-Agent\": \"OpenClaude/1.0 (; )\",\n \"X-Title\": \"OpenClaude CLI\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://github.com/Gitlawb/openclaude\",\n \"User-Agent\": \"OpenClaude/1.0 (; )\",\n \"X-Title\": \"OpenClaude CLI\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://opengateway.gitlawb.com/v1/gmi-cloud\",\n \"stream\": \"https://opengateway.gitlawb.com/v1/gmi-cloud\"\n }\n },\n \"glm\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.z.ai/api/coding/paas/v4/chat/completions\",\n \"stream\": \"https://api.z.ai/api/coding/paas/v4/chat/completions\"\n }\n },\n \"glm-cn\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://open.bigmodel.cn/api/coding/paas/v4/chat/completions\",\n \"stream\": \"https://open.bigmodel.cn/api/coding/paas/v4/chat/completions\"\n }\n },\n \"glmt\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.z.ai/api/coding/paas/v4/chat/completions\",\n \"stream\": \"https://api.z.ai/api/coding/paas/v4/chat/completions\"\n }\n },\n \"grok-cli\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://cli-chat-proxy.grok.com/v1/chat/completions\",\n \"stream\": \"https://cli-chat-proxy.grok.com/v1/chat/completions\"\n }\n },\n \"grok-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://grok.com/rest/app-chat/conversations/new\",\n \"stream\": \"https://grok.com/rest/app-chat/conversations/new\"\n }\n },\n \"groq\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.groq.com/openai/v1/chat/completions\",\n \"stream\": \"https://api.groq.com/openai/v1/chat/completions\"\n }\n },\n \"hackclub\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://ai.hackclub.com/proxy/v1/chat/completions\",\n \"stream\": \"https://ai.hackclub.com/proxy/v1/chat/completions\"\n }\n },\n \"haiper\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.haiper.ai/v1\",\n \"stream\": \"https://api.haiper.ai/v1\"\n }\n },\n \"hcnsec\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.hcnsec.cn/v1/chat/completions\",\n \"stream\": \"https://api.hcnsec.cn/v1/chat/completions\"\n }\n },\n \"heroku\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://us.inference.heroku.com/v1/chat/completions\",\n \"stream\": \"https://us.inference.heroku.com/v1/chat/completions\"\n }\n },\n \"huggingchat\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://huggingface.co/chat/conversation\",\n \"stream\": \"https://huggingface.co/chat/conversation\"\n }\n },\n \"huggingface\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://router.huggingface.co/v1/chat/completions\",\n \"stream\": \"https://router.huggingface.co/v1/chat/completions\"\n }\n },\n \"hyperbolic\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.hyperbolic.xyz/v1/chat/completions\",\n \"stream\": \"https://api.hyperbolic.xyz/v1/chat/completions\"\n }\n },\n \"ideogram\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.ideogram.ai\",\n \"stream\": \"https://api.ideogram.ai\"\n }\n },\n \"iflytek\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://spark-api.xf-yun.com/v1/chat/completions\",\n \"stream\": \"https://spark-api.xf-yun.com/v1/chat/completions\"\n }\n },\n \"inference-net\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.inference.net/v1/chat/completions\",\n \"stream\": \"https://api.inference.net/v1/chat/completions\"\n }\n },\n \"inner-ai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://chatapi.innerai.com/chat\",\n \"stream\": \"https://chatapi.innerai.com/chat\"\n }\n },\n \"kenari\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://kenari.id/v1/chat/completions\",\n \"stream\": \"https://kenari.id/v1/chat/completions\"\n }\n },\n \"kie\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.kie.ai/v1/chat/completions\",\n \"stream\": \"https://api.kie.ai/v1/chat/completions\"\n }\n },\n \"kilo-gateway\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.kilo.ai/api/gateway/chat/completions\",\n \"stream\": \"https://api.kilo.ai/api/gateway/chat/completions\"\n }\n },\n \"kilocode\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"X-KILOCODE-EDITORNAME\": \"OmniRoute\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"X-KILOCODE-EDITORNAME\": \"OmniRoute\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"X-KILOCODE-EDITORNAME\": \"OmniRoute\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.kilo.ai/api/openrouter/chat/completions\",\n \"stream\": \"https://api.kilo.ai/api/openrouter/chat/completions\"\n }\n },\n \"kimi\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.moonshot.ai/v1/chat/completions\",\n \"stream\": \"https://api.moonshot.ai/v1/chat/completions\"\n }\n },\n \"kimi-coding\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n },\n \"nonStream\": {\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.kimi.com/coding/v1/messages?beta=true\",\n \"stream\": \"https://api.kimi.com/coding/v1/messages?beta=true\"\n }\n },\n \"kimi-coding-apikey\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n },\n \"nonStream\": {\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.kimi.com/coding/v1/messages\",\n \"stream\": \"https://api.kimi.com/coding/v1/messages\"\n }\n },\n \"kimi-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://www.kimi.com\",\n \"stream\": \"https://www.kimi.com\"\n }\n },\n \"kiro\": {\n \"format\": \"kiro\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"AWS-SDK-JS/3.0.0 kiro-ide/1.0.0\",\n \"X-Amz-Target\": \"AmazonCodeWhispererStreamingService.GenerateAssistantResponse\",\n \"X-Amz-User-Agent\": \"aws-sdk-js/3.0.0 kiro-ide/1.0.0\"\n },\n \"nonStream\": {\n \"Accept\": \"application/vnd.amazon.eventstream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"AWS-SDK-JS/3.0.0 kiro-ide/1.0.0\",\n \"X-Amz-Target\": \"AmazonCodeWhispererStreamingService.GenerateAssistantResponse\",\n \"X-Amz-User-Agent\": \"aws-sdk-js/3.0.0 kiro-ide/1.0.0\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"AWS-SDK-JS/3.0.0 kiro-ide/1.0.0\",\n \"X-Amz-Target\": \"AmazonCodeWhispererStreamingService.GenerateAssistantResponse\",\n \"X-Amz-User-Agent\": \"aws-sdk-js/3.0.0 kiro-ide/1.0.0\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://codewhisperer.us-east-1.amazonaws.com/generateAssistantResponse\",\n \"stream\": \"https://codewhisperer.us-east-1.amazonaws.com/generateAssistantResponse\"\n }\n },\n \"lambda-ai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.lambda.ai/v1/chat/completions\",\n \"stream\": \"https://api.lambda.ai/v1/chat/completions\"\n }\n },\n \"leonardo\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://cloud.leonardo.ai/api/rest/v1\",\n \"stream\": \"https://cloud.leonardo.ai/api/rest/v1\"\n }\n },\n \"liquid\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.liquid.ai/v1/chat/completions\",\n \"stream\": \"https://api.liquid.ai/v1/chat/completions\"\n }\n },\n \"llamagate\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://llamagate.ai/v1/chat/completions\",\n \"stream\": \"https://llamagate.ai/v1/chat/completions\"\n }\n },\n \"llm7\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.llm7.io/v1/chat/completions\",\n \"stream\": \"https://api.llm7.io/v1/chat/completions\"\n }\n },\n \"lmarena\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://arena.ai/nextjs-api/stream/create-evaluation\",\n \"stream\": \"https://arena.ai/nextjs-api/stream/create-evaluation\"\n }\n },\n \"longcat\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.longcat.chat/openai/v1/chat/completions\",\n \"stream\": \"https://api.longcat.chat/openai/v1/chat/completions\"\n }\n },\n \"maritalk\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Key \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Key \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Key \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://chat.maritaca.ai/api\",\n \"stream\": \"https://chat.maritaca.ai/api\"\n }\n },\n \"meta-llama\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.llama.com/compat/v1/chat/completions\",\n \"stream\": \"https://api.llama.com/compat/v1/chat/completions\"\n }\n },\n \"mimocode\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.xiaomimimo.com\",\n \"stream\": \"https://api.xiaomimimo.com\"\n }\n },\n \"minimax\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.minimax.io/anthropic/v1/messages?beta=true\",\n \"stream\": \"https://api.minimax.io/anthropic/v1/messages?beta=true\"\n }\n },\n \"minimax-cn\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.minimaxi.com/anthropic/v1/messages?beta=true\",\n \"stream\": \"https://api.minimaxi.com/anthropic/v1/messages?beta=true\"\n }\n },\n \"mistral\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.mistral.ai/v1/chat/completions\",\n \"stream\": \"https://api.mistral.ai/v1/chat/completions\"\n }\n },\n \"modal\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.modal.ai/v1/chat/completions\",\n \"stream\": \"https://api.modal.ai/v1/chat/completions\"\n }\n },\n \"modelscope\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api-inference.modelscope.cn/v1/chat/completions\",\n \"stream\": \"https://api-inference.modelscope.cn/v1/chat/completions\"\n }\n },\n \"monsterapi\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.monsterapi.ai/v1/chat/completions\",\n \"stream\": \"https://api.monsterapi.ai/v1/chat/completions\"\n }\n },\n \"moonshot\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.moonshot.ai/v1/chat/completions\",\n \"stream\": \"https://api.moonshot.ai/v1/chat/completions\"\n }\n },\n \"morph\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.morphllm.com/v1/chat/completions\",\n \"stream\": \"https://api.morphllm.com/v1/chat/completions\"\n }\n },\n \"muse-spark-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://www.meta.ai/api/graphql\",\n \"stream\": \"https://www.meta.ai/api/graphql\"\n }\n },\n \"nanogpt\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://nano-gpt.com/api/v1/chat/completions\",\n \"stream\": \"https://nano-gpt.com/api/v1/chat/completions\"\n }\n },\n \"nebius\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.tokenfactory.nebius.com/v1/chat/completions\",\n \"stream\": \"https://api.tokenfactory.nebius.com/v1/chat/completions\"\n }\n },\n \"nlpcloud\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.nlpcloud.io/v1/chat/completions\",\n \"stream\": \"https://api.nlpcloud.io/v1/chat/completions\"\n }\n },\n \"nous-research\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://inference-api.nousresearch.com/v1/chat/completions\",\n \"stream\": \"https://inference-api.nousresearch.com/v1/chat/completions\"\n }\n },\n \"novita\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.novita.ai/openai/v1/chat/completions\",\n \"stream\": \"https://api.novita.ai/openai/v1/chat/completions\"\n }\n },\n \"nscale\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://inference.api.nscale.com/v1/chat/completions\",\n \"stream\": \"https://inference.api.nscale.com/v1/chat/completions\"\n }\n },\n \"nube\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://ai.nube.sh/api/v1/chat/completions\",\n \"stream\": \"https://ai.nube.sh/api/v1/chat/completions\"\n }\n },\n \"nvidia\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://integrate.api.nvidia.com/v1/chat/completions\",\n \"stream\": \"https://integrate.api.nvidia.com/v1/chat/completions\"\n }\n },\n \"ollama-cloud\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://ollama.com/v1/chat/completions\",\n \"stream\": \"https://ollama.com/v1/chat/completions\"\n }\n },\n \"openadapter\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.openadapter.in/v1/chat/completions\",\n \"stream\": \"https://api.openadapter.in/v1/chat/completions\"\n }\n },\n \"openai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.openai.com/v1/chat/completions\",\n \"stream\": \"https://api.openai.com/v1/chat/completions\"\n }\n },\n \"opencode\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://opencode.ai/zen/v1\",\n \"stream\": \"https://opencode.ai/zen/v1\"\n }\n },\n \"opencode-go\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://opencode.ai/zen/go/v1\",\n \"stream\": \"https://opencode.ai/zen/go/v1\"\n }\n },\n \"opencode-zen\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://opencode.ai/zen/v1\",\n \"stream\": \"https://opencode.ai/zen/v1\"\n }\n },\n \"openrouter\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://openrouter.ai/api/v1/chat/completions\",\n \"stream\": \"https://openrouter.ai/api/v1/chat/completions\"\n }\n },\n \"openvecta\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.openvecta.com/v1/chat/completions\",\n \"stream\": \"https://api.openvecta.com/v1/chat/completions\"\n }\n },\n \"orcarouter\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"HTTP-Referer\": \"https://endpoint-proxy.local\",\n \"X-Title\": \"Endpoint Proxy\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.orcarouter.ai/v1\",\n \"stream\": \"https://api.orcarouter.ai/v1\"\n }\n },\n \"ovhcloud\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://oai.endpoints.kepler.ai.cloud.ovh.net/v1/chat/completions\",\n \"stream\": \"https://oai.endpoints.kepler.ai.cloud.ovh.net/v1/chat/completions\"\n }\n },\n \"perplexity\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.perplexity.ai/chat/completions\",\n \"stream\": \"https://api.perplexity.ai/chat/completions\"\n }\n },\n \"perplexity-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://www.perplexity.ai/rest/sse/perplexity_ask\",\n \"stream\": \"https://www.perplexity.ai/rest/sse/perplexity_ask\"\n }\n },\n \"pioneer\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n },\n \"nonStream\": {\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.pioneer.ai/v1/chat/completions\",\n \"stream\": \"https://api.pioneer.ai/v1/chat/completions\"\n }\n },\n \"pollinations\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://gen.pollinations.ai/v1/chat/completions\",\n \"stream\": \"https://gen.pollinations.ai/v1/chat/completions\"\n }\n },\n \"predibase\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://serving.app.predibase.com/v1/chat/completions\",\n \"stream\": \"https://serving.app.predibase.com/v1/chat/completions\"\n }\n },\n \"publicai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.publicai.co/v1/chat/completions\",\n \"stream\": \"https://api.publicai.co/v1/chat/completions\"\n }\n },\n \"puter\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.puter.com/puterai/openai/v1/chat/completions\",\n \"stream\": \"https://api.puter.com/puterai/openai/v1/chat/completions\"\n }\n },\n \"qianfan\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://qianfan.baidubce.com/v2/chat/completions\",\n \"stream\": \"https://qianfan.baidubce.com/v2/chat/completions\"\n }\n },\n \"qiniu\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.qnaigc.com/v1/chat/completions\",\n \"stream\": \"https://api.qnaigc.com/v1/chat/completions\"\n }\n },\n \"qoder\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Qoder-Cli\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Qoder-Cli\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Qoder-Cli\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.qoder.com/v1/chat/completions\",\n \"stream\": \"https://api.qoder.com/v1/chat/completions\"\n }\n },\n \"qwen\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Accept-Language\": \"*\",\n \"Authorization\": \"Bearer \",\n \"Connection\": \"keep-alive\",\n \"Content-Type\": \"application/json\",\n \"Sec-Fetch-Mode\": \"cors\",\n \"User-Agent\": \"QwenCode/0.19.3 (; )\",\n \"X-Dashscope-AuthType\": \"qwen-oauth\",\n \"X-Dashscope-CacheControl\": \"enable\",\n \"X-Dashscope-UserAgent\": \"QwenCode/0.19.3 (; )\",\n \"X-Stainless-Arch\": \"\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-Os\": \"\",\n \"X-Stainless-Package-Version\": \"5.11.0\",\n \"X-Stainless-Retry-Count\": \"1\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"\"\n },\n \"nonStream\": {\n \"Accept-Language\": \"*\",\n \"Authorization\": \"Bearer \",\n \"Connection\": \"keep-alive\",\n \"Content-Type\": \"application/json\",\n \"Sec-Fetch-Mode\": \"cors\",\n \"User-Agent\": \"QwenCode/0.19.3 (; )\",\n \"X-Dashscope-AuthType\": \"qwen-oauth\",\n \"X-Dashscope-CacheControl\": \"enable\",\n \"X-Dashscope-UserAgent\": \"QwenCode/0.19.3 (; )\",\n \"X-Stainless-Arch\": \"\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-Os\": \"\",\n \"X-Stainless-Package-Version\": \"5.11.0\",\n \"X-Stainless-Retry-Count\": \"1\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Accept-Language\": \"*\",\n \"Authorization\": \"Bearer \",\n \"Connection\": \"keep-alive\",\n \"Content-Type\": \"application/json\",\n \"Sec-Fetch-Mode\": \"cors\",\n \"User-Agent\": \"QwenCode/0.19.3 (; )\",\n \"X-Dashscope-AuthType\": \"qwen-oauth\",\n \"X-Dashscope-CacheControl\": \"enable\",\n \"X-Dashscope-UserAgent\": \"QwenCode/0.19.3 (; )\",\n \"X-Stainless-Arch\": \"\",\n \"X-Stainless-Lang\": \"js\",\n \"X-Stainless-Os\": \"\",\n \"X-Stainless-Package-Version\": \"5.11.0\",\n \"X-Stainless-Retry-Count\": \"1\",\n \"X-Stainless-Runtime\": \"node\",\n \"X-Stainless-Runtime-Version\": \"\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://chat.qwen.ai/api/v1/services/aigc/text-generation/generation\",\n \"stream\": \"https://chat.qwen.ai/api/v1/services/aigc/text-generation/generation\"\n }\n },\n \"qwen-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://chat.qwen.ai/api/v2/chat/completions\",\n \"stream\": \"https://chat.qwen.ai/api/v2/chat/completions\"\n }\n },\n \"reka\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.reka.ai/v1/chat/completions\",\n \"stream\": \"https://api.reka.ai/v1/chat/completions\"\n }\n },\n \"requesty\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://router.requesty.ai/v1/chat/completions\",\n \"stream\": \"https://router.requesty.ai/v1/chat/completions\"\n }\n },\n \"sambanova\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.sambanova.ai/v1/chat/completions\",\n \"stream\": \"https://api.sambanova.ai/v1/chat/completions\"\n }\n },\n \"scaleway\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.scaleway.ai/v1/chat/completions\",\n \"stream\": \"https://api.scaleway.ai/v1/chat/completions\"\n }\n },\n \"sensenova\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://token.sensenova.cn/v1/chat/completions\",\n \"stream\": \"https://token.sensenova.cn/v1/chat/completions\"\n }\n },\n \"siliconflow\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.siliconflow.com/v1/chat/completions\",\n \"stream\": \"https://api.siliconflow.com/v1/chat/completions\"\n }\n },\n \"snowflake\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://{account}.snowflakecomputing.com/api/v2\",\n \"stream\": \"https://{account}.snowflakecomputing.com/api/v2\"\n }\n },\n \"sparkdesk\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://spark-api.xf-yun.com/v3.1/chat/completions\",\n \"stream\": \"https://spark-api.xf-yun.com/v3.1/chat/completions\"\n }\n },\n \"stepfun\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.stepfun.com/v1/chat/completions\",\n \"stream\": \"https://api.stepfun.com/v1/chat/completions\"\n }\n },\n \"sumopod\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://ai.sumopod.com/v1/chat/completions\",\n \"stream\": \"https://ai.sumopod.com/v1/chat/completions\"\n }\n },\n \"suno\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://studio-api.suno.ai/api/generate/v2/\",\n \"stream\": \"https://studio-api.suno.ai/api/generate/v2/\"\n }\n },\n \"synthetic\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.synthetic.new/openai/v1/chat/completions\",\n \"stream\": \"https://api.synthetic.new/openai/v1/chat/completions\"\n }\n },\n \"t3-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://t3.chat/api/chat\",\n \"stream\": \"https://t3.chat/api/chat\"\n }\n },\n \"tencent\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.hunyuan.cloud.tencent.com/v1/chat/completions\",\n \"stream\": \"https://api.hunyuan.cloud.tencent.com/v1/chat/completions\"\n }\n },\n \"theoldllm\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://theoldllm.vercel.app/api/chatgpt\",\n \"stream\": \"https://theoldllm.vercel.app/api/chatgpt\"\n }\n },\n \"together\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.together.xyz/v1/chat/completions\",\n \"stream\": \"https://api.together.xyz/v1/chat/completions\"\n }\n },\n \"tokenrouter\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.tokenrouter.com/v1/chat/completions\",\n \"stream\": \"https://api.tokenrouter.com/v1/chat/completions\"\n }\n },\n \"trae\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://core-normal.trae.ai/api/remote/v1\",\n \"stream\": \"https://core-normal.trae.ai/api/remote/v1\"\n }\n },\n \"udio\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://www.udio.com/api/generate-proxy\",\n \"stream\": \"https://www.udio.com/api/generate-proxy\"\n }\n },\n \"uncloseai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://hermes.ai.unturf.com/v1/chat/completions\",\n \"stream\": \"https://hermes.ai.unturf.com/v1/chat/completions\"\n }\n },\n \"upstage\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.upstage.ai/v1/chat/completions\",\n \"stream\": \"https://api.upstage.ai/v1/chat/completions\"\n }\n },\n \"v0-vercel\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.v0.dev/v1/chat/completions\",\n \"stream\": \"https://api.v0.dev/v1/chat/completions\"\n }\n },\n \"venice\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.venice.ai/api/v1/chat/completions\",\n \"stream\": \"https://api.venice.ai/api/v1/chat/completions\"\n }\n },\n \"veoaifree-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://veoaifree.com/wp-admin/admin-ajax.php\",\n \"stream\": \"https://veoaifree.com/wp-admin/admin-ajax.php\"\n }\n },\n \"vercel-ai-gateway\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://ai-gateway.vercel.sh/v1/chat/completions\",\n \"stream\": \"https://ai-gateway.vercel.sh/v1/chat/completions\"\n }\n },\n \"vertex\": {\n \"format\": \"gemini\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://generativelanguage.googleapis.com/v1beta/models/test-model:generateContent\",\n \"stream\": \"https://generativelanguage.googleapis.com/v1beta/models/test-model:streamGenerateContent?alt=sse\"\n }\n },\n \"vertex-partner\": {\n \"format\": \"gemini\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://us-central1-aiplatform.googleapis.com/v1/projects\",\n \"stream\": \"https://us-central1-aiplatform.googleapis.com/v1/projects\"\n }\n },\n \"volcengine\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://ark.cn-beijing.volces.com/api/v3/chat/completions\",\n \"stream\": \"https://ark.cn-beijing.volces.com/api/v3/chat/completions\"\n }\n },\n \"wafer\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://pass.wafer.ai/v1/messages\",\n \"stream\": \"https://pass.wafer.ai/v1/messages\"\n }\n },\n \"wandb\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.inference.wandb.ai/v1/chat/completions\",\n \"stream\": \"https://api.inference.wandb.ai/v1/chat/completions\"\n }\n },\n \"windsurf\": {\n \"format\": \"windsurf\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://server.self-serve.windsurf.com\",\n \"stream\": \"https://server.self-serve.windsurf.com\"\n }\n },\n \"x5lab\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.x5lab.dev/v1/chat/completions\",\n \"stream\": \"https://api.x5lab.dev/v1/chat/completions\"\n }\n },\n \"xai\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.x.ai/v1/chat/completions\",\n \"stream\": \"https://api.x.ai/v1/chat/completions\"\n }\n },\n \"xiaomi-mimo\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.xiaomimimo.com/v1\",\n \"stream\": \"https://api.xiaomimimo.com/v1\"\n }\n },\n \"yi\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.lingyiwanwu.com/v1/chat/completions\",\n \"stream\": \"https://api.lingyiwanwu.com/v1/chat/completions\"\n }\n },\n \"yuanbao-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://yuanbao.tencent.com/api/chat\",\n \"stream\": \"https://yuanbao.tencent.com/api/chat\"\n }\n },\n \"zai\": {\n \"format\": \"claude\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n },\n \"nonStream\": {\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Anthropic-Version\": \"2023-06-01\",\n \"Content-Type\": \"application/json\",\n \"x-api-key\": \"\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://api.z.ai/api/anthropic/v1/messages?beta=true\",\n \"stream\": \"https://api.z.ai/api/anthropic/v1/messages?beta=true\"\n }\n },\n \"zai-web\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://chat.z.ai\",\n \"stream\": \"https://chat.z.ai\"\n }\n },\n \"zed-hosted\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://cloud.zed.dev/completions\",\n \"stream\": \"https://cloud.zed.dev/completions\"\n }\n },\n \"zenmux\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://zenmux.ai/api/v1/chat/completions\",\n \"stream\": \"https://zenmux.ai/api/v1/chat/completions\"\n }\n },\n \"zenmux-free\": {\n \"format\": \"openai\",\n \"headers\": {\n \"apiKey\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"nonStream\": {\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n },\n \"oauth\": {\n \"Accept\": \"text/event-stream\",\n \"Authorization\": \"Bearer \",\n \"Content-Type\": \"application/json\"\n }\n },\n \"url\": {\n \"nonStream\": \"https://zenmux.ai/api/anthropic/v1/messages\",\n \"stream\": \"https://zenmux.ai/api/anthropic/v1/messages\"\n }\n }\n}\n"}}, "docs/i18n/cs/README.md": {"df4fa8e65b6d5e5876dcecd5a0eec84928b2be31": {"t": 1785746454.5157194, "n": 112445, "h": "d41719d36550c571", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../bn/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../fa/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../gu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../mr/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../sw/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../ta/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../te/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../ur/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** โ€” Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** โ€” Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** โ€” Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** โ€” A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** โ€” The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** โ€” The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** โ€” Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 100+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** โ€” Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** โ€” App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** โ€” Configurable queue, pacing, and concurrency defaults in Settings โ†’ Resilience\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Manual Combo Ordering** โ€” Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n
\n๐Ÿ“š 31. \"My long sessions crash with 'context_length_exceeded' limits\"\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** โ€” Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** โ€” Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** โ€” Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Pass `--allow-build` at install time to enable native build scripts required by `better-sqlite3` and `@swc/core` (the `approve-builds -g` command is not supported for global installs on pnpm v11):\n>\n> ```bash\n> pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `600000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŒ **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` โ€” full streaming over WS with session auth (API key or session cookie) |\n| ๐Ÿ”‘ **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| ๐Ÿง  **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing โ€” Claude-compatible API |\n| ๐Ÿ”ข **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation โ€” accurate usage tracking without guessing |\n| ๐ŸŒฑ **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup โ€” no more routing mismatches |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| โณ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** | Startup validates all env vars with Zod schemas โ€” clear errors for missing secrets, invalid URLs, or wrong types |\n| ๐Ÿ“‹ **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| ๐Ÿ” **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) โ€” quick performance at-a-glance for every request |\n| ๐Ÿ—‘๏ธ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything โ€” clean removal for all install methods |\n| ๐Ÿ”ง **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| ๐Ÿ”’ **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| ๐Ÿ‘๏ธ **Model Visibility Toggle** | Per-model visibility toggle (๐Ÿ‘ icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| ๐Ÿ“ง **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| ๐Ÿ”— **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| ๐Ÿ”’ **Daily Quota Lock** ๐Ÿ†• | Detects exhaustion signals and locks routing for the specific model until midnight |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿšฆ **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| โ„๏ธ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** ๐Ÿ†• | Guarded fetch for provider calls โ€” blocks private/local URLs, retries, SSRF protection |\n| โณ **Wait For Cooldown** ๐Ÿ†• | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** ๐Ÿ†• | Zod-based env schema validation at startup with actionable error messages |\n| ๐Ÿ“‹ **Compliance Audit v2** ๐Ÿ†• | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿท๏ธ **Real-Time Model Badges** ๐Ÿ†• | Live model status and daily quota countdown timers |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n| ๐Ÿ” **TPS Log Metric** ๐Ÿ†• | Tokens Per Second badge in log details modal |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n| ๐ŸŒ **V1 WebSocket Bridge** ๐Ÿ†• | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| ๐Ÿ”‘ **Sync Tokens & Bundle** ๐Ÿ†• | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) โ€” domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| --------------------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n\n \n \n \n \"Star\n \n\n\n## ๐ŸŒ StarMapper\n\n\n \n \n \n \"StarMapper\"\n \n\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "1bda6c15dc885b645243f6cc198688ba6bb7480c": {"t": 1785764413.8358448, "n": 112445, "h": "d41719d36550c571", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../bn/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../fa/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../gu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../mr/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../sw/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../ta/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../te/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../ur/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** โ€” Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** โ€” Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** โ€” Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** โ€” A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** โ€” The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** โ€” The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** โ€” Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 100+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** โ€” Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** โ€” App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** โ€” Configurable queue, pacing, and concurrency defaults in Settings โ†’ Resilience\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Manual Combo Ordering** โ€” Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n
\n๐Ÿ“š 31. \"My long sessions crash with 'context_length_exceeded' limits\"\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** โ€” Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** โ€” Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** โ€” Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Pass `--allow-build` at install time to enable native build scripts required by `better-sqlite3` and `@swc/core` (the `approve-builds -g` command is not supported for global installs on pnpm v11):\n>\n> ```bash\n> pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `600000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŒ **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` โ€” full streaming over WS with session auth (API key or session cookie) |\n| ๐Ÿ”‘ **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| ๐Ÿง  **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing โ€” Claude-compatible API |\n| ๐Ÿ”ข **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation โ€” accurate usage tracking without guessing |\n| ๐ŸŒฑ **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup โ€” no more routing mismatches |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| โณ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** | Startup validates all env vars with Zod schemas โ€” clear errors for missing secrets, invalid URLs, or wrong types |\n| ๐Ÿ“‹ **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| ๐Ÿ” **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) โ€” quick performance at-a-glance for every request |\n| ๐Ÿ—‘๏ธ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything โ€” clean removal for all install methods |\n| ๐Ÿ”ง **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| ๐Ÿ”’ **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| ๐Ÿ‘๏ธ **Model Visibility Toggle** | Per-model visibility toggle (๐Ÿ‘ icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| ๐Ÿ“ง **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| ๐Ÿ”— **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| ๐Ÿ”’ **Daily Quota Lock** ๐Ÿ†• | Detects exhaustion signals and locks routing for the specific model until midnight |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿšฆ **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| โ„๏ธ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** ๐Ÿ†• | Guarded fetch for provider calls โ€” blocks private/local URLs, retries, SSRF protection |\n| โณ **Wait For Cooldown** ๐Ÿ†• | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** ๐Ÿ†• | Zod-based env schema validation at startup with actionable error messages |\n| ๐Ÿ“‹ **Compliance Audit v2** ๐Ÿ†• | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿท๏ธ **Real-Time Model Badges** ๐Ÿ†• | Live model status and daily quota countdown timers |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n| ๐Ÿ” **TPS Log Metric** ๐Ÿ†• | Tokens Per Second badge in log details modal |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n| ๐ŸŒ **V1 WebSocket Bridge** ๐Ÿ†• | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| ๐Ÿ”‘ **Sync Tokens & Bundle** ๐Ÿ†• | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) โ€” domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| --------------------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n\n \n \n \n \"Star\n \n\n\n## ๐ŸŒ StarMapper\n\n\n \n \n \n \"StarMapper\"\n \n\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "b729a8f27364f072c87082e03bb8e122f3d76251": {"t": 1785764415.6436114, "n": 115018, "h": "c52555adb4a1a7ac", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../bn/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../fa/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../gu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../mr/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../sw/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../ta/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../te/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../ur/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** โ€” Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** โ€” Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** โ€” Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** โ€” A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** โ€” The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** โ€” The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** โ€” Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 100+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** โ€” Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** โ€” App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** โ€” Configurable queue, pacing, and concurrency defaults in Settings โ†’ Resilience\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Manual Combo Ordering** โ€” Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n
\n๐Ÿ“š 31. \"My long sessions crash with 'context_length_exceeded' limits\"\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** โ€” Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** โ€” Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** โ€” Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Pass `--allow-build` at install time to enable native build scripts required by `better-sqlite3` and `@swc/core` (the `approve-builds -g` command is not supported for global installs on pnpm v11):\n>\n> ```bash\n> pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `600000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŒ **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` โ€” full streaming over WS with session auth (API key or session cookie) |\n| ๐Ÿ”‘ **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| ๐Ÿง  **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing โ€” Claude-compatible API |\n| ๐Ÿ”ข **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation โ€” accurate usage tracking without guessing |\n| ๐ŸŒฑ **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup โ€” no more routing mismatches |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| โณ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** | Startup validates all env vars with Zod schemas โ€” clear errors for missing secrets, invalid URLs, or wrong types |\n| ๐Ÿ“‹ **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| ๐Ÿ” **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) โ€” quick performance at-a-glance for every request |\n| ๐Ÿ—‘๏ธ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything โ€” clean removal for all install methods |\n| ๐Ÿ”ง **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| ๐Ÿ”’ **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| ๐Ÿ‘๏ธ **Model Visibility Toggle** | Per-model visibility toggle (๐Ÿ‘ icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| ๐Ÿ“ง **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| ๐Ÿ”— **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| ๐Ÿ”’ **Daily Quota Lock** ๐Ÿ†• | Detects exhaustion signals and locks routing for the specific model until midnight |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿšฆ **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| โ„๏ธ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** ๐Ÿ†• | Guarded fetch for provider calls โ€” blocks private/local URLs, retries, SSRF protection |\n| โณ **Wait For Cooldown** ๐Ÿ†• | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** ๐Ÿ†• | Zod-based env schema validation at startup with actionable error messages |\n| ๐Ÿ“‹ **Compliance Audit v2** ๐Ÿ†• | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿท๏ธ **Real-Time Model Badges** ๐Ÿ†• | Live model status and daily quota countdown timers |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n| ๐Ÿ” **TPS Log Metric** ๐Ÿ†• | Tokens Per Second badge in log details modal |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n| ๐ŸŒ **V1 WebSocket Bridge** ๐Ÿ†• | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| ๐Ÿ”‘ **Sync Tokens & Bundle** ๐Ÿ†• | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) โ€” domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| --------------------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n\n \n \n \n \"Star\n \n\n\n## ๐ŸŒ StarMapper\n\n\n \n \n \n \"StarMapper\"\n \n\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "7c23dab64de929686d2326f6824527ba9c746ca9": {"t": 1785764417.4323237, "n": 114944, "h": "5f5ffd692d374dc0", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../bn/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../fa/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../gu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../mr/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../sw/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../ta/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../te/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../ur/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** โ€” Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** โ€” Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** โ€” Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** โ€” A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** โ€” The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** โ€” The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** โ€” Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 100+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** โ€” Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** โ€” App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** โ€” Configurable queue, pacing, and concurrency defaults in Settings โ†’ Resilience\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Manual Combo Ordering** โ€” Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n
\n๐Ÿ“š 31. \"My long sessions crash with 'context_length_exceeded' limits\"\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** โ€” Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** โ€” Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** โ€” Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `600000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŒ **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` โ€” full streaming over WS with session auth (API key or session cookie) |\n| ๐Ÿ”‘ **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| ๐Ÿง  **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing โ€” Claude-compatible API |\n| ๐Ÿ”ข **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation โ€” accurate usage tracking without guessing |\n| ๐ŸŒฑ **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup โ€” no more routing mismatches |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| โณ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** | Startup validates all env vars with Zod schemas โ€” clear errors for missing secrets, invalid URLs, or wrong types |\n| ๐Ÿ“‹ **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| ๐Ÿ” **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) โ€” quick performance at-a-glance for every request |\n| ๐Ÿ—‘๏ธ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything โ€” clean removal for all install methods |\n| ๐Ÿ”ง **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| ๐Ÿ”’ **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| ๐Ÿ‘๏ธ **Model Visibility Toggle** | Per-model visibility toggle (๐Ÿ‘ icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| ๐Ÿ“ง **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| ๐Ÿ”— **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| ๐Ÿ”’ **Daily Quota Lock** ๐Ÿ†• | Detects exhaustion signals and locks routing for the specific model until midnight |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿšฆ **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| โ„๏ธ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** ๐Ÿ†• | Guarded fetch for provider calls โ€” blocks private/local URLs, retries, SSRF protection |\n| โณ **Wait For Cooldown** ๐Ÿ†• | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** ๐Ÿ†• | Zod-based env schema validation at startup with actionable error messages |\n| ๐Ÿ“‹ **Compliance Audit v2** ๐Ÿ†• | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿท๏ธ **Real-Time Model Badges** ๐Ÿ†• | Live model status and daily quota countdown timers |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n| ๐Ÿ” **TPS Log Metric** ๐Ÿ†• | Tokens Per Second badge in log details modal |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n| ๐ŸŒ **V1 WebSocket Bridge** ๐Ÿ†• | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| ๐Ÿ”‘ **Sync Tokens & Bundle** ๐Ÿ†• | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) โ€” domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| --------------------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n\n \n \n \n \"Star\n \n\n\n## ๐ŸŒ StarMapper\n\n\n \n \n \n \"StarMapper\"\n \n\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "b91ffa7f721b121876a78d552169fa10783fb076": {"t": 1785764419.9927485, "n": 118180, "h": "6a7b93caed90658d", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../bn/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../fa/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../gu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../mr/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../sw/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../ta/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../te/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../ur/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Gemini
\n Gemini CLI\n
\n โญ 94.7K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** โ€” Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** โ€” Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** โ€” Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** โ€” A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** โ€” The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** โ€” The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** โ€” Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 100+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** โ€” Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** โ€” App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** โ€” Configurable queue, pacing, and concurrency defaults in Settings โ†’ Resilience\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Manual Combo Ordering** โ€” Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n
\n๐Ÿ“š 31. \"My long sessions crash with 'context_length_exceeded' limits\"\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** โ€” Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** โ€” Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** โ€” Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** |\n| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `600000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŒ **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` โ€” full streaming over WS with session auth (API key or session cookie) |\n| ๐Ÿ”‘ **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| ๐Ÿง  **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing โ€” Claude-compatible API |\n| ๐Ÿ”ข **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation โ€” accurate usage tracking without guessing |\n| ๐ŸŒฑ **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup โ€” no more routing mismatches |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| โณ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** | Startup validates all env vars with Zod schemas โ€” clear errors for missing secrets, invalid URLs, or wrong types |\n| ๐Ÿ“‹ **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| ๐Ÿ” **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) โ€” quick performance at-a-glance for every request |\n| ๐Ÿ—‘๏ธ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything โ€” clean removal for all install methods |\n| ๐Ÿ”ง **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| ๐Ÿ”’ **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| ๐Ÿ‘๏ธ **Model Visibility Toggle** | Per-model visibility toggle (๐Ÿ‘ icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| ๐Ÿ“ง **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| ๐Ÿ”— **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| ๐Ÿ”’ **Daily Quota Lock** ๐Ÿ†• | Detects exhaustion signals and locks routing for the specific model until midnight |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿšฆ **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| โ„๏ธ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** ๐Ÿ†• | Guarded fetch for provider calls โ€” blocks private/local URLs, retries, SSRF protection |\n| โณ **Wait For Cooldown** ๐Ÿ†• | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** ๐Ÿ†• | Zod-based env schema validation at startup with actionable error messages |\n| ๐Ÿ“‹ **Compliance Audit v2** ๐Ÿ†• | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿท๏ธ **Real-Time Model Badges** ๐Ÿ†• | Live model status and daily quota countdown timers |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n| ๐Ÿ” **TPS Log Metric** ๐Ÿ†• | Tokens Per Second badge in log details modal |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n| ๐ŸŒ **V1 WebSocket Bridge** ๐Ÿ†• | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| ๐Ÿ”‘ **Sync Tokens & Bundle** ๐Ÿ†• | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) โ€” domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| --------------------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n\n \n \n \n \"Star\n \n\n\n## ๐ŸŒ StarMapper\n\n\n \n \n \n \"StarMapper\"\n \n\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "54be51a664725a07e237ee6487692ad8ef5e9b79": {"t": 1785764421.7236533, "n": 118180, "h": "3e0d9d5b90c20cc1", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../bn/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../fa/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../gu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../mr/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../sw/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../ta/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../te/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../ur/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Gemini
\n Gemini CLI\n
\n โญ 94.7K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** โ€” Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** โ€” Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** โ€” Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** โ€” A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** โ€” The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** โ€” The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** โ€” Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 100+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** โ€” Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** โ€” App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** โ€” Configurable queue, pacing, and concurrency defaults in Settings โ†’ Resilience\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Manual Combo Ordering** โ€” Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n
\n๐Ÿ“š 31. \"My long sessions crash with 'context_length_exceeded' limits\"\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** โ€” Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** โ€” Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** โ€” Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** |\n| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŒ **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` โ€” full streaming over WS with session auth (API key or session cookie) |\n| ๐Ÿ”‘ **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| ๐Ÿง  **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing โ€” Claude-compatible API |\n| ๐Ÿ”ข **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation โ€” accurate usage tracking without guessing |\n| ๐ŸŒฑ **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup โ€” no more routing mismatches |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| โณ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** | Startup validates all env vars with Zod schemas โ€” clear errors for missing secrets, invalid URLs, or wrong types |\n| ๐Ÿ“‹ **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| ๐Ÿ” **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) โ€” quick performance at-a-glance for every request |\n| ๐Ÿ—‘๏ธ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything โ€” clean removal for all install methods |\n| ๐Ÿ”ง **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| ๐Ÿ”’ **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| ๐Ÿ‘๏ธ **Model Visibility Toggle** | Per-model visibility toggle (๐Ÿ‘ icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| ๐Ÿ“ง **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| ๐Ÿ”— **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| ๐Ÿ”’ **Daily Quota Lock** ๐Ÿ†• | Detects exhaustion signals and locks routing for the specific model until midnight |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿšฆ **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| โ„๏ธ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** ๐Ÿ†• | Guarded fetch for provider calls โ€” blocks private/local URLs, retries, SSRF protection |\n| โณ **Wait For Cooldown** ๐Ÿ†• | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** ๐Ÿ†• | Zod-based env schema validation at startup with actionable error messages |\n| ๐Ÿ“‹ **Compliance Audit v2** ๐Ÿ†• | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿท๏ธ **Real-Time Model Badges** ๐Ÿ†• | Live model status and daily quota countdown timers |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n| ๐Ÿ” **TPS Log Metric** ๐Ÿ†• | Tokens Per Second badge in log details modal |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n| ๐ŸŒ **V1 WebSocket Bridge** ๐Ÿ†• | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| ๐Ÿ”‘ **Sync Tokens & Bundle** ๐Ÿ†• | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) โ€” domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| --------------------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n\n \n \n \n \"Star\n \n\n\n## ๐ŸŒ StarMapper\n\n\n \n \n \n \"StarMapper\"\n \n\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "8a1d9beb55fe825bd132c8696117046258869a79": {"t": 1785764423.7960794, "n": 118547, "h": "193e9c035bc06fa6", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../bn/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../fa/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../gu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../mr/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../sw/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../ta/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../te/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../ur/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Gemini
\n Gemini CLI\n
\n โญ 94.7K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** โ€” Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** โ€” Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** โ€” Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** โ€” A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** โ€” The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** โ€” The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** โ€” Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 100+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** โ€” Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** โ€” App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** โ€” Configurable queue, pacing, and concurrency defaults in Settings โ†’ Resilience\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Manual Combo Ordering** โ€” Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n
\n๐Ÿ“š 31. \"My long sessions crash with 'context_length_exceeded' limits\"\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** โ€” Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** โ€” Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** โ€” Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** |\n| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŒ **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` โ€” full streaming over WS with session auth (API key or session cookie) |\n| ๐Ÿ”‘ **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| ๐Ÿง  **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing โ€” Claude-compatible API |\n| ๐Ÿ”ข **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation โ€” accurate usage tracking without guessing |\n| ๐ŸŒฑ **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup โ€” no more routing mismatches |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| โณ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** | Startup validates all env vars with Zod schemas โ€” clear errors for missing secrets, invalid URLs, or wrong types |\n| ๐Ÿ“‹ **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| ๐Ÿ” **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) โ€” quick performance at-a-glance for every request |\n| ๐Ÿ—‘๏ธ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything โ€” clean removal for all install methods |\n| ๐Ÿ”ง **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| ๐Ÿ”’ **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| ๐Ÿ‘๏ธ **Model Visibility Toggle** | Per-model visibility toggle (๐Ÿ‘ icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| ๐Ÿ“ง **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| ๐Ÿ”— **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| ๐Ÿ”’ **Daily Quota Lock** ๐Ÿ†• | Detects exhaustion signals and locks routing for the specific model until midnight |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿšฆ **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| โ„๏ธ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** ๐Ÿ†• | Guarded fetch for provider calls โ€” blocks private/local URLs, retries, SSRF protection |\n| โณ **Wait For Cooldown** ๐Ÿ†• | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** ๐Ÿ†• | Zod-based env schema validation at startup with actionable error messages |\n| ๐Ÿ“‹ **Compliance Audit v2** ๐Ÿ†• | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿท๏ธ **Real-Time Model Badges** ๐Ÿ†• | Live model status and daily quota countdown timers |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n| ๐Ÿ” **TPS Log Metric** ๐Ÿ†• | Tokens Per Second badge in log details modal |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n| ๐ŸŒ **V1 WebSocket Bridge** ๐Ÿ†• | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| ๐Ÿ”‘ **Sync Tokens & Bundle** ๐Ÿ†• | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) โ€” domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| --------------------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n\n \n \n \n \"Star\n \n\n\n## ๐ŸŒ StarMapper\n\n\n \n \n \n \"StarMapper\"\n \n\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ€” the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "3d75fb3fae6eb50f8d2ae5e678dfdc2978e33163": {"t": 1785764425.701589, "n": 118300, "h": "648861745370d537", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../bn/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../fa/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../gu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../mr/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../sw/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../ta/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../te/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../ur/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Gemini
\n Gemini CLI\n
\n โญ 94.7K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** โ€” Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** โ€” Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** โ€” Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** โ€” A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** โ€” The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** โ€” The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** โ€” Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 100+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** โ€” Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** โ€” App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** โ€” Configurable queue, pacing, and concurrency defaults in Settings โ†’ Resilience\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Manual Combo Ordering** โ€” Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n
\n๐Ÿ“š 31. \"My long sessions crash with 'context_length_exceeded' limits\"\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** โ€” Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** โ€” Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** โ€” Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** |\n| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŒ **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` โ€” full streaming over WS with session auth (API key or session cookie) |\n| ๐Ÿ”‘ **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| ๐Ÿง  **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing โ€” Claude-compatible API |\n| ๐Ÿ”ข **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation โ€” accurate usage tracking without guessing |\n| ๐ŸŒฑ **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup โ€” no more routing mismatches |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| โณ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** | Startup validates all env vars with Zod schemas โ€” clear errors for missing secrets, invalid URLs, or wrong types |\n| ๐Ÿ“‹ **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| ๐Ÿ” **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) โ€” quick performance at-a-glance for every request |\n| ๐Ÿ—‘๏ธ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything โ€” clean removal for all install methods |\n| ๐Ÿ”ง **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| ๐Ÿ”’ **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| ๐Ÿ‘๏ธ **Model Visibility Toggle** | Per-model visibility toggle (๐Ÿ‘ icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| ๐Ÿ“ง **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| ๐Ÿ”— **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| ๐Ÿ”’ **Daily Quota Lock** ๐Ÿ†• | Detects exhaustion signals and locks routing for the specific model until midnight |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿšฆ **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| โ„๏ธ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** ๐Ÿ†• | Guarded fetch for provider calls โ€” blocks private/local URLs, retries, SSRF protection |\n| โณ **Wait For Cooldown** ๐Ÿ†• | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** ๐Ÿ†• | Zod-based env schema validation at startup with actionable error messages |\n| ๐Ÿ“‹ **Compliance Audit v2** ๐Ÿ†• | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿท๏ธ **Real-Time Model Badges** ๐Ÿ†• | Live model status and daily quota countdown timers |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n| ๐Ÿ” **TPS Log Metric** ๐Ÿ†• | Tokens Per Second badge in log details modal |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n| ๐ŸŒ **V1 WebSocket Bridge** ๐Ÿ†• | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| ๐Ÿ”‘ **Sync Tokens & Bundle** ๐Ÿ†• | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) โ€” domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| -------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n\n \n \n \n \"Star\n \n\n\n## ๐ŸŒ StarMapper\n\n\n \n \n \n \"StarMapper\"\n \n\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ€” the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "5b8e41c1b2a4ef0412f8002fd3909ea7e10efd1b": {"t": 1785764427.4826927, "n": 118300, "h": "a71825816c457a07", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../bn/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../fa/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../gu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../mr/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../sw/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../ta/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../te/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../ur/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Gemini
\n Gemini CLI\n
\n โญ 94.7K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** โ€” Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** โ€” Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** โ€” Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** โ€” A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** โ€” The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** โ€” The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** โ€” Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 100+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** โ€” Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** โ€” App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** โ€” Configurable queue, pacing, and concurrency defaults in Settings โ†’ Resilience\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Manual Combo Ordering** โ€” Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n
\n๐Ÿ“š 31. \"My long sessions crash with 'context_length_exceeded' limits\"\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** โ€” Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** โ€” Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** โ€” Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** |\n| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŒ **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` โ€” full streaming over WS with session auth (API key or session cookie) |\n| ๐Ÿ”‘ **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| ๐Ÿง  **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing โ€” Claude-compatible API |\n| ๐Ÿ”ข **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation โ€” accurate usage tracking without guessing |\n| ๐ŸŒฑ **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup โ€” no more routing mismatches |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| โณ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** | Startup validates all env vars with Zod schemas โ€” clear errors for missing secrets, invalid URLs, or wrong types |\n| ๐Ÿ“‹ **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| ๐Ÿ” **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) โ€” quick performance at-a-glance for every request |\n| ๐Ÿ—‘๏ธ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything โ€” clean removal for all install methods |\n| ๐Ÿ”ง **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| ๐Ÿ”’ **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| ๐Ÿ‘๏ธ **Model Visibility Toggle** | Per-model visibility toggle (๐Ÿ‘ icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| ๐Ÿ“ง **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| ๐Ÿ”— **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| ๐Ÿ”’ **Daily Quota Lock** ๐Ÿ†• | Detects exhaustion signals and locks routing for the specific model until midnight |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿšฆ **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| โ„๏ธ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** ๐Ÿ†• | Guarded fetch for provider calls โ€” blocks private/local URLs, retries, SSRF protection |\n| โณ **Wait For Cooldown** ๐Ÿ†• | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** ๐Ÿ†• | Zod-based env schema validation at startup with actionable error messages |\n| ๐Ÿ“‹ **Compliance Audit v2** ๐Ÿ†• | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿท๏ธ **Real-Time Model Badges** ๐Ÿ†• | Live model status and daily quota countdown timers |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n| ๐Ÿ” **TPS Log Metric** ๐Ÿ†• | Tokens Per Second badge in log details modal |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n| ๐ŸŒ **V1 WebSocket Bridge** ๐Ÿ†• | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| ๐Ÿ”‘ **Sync Tokens & Bundle** ๐Ÿ†• | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) โ€” domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| -------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n\n \n \n \n \"Star\n \n\n\n## ๐ŸŒ StarMapper\n\n\n \n \n \n \"StarMapper\"\n \n\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ€” the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "7388623244b0e75f528f9a2d0983bda027bc053a": {"t": 1785764429.31307, "n": 118300, "h": "cd5c2dad2c12be8a", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../bn/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../fa/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../gu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../mr/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../sw/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../ta/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../te/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../ur/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Gemini
\n Gemini CLI\n
\n โญ 94.7K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** โ€” Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** โ€” Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Request Queue & Pacing** โ€” Per-connection request buckets smooth bursts before they hit upstream rate caps\n- **Connection Cooldown** โ€” A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff\n- **Provider Circuit Breaker** โ€” The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown\n- **Wait For Cooldown** โ€” The server can wait for the earliest connection cooldown to expire and retry the same client request automatically\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Health Dashboard** โ€” Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 100+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** โ€” Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** โ€” App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Request Queue & Pacing** โ€” Configurable queue, pacing, and concurrency defaults in Settings โ†’ Resilience\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Manual Combo Ordering** โ€” Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page\n- Review live provider breaker state from the Health dashboard\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n
\n๐Ÿ“š 31. \"My long sessions crash with 'context_length_exceeded' limits\"\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** โ€” Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** โ€” Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** โ€” Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** |\n| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n#### Arch Linux (AUR)\n\nArch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service:\n\n```bash\nyay -S omniroute-bin\nsystemctl --user enable --now omniroute.service\n```\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŒ **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` โ€” full streaming over WS with session auth (API key or session cookie) |\n| ๐Ÿ”‘ **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| ๐Ÿง  **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing โ€” Claude-compatible API |\n| ๐Ÿ”ข **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation โ€” accurate usage tracking without guessing |\n| ๐ŸŒฑ **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup โ€” no more routing mismatches |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| โณ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** | Startup validates all env vars with Zod schemas โ€” clear errors for missing secrets, invalid URLs, or wrong types |\n| ๐Ÿ“‹ **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| ๐Ÿ” **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) โ€” quick performance at-a-glance for every request |\n| ๐Ÿ—‘๏ธ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything โ€” clean removal for all install methods |\n| ๐Ÿ”ง **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| ๐Ÿ”’ **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| ๐Ÿ‘๏ธ **Model Visibility Toggle** | Per-model visibility toggle (๐Ÿ‘ icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| ๐Ÿ“ง **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| ๐Ÿ”— **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds |\n| ๐Ÿ”’ **Daily Quota Lock** ๐Ÿ†• | Detects exhaustion signals and locks routing for the specific model until midnight |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿšฆ **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| โ„๏ธ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** ๐Ÿ†• | Guarded fetch for provider calls โ€” blocks private/local URLs, retries, SSRF protection |\n| โณ **Wait For Cooldown** ๐Ÿ†• | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` |\n| ๐Ÿ” **Runtime Env Validation** ๐Ÿ†• | Zod-based env schema validation at startup with actionable error messages |\n| ๐Ÿ“‹ **Compliance Audit v2** ๐Ÿ†• | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿท๏ธ **Real-Time Model Badges** ๐Ÿ†• | Live model status and daily quota countdown timers |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n| ๐Ÿ” **TPS Log Metric** ๐Ÿ†• | Tokens Per Second badge in log details modal |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n| ๐ŸŒ **V1 WebSocket Bridge** ๐Ÿ†• | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| ๐Ÿ”‘ **Sync Tokens & Bundle** ๐Ÿ†• | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) โ€” domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| -------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n\n \n \n \n \"Star\n \n\n\n## ๐ŸŒ StarMapper\n\n\n \n \n \n \"StarMapper\"\n \n\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ€” the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "cde6f560140ff86aa3ffbec72282e31cfcba04cd": {"t": 1785764432.5278122, "n": 117089, "h": "be1d684d6e1e0924", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Gemini
\n Gemini CLI\n
\n โญ 94.7K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** โ€” Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** โ€” Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Settings-Driven Lock Hierarchy** โ€” Provider profiles control default account/model lockouts, global model quarantine, and provider circuit breakers from one control surface, while explicit upstream `Retry-After` windows still take priority\n- **Exponential Backoff** โ€” Progressive retry delays for both account/model lockouts and higher-level quarantine\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** โ€” Auto-disables failing providers within a combo chain\n- **Health Dashboard** โ€” Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 100+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** โ€” Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** โ€” App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** โ€” Configurable defaults in Settings โ†’ Resilience with persistence\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Manual Combo Ordering** โ€” Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n
\n๐Ÿ“š 31. \"My long sessions crash with 'context_length_exceeded' limits\"\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** โ€” Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** โ€” Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** โ€” Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** |\n| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŒ **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` โ€” full streaming over WS with session auth (API key or session cookie) |\n| ๐Ÿ”‘ **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| ๐Ÿง  **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing โ€” Claude-compatible API |\n| ๐Ÿ”ข **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation โ€” accurate usage tracking without guessing |\n| ๐ŸŒฑ **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup โ€” no more routing mismatches |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| ๐Ÿ”„ **Cooldown-Aware Retries** | Chat requests auto-retry on model-scoped cooldowns with configurable `requestRetry` and `maxRetryIntervalSec` |\n| ๐Ÿ” **Runtime Env Validation** | Startup validates all env vars with Zod schemas โ€” clear errors for missing secrets, invalid URLs, or wrong types |\n| ๐Ÿ“‹ **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| ๐Ÿ” **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) โ€” quick performance at-a-glance for every request |\n| ๐Ÿ—‘๏ธ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything โ€” clean removal for all install methods |\n| ๐Ÿ”ง **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| ๐Ÿ”’ **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| ๐Ÿ‘๏ธ **Model Visibility Toggle** | Per-model visibility toggle (๐Ÿ‘ icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| ๐Ÿ“ง **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| ๐Ÿ”— **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | --------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Circuit Breakers** | Per-provider and per-model trip/recover with 10-minute cooldowns |\n| ๐Ÿ”’ **Daily Quota Lock** ๐Ÿ†• | Detects exhaustion signals and locks routing for the specific model until midnight |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿ“Š **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** ๐Ÿ†• | Guarded fetch for provider calls โ€” blocks private/local URLs, retries, SSRF protection |\n| ๐Ÿ”„ **Cooldown-Aware Retries** ๐Ÿ†• | Auto-retry chat on model cooldowns; configurable `requestRetry` / `maxRetryIntervalSec` |\n| ๐Ÿ” **Runtime Env Validation** ๐Ÿ†• | Zod-based env schema validation at startup with actionable error messages |\n| ๐Ÿ“‹ **Compliance Audit v2** ๐Ÿ†• | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿท๏ธ **Real-Time Model Badges** ๐Ÿ†• | Live model status and daily quota countdown timers |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n| ๐Ÿ” **TPS Log Metric** ๐Ÿ†• | Tokens Per Second badge in log details modal |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n| ๐ŸŒ **V1 WebSocket Bridge** ๐Ÿ†• | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| ๐Ÿ”‘ **Sync Tokens & Bundle** ๐Ÿ†• | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) โ€” domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| -------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n\n \n \n \n \"Star\n \n\n\n## ๐ŸŒ StarMapper\n\n\n \n \n \n \"StarMapper\"\n \n\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ€” the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "333f0b9f2d19e61cc3108cd66bd1f30622a25c2a": {"t": 1785764436.5259306, "n": 117090, "h": "41c28b5cef34c20d", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md)\n\n---\n\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Gemini
\n Gemini CLI\n
\n โญ 94.7K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** โ€” Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** โ€” Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Settings-Driven Lock Hierarchy** โ€” Provider profiles control default account/model lockouts, global model quarantine, and provider circuit breakers from one control surface, while explicit upstream `Retry-After` windows still take priority\n- **Exponential Backoff** โ€” Progressive retry delays for both account/model lockouts and higher-level quarantine\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** โ€” Auto-disables failing providers within a combo chain\n- **Health Dashboard** โ€” Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 100+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** โ€” Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** โ€” App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** โ€” Configurable defaults in Settings โ†’ Resilience with persistence\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Manual Combo Ordering** โ€” Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n
\n๐Ÿ“š 31. \"My long sessions crash with 'context_length_exceeded' limits\"\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** โ€” Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** โ€” Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** โ€” Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** |\n| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŒ **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` โ€” full streaming over WS with session auth (API key or session cookie) |\n| ๐Ÿ”‘ **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| ๐Ÿง  **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing โ€” Claude-compatible API |\n| ๐Ÿ”ข **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation โ€” accurate usage tracking without guessing |\n| ๐ŸŒฑ **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup โ€” no more routing mismatches |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| ๐Ÿ”„ **Cooldown-Aware Retries** | Chat requests auto-retry on model-scoped cooldowns with configurable `requestRetry` and `maxRetryIntervalSec` |\n| ๐Ÿ” **Runtime Env Validation** | Startup validates all env vars with Zod schemas โ€” clear errors for missing secrets, invalid URLs, or wrong types |\n| ๐Ÿ“‹ **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| ๐Ÿ” **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) โ€” quick performance at-a-glance for every request |\n| ๐Ÿ—‘๏ธ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything โ€” clean removal for all install methods |\n| ๐Ÿ”ง **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| ๐Ÿ”’ **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| ๐Ÿ‘๏ธ **Model Visibility Toggle** | Per-model visibility toggle (๐Ÿ‘ icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| ๐Ÿ“ง **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| ๐Ÿ”— **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | --------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Circuit Breakers** | Per-provider and per-model trip/recover with 10-minute cooldowns |\n| ๐Ÿ”’ **Daily Quota Lock** ๐Ÿ†• | Detects exhaustion signals and locks routing for the specific model until midnight |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿ“Š **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** ๐Ÿ†• | Guarded fetch for provider calls โ€” blocks private/local URLs, retries, SSRF protection |\n| ๐Ÿ”„ **Cooldown-Aware Retries** ๐Ÿ†• | Auto-retry chat on model cooldowns; configurable `requestRetry` / `maxRetryIntervalSec` |\n| ๐Ÿ” **Runtime Env Validation** ๐Ÿ†• | Zod-based env schema validation at startup with actionable error messages |\n| ๐Ÿ“‹ **Compliance Audit v2** ๐Ÿ†• | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿท๏ธ **Real-Time Model Badges** ๐Ÿ†• | Live model status and daily quota countdown timers |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n| ๐Ÿ” **TPS Log Metric** ๐Ÿ†• | Tokens Per Second badge in log details modal |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n| ๐ŸŒ **V1 WebSocket Bridge** ๐Ÿ†• | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| ๐Ÿ”‘ **Sync Tokens & Bundle** ๐Ÿ†• | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) โ€” domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| -------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n\n \n \n \n \"Star\n \n\n\n## ๐ŸŒ StarMapper\n\n\n \n \n \n \"StarMapper\"\n \n\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ€” the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "e5c4e450c0cd597c2de3d9dde1d74b572c0a6bb3": {"t": 1785764438.1935754, "n": 116868, "h": "329c73205017133c", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Gemini
\n Gemini CLI\n
\n โญ 94.7K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** โ€” Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** โ€” Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Settings-Driven Lock Hierarchy** โ€” Provider profiles control default account/model lockouts, global model quarantine, and provider circuit breakers from one control surface, while explicit upstream `Retry-After` windows still take priority\n- **Exponential Backoff** โ€” Progressive retry delays for both account/model lockouts and higher-level quarantine\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** โ€” Auto-disables failing providers within a combo chain\n- **Health Dashboard** โ€” Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 100+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Summary Logs** โ€” Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Detail Artifacts** โ€” App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** โ€” Configurable defaults in Settings โ†’ Resilience with persistence\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Manual Combo Ordering** โ€” Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n
\n๐Ÿ“š 31. \"My long sessions crash with 'context_length_exceeded' limits\"\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** โ€” Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** โ€” Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** โ€” Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** |\n| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŒ **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` โ€” full streaming over WS with session auth (API key or session cookie) |\n| ๐Ÿ”‘ **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| ๐Ÿง  **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing โ€” Claude-compatible API |\n| ๐Ÿ”ข **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation โ€” accurate usage tracking without guessing |\n| ๐ŸŒฑ **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup โ€” no more routing mismatches |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| ๐Ÿ”„ **Cooldown-Aware Retries** | Chat requests auto-retry on model-scoped cooldowns with configurable `requestRetry` and `maxRetryIntervalSec` |\n| ๐Ÿ” **Runtime Env Validation** | Startup validates all env vars with Zod schemas โ€” clear errors for missing secrets, invalid URLs, or wrong types |\n| ๐Ÿ“‹ **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| ๐Ÿ” **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) โ€” quick performance at-a-glance for every request |\n| ๐Ÿ—‘๏ธ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything โ€” clean removal for all install methods |\n| ๐Ÿ”ง **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| ๐Ÿ”’ **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| ๐Ÿ‘๏ธ **Model Visibility Toggle** | Per-model visibility toggle (๐Ÿ‘ icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| ๐Ÿ“ง **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| ๐Ÿ”— **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | --------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿ“Š **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** ๐Ÿ†• | Guarded fetch for provider calls โ€” blocks private/local URLs, retries, SSRF protection |\n| ๐Ÿ”„ **Cooldown-Aware Retries** ๐Ÿ†• | Auto-retry chat on model cooldowns; configurable `requestRetry` / `maxRetryIntervalSec` |\n| ๐Ÿ” **Runtime Env Validation** ๐Ÿ†• | Zod-based env schema validation at startup with actionable error messages |\n| ๐Ÿ“‹ **Compliance Audit v2** ๐Ÿ†• | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** ๐Ÿ†• | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n| ๐Ÿ” **TPS Log Metric** ๐Ÿ†• | Tokens Per Second badge in log details modal |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n| ๐ŸŒ **V1 WebSocket Bridge** ๐Ÿ†• | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| ๐Ÿ”‘ **Sync Tokens & Bundle** ๐Ÿ†• | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-7\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-7 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views\n- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite`\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) โ€” domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| -------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n\n \n \n \n \"Star\n \n\n\n## ๐ŸŒ StarMapper\n\n\n \n \n \n \"StarMapper\"\n \n\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ€” the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "9e45baae58644a3001b6d1012a461e7f5726184b": {"t": 1785764439.927704, "n": 115599, "h": "e7a87bfcf523e187", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Gemini
\n Gemini CLI\n
\n โญ 94.7K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Structured Combo Builder** โ€” Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets\n- **Quota-Aware P2C** โ€” Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Settings-Driven Lock Hierarchy** โ€” Provider profiles control default account/model lockouts, global model quarantine, and provider circuit breakers from one control surface, while explicit upstream `Retry-After` windows still take priority\n- **Exponential Backoff** โ€” Progressive retry delays for both account/model lockouts and higher-level quarantine\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** โ€” Auto-disables failing providers within a combo chain\n- **Health Dashboard** โ€” Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 100+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** โ€” Configurable defaults in Settings โ†’ Resilience with persistence\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Manual Combo Ordering** โ€” Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n
\n๐Ÿ“š 31. \"My long sessions crash with 'context_length_exceeded' limits\"\n\nDuring deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context.\n\n**How OmniRoute solves it:**\n\n- **Proactive Context Compression** โ€” Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism.\n- **Structural Integrity Guards** โ€” Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors.\n- **Multi-Layer Dropping** โ€” Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic.\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** |\n| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nFor Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration.\n\nFor third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default\n`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`,\nonly forwards client-provided `cache_control` markers. If the request does not include\n`cache_control`, OmniRoute does not inject bridge-owned markers.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nFor streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`).\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.6 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.6.x Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŒ **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` โ€” full streaming over WS with session auth (API key or session cookie) |\n| ๐Ÿ”‘ **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling |\n| ๐Ÿง  **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing โ€” Claude-compatible API |\n| ๐Ÿ”ข **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation โ€” accurate usage tracking without guessing |\n| ๐ŸŒฑ **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup โ€” no more routing mismatches |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection |\n| ๐Ÿ”„ **Cooldown-Aware Retries** | Chat requests auto-retry on model-scoped cooldowns with configurable `requestRetry` and `maxRetryIntervalSec` |\n| ๐Ÿ” **Runtime Env Validation** | Startup validates all env vars with Zod schemas โ€” clear errors for missing secrets, invalid URLs, or wrong types |\n| ๐Ÿ“‹ **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging |\n| ๐Ÿ” **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) โ€” quick performance at-a-glance for every request |\n| ๐Ÿ—‘๏ธ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything โ€” clean removal for all install methods |\n| ๐Ÿ”ง **OAuth Env Repair** | One-click \"Repair env\" action for OAuth providers restores missing env vars and fixes broken auth state |\n| ๐Ÿ”’ **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close |\n| ๐Ÿ‘๏ธ **Model Visibility Toggle** | Per-model visibility toggle (๐Ÿ‘ icon) with search filter and active-count badge (`N/M active`) on provider pages |\n| ๐Ÿ“ง **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover |\n| ๐Ÿ”— **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | --------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿ“Š **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n| ๐Ÿ›ก๏ธ **Safe Outbound Fetch** ๐Ÿ†• | Guarded fetch for provider calls โ€” blocks private/local URLs, retries, SSRF protection |\n| ๐Ÿ”„ **Cooldown-Aware Retries** ๐Ÿ†• | Auto-retry chat on model cooldowns; configurable `requestRetry` / `maxRetryIntervalSec` |\n| ๐Ÿ” **Runtime Env Validation** ๐Ÿ†• | Zod-based env schema validation at startup with actionable error messages |\n| ๐Ÿ“‹ **Compliance Audit v2** ๐Ÿ†• | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** ๐Ÿ†• | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n| ๐Ÿ” **TPS Log Metric** ๐Ÿ†• | Tokens Per Second badge in log details modal |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n| ๐ŸŒ **V1 WebSocket Bridge** ๐Ÿ†• | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` |\n| ๐Ÿ”‘ **Sync Tokens & Bundle** ๐Ÿ†• | Config sync tokens + versioned bundle endpoint with ETag support |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) โ€” domain state, proxy logs, MCP audit, routing decisions, memory, skills\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| -------------------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |\n| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |\n| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **218+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ€” the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "86fc7841b89371eb813a00922bc526662ab3bad6": {"t": 1785764442.4027174, "n": 108963, "h": "23a9e40aba54bab9", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Gemini
\n Gemini CLI\n
\n โญ 94.7K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 100+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Circuit Breaker per-model** โ€” Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks\n- **Exponential Backoff** โ€” Progressive retry delays\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** โ€” Auto-disables failing providers within a combo chain\n- **Health Dashboard** โ€” Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 100+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** โ€” Configurable defaults in Settings โ†’ Resilience with persistence\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Manual Combo Ordering** โ€” Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** |\n| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream fetch, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Total upstream request timeout used by the main fetch abort signal |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.5 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.5.5 Highlights (Apr 2026)\n\n| Feature | What It Does |\n| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”— **Context Relay Strategy** | New combo strategy that preserves session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config โ€” no more bypass in restricted envs |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner with instructions |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF files attached in chat messages are now correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | -------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿ“Š **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** ๐Ÿ†• | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| ----------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ€” the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "87c82071c0c514831e549fc2e9ac7306708a017d": {"t": 1785764444.5941145, "n": 108760, "h": "30560fd73dc7dad1", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md)\n\n---\n\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Gemini
\n Gemini CLI\n
\n โญ 94.7K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Circuit Breaker per-model** โ€” Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks\n- **Exponential Backoff** โ€” Progressive retry delays\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** โ€” Auto-disables failing providers within a combo chain\n- **Health Dashboard** โ€” Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** โ€” Configurable defaults in Settings โ†’ Resilience with persistence\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Manual Combo Ordering** โ€” Drag combo cards by handle and persist the order in SQLite\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** |\n| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| --- | --- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream fetch, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Total upstream request timeout used by the main fetch abort signal |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.5 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.5.5 Highlights (Apr 2026)\n\n| Feature | What It Does |\n| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”— **Context Relay Strategy** | New combo strategy that preserves session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config โ€” no more bypass in restricted envs |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner with instructions |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF files attached in chat messages are now correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | -------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿ“Š **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** ๐Ÿ†• | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| ----------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ€” the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "1442c47bbb68383fc4a1c7295898cc8823d37274": {"t": 1785764446.3066685, "n": 108110, "h": "b1503eadf726a19c", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Gemini
\n Gemini CLI\n
\n โญ 94.7K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Circuit Breaker per-model** โ€” Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks\n- **Exponential Backoff** โ€” Progressive retry delays\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** โ€” Auto-disables failing providers within a combo chain\n- **Health Dashboard** โ€” Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** โ€” Configurable defaults in Settings โ†’ Resilience with persistence\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** |\n| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream fetch, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Total upstream request timeout used by the main fetch abort signal |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.5 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.5.5 Highlights (Apr 2026)\n\n| Feature | What It Does |\n| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”— **Context Relay Strategy** | New combo strategy that preserves session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config โ€” no more bypass in restricted envs |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner with instructions |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF files attached in chat messages are now correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | -------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿ“Š **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** ๐Ÿ†• | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| ----------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ€” the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "581ff5fc73df3de6f3577f993735a3ea5692d757": {"t": 1785764448.4087706, "n": 108160, "h": "ba525ca7a76c4fd9", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md)\n\n---\n\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Gemini
\n Gemini CLI\n
\n โญ 94.7K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**)\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Circuit Breaker per-model** โ€” Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks\n- **Exponential Backoff** โ€” Progressive retry delays\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** โ€” Auto-disables failing providers within a combo chain\n- **Health Dashboard** โ€” Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** โ€” Configurable defaults in Settings โ†’ Resilience with persistence\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** |\n| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream fetch, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Total upstream request timeout used by the main fetch abort signal |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport LOG_TO_FILE=\"${LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v3.5 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” v3.5.5 Highlights (Apr 2026)\n\n| Feature | What It Does |\n| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”— **Context Relay Strategy** | New combo strategy that preserves session continuity via structured handoff summaries when accounts rotate mid-conversation |\n| ๐Ÿ›ก๏ธ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config โ€” no more bypass in restricted envs |\n| โš ๏ธ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner with instructions |\n| ๐Ÿ“Ž **Gemini PDF Attachments** | PDF files attached in chat messages are now correctly routed to Gemini via `inline_data` and generic base64 detection |\n| ๐Ÿ”’ **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts |\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 13 balancing strategies + fallback chain control |\n| ๐Ÿ”— **Context Relay** | Session continuity handoffs when account rotation happens mid-session |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | -------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿ“Š **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** ๐Ÿ†• | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| ---------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Context Relay](docs/features/context-relay.md)| Session handoff strategy for account rotation |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ€” the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "5085dcf96f72bc3ddaf7ac4473bbf9dba31e340b": {"t": 1785764450.11344, "n": 111940, "h": "55b876e65b1b0a21", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Vรกลก univerzรกlnรญ API proxy โ€“ jeden koncovรฝ bod, 60+ poskytovatelลฏ, nulovรฉ prostoje. Nynรญ s**MCP Server (25 nรกstrojลฏ)**,**Protokol A2A**,**Pamฤ›ลฅ/Skills Systems**a**Electron Desktop App**._\n\n**Dokonฤenรญ chatu โ€ข Vloลพenรญ โ€ข Generovรกnรญ obrรกzkลฏ โ€ข Video โ€ข Hudba โ€ข Zvuk โ€ข Zmฤ›na poล™adรญ โ€ข**Vyhledรกvรกnรญ na webu**โ€ข Server MCP โ€ข Protokol A2A โ€ข 100% TypeScript**---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Web](https://omniroute.online) โ€ข [๐Ÿš€ Rychlรฝ start](#-rychlรฝ start) โ€ข [๐Ÿ’ก Funkce](#-klรญฤovรฝch-funkcรญ) โ€ข [๐Ÿ“– Dokumenty](#-dokumentace) โ€ข [๐Ÿ’ฐ Cena](#-cena-na prvnรญ pohled) โ€ข [๐Ÿฌ’ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
\n\n๐ŸŒ**Dostupnรฉ v:**๐Ÿ‡บ๐Ÿ‡ธ [anglicky](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Maฤarลกtina](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n\nKliknutรญm zobrazรญte snรญmky obrazovky ล™รญdicรญho panelu\n\n| Strana | Snรญmek obrazovky |\n| --------------------- | --------------------------------------------------- | ---------- |\n| **Poskytovatelรฉ** | ![Poskytovatelรฉ](docs/screenshots/01-providers.png) |\n| **Komba** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Zdravรญ** | ![Zdravรญ](docs/screenshots/04-health.png) |\n| **Pล™ekladatel** | ![Translator](docs/screenshots/05-translator.png) |\n| **Nastavenรญ** | ![Nastavenรญ](docs/screenshots/06-settings.png) |\n| **Nรกstroje CLI** | ![Nรกstroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly pouลพitรญ** | ![Pouลพitรญ](docs/screenshots/08-usage.png) |\n| **Koncovรฉ body** | ![Koncovรฉ body](docs/screenshots/09-endpoint.png) |
|\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Pล™ipojte jakรฝkoli nรกstroj IDE nebo CLI s umฤ›lou inteligencรญ prostล™ednictvรญm OmniRoute โ€“ bezplatnรฉ brรกny API pro neomezenรฉ kรณdovรกnรญ._\n\n \n \n \n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205ย 000\n \n \n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20,9ย 000\n \n \n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14,6ย 000\n \n \n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9,9ย 000\n \n \n \n \"ลฝeleznรฝ
\n IronClaw\n
\n โญ 2,1ย 000\n \n \n \n \n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106ย 000\n \n \n \n \"Codex
\n Codex CLI\n
\n โญ 60,8ย 000\n \n \n \n \"Kรณd
\n Claude Code\n
\n โญ 67,3ย 000\n \n \n \n \"Gemini
\n Gemini CLI\n
\n โญ 94,7ย 000\n \n \n \n \"Kilokรณd\"
\n Kilovรฝ kรณd\n
\n โญ 15,5ย 000\n \n \n \n\n๐Ÿ“ก Vลกichni agenti se pล™ipojujรญ pล™es http://localhost:20128/v1 nebo http://cloud.omniroute.online/v1 โ€” jedna konfigurace, neomezenรฉ modely a kvรณta---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Pล™estaลˆte plรฝtvat penฤ›zi a narรกลพet na limity:**\n\nโ€“ Kvรณta pล™edplatnรฉho vyprลกรญ nevyuลพita kaลพdรฝ mฤ›sรญc\nโ€“ Omezenรญ sazby vรกm brรกnรญ uprostล™ed kรณdovรกnรญ\nโ€“ Drahรก rozhranรญ API (20โ€“50 $ mฤ›sรญฤnฤ› na poskytovatele)\n\n- Ruฤnรญ pล™epรญnรกnรญ mezi poskytovateli\n\n**OmniRoute to ล™eลกรญ:**\n\n- โœ…**Maximalizujte odbฤ›ry**- Sledujte kvรณtu, pล™ed resetovรกnรญm pouลพijte kaลพdรฝ bit\n- โœ…**Automatickรก zรกloha**- Pล™edplatnรฉ โ†’ Klรญฤ API โ†’ Levnรฉ โ†’ Zdarma, nulovรฉ prostoje\n- โœ…**Vรญce รบฤtลฏ**- Round-robin mezi รบฤty na poskytovatele\n- โœ…**Universal**- Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, jakรฝmkoliv nรกstrojem CLI---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ**Pล™ipojte se k naลกรญ komunitฤ›!**[Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Zรญskejte nรกpovฤ›du, sdรญlejte tipy a buฤte v obraze.\n\n-**Web**: [omniroute.online](https://omniroute.online) -**GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute) -**Problรฉmy**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -**WhatsApp**: [Skupina komunity](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) -**Pล™ispรญvรกnรญ**: Podรญvejte se na [CONTRIBUTING.md](CONTRIBUTING.md), otevล™ete PR nebo si vyberte โ€ždobrรฉ prvnรญ ฤรญsloโ€œ -**Pลฏvodnรญ projekt**: [9router by decolua](https://github.com/decolua/9router)### ๐Ÿ› Reporting a Bug?\n\nPล™i otevรญrรกnรญ problรฉmu spusลฅte pล™รญkaz system-info a pล™ipojte vygenerovanรฝ soubor:```bash\nnpm run system-info\n\n```\n\nTรญm se vygeneruje soubor `system-info.txt` s vaลกรญ verzรญ Node.js, verzรญ OmniRoute, podrobnostmi OS, nainstalovanรฝmi nรกstroji CLI (qoder, gemini, claude, codex, antigravity, droid atd.), stavem Docker/PM2 a systรฉmovรฝmi balรญฤky โ€“ vลกe, co potล™ebujeme k rychlรฉ reprodukci vaลกeho problรฉmu. Pล™ipojte soubor pล™รญmo k vaลกemu problรฉmu na GitHubu.---\n\n## ๐Ÿ”„ How It Works\n\n```\n\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\nโ”‚ http://localhost:20128/v1\nโ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\nโ”‚\nโ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\nโ”‚ โ†“ quota exhausted\nโ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\nโ”‚ โ†“ budget limit\nโ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\nโ”‚ โ†“ budget limit\nโ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n\n````\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n>**Kaลพdรฝ vรฝvojรกล™ pouลพรญvajรญcรญ nรกstroje AI ฤelรญ tฤ›mto problรฉmลฏm dennฤ›.**OmniRoute byl vytvoล™en tak, aby je vyล™eลกil vลกechny โ€“ od pล™ekroฤenรญ nรกkladลฏ po regionรกlnรญ bloky, od pล™eruลกenรฝch tokลฏ OAuth po operace protokolลฏ a podnikovรก pozorovatelnost.\n\n\n๐Ÿ’ธ 1. โ€žPlatรญm za drahรฉ pล™edplatnรฉ, ale stรกle mฤ› vyruลกujรญ limityโ€œ\n\nVรฝvojรกล™i platรญ 20โ€“200 $ mฤ›sรญฤnฤ› za Claude Pro, Codex Pro nebo GitHub Copilot. I pล™i placenรญ mรก kvรณta strop โ€“ 5 hodin pouลพรญvรกnรญ, tรฝdennรญ limity nebo limity sazby za minutu. Uprostล™ed relace kรณdovรกnรญ poskytovatel pล™estane reagovat a vรฝvojรกล™ ztrรกcรญ tok a produktivitu.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n-**Chytrรฝ 4-รบrovลˆovรฝ zรกloลพnรญ zdroj**โ€“ Pokud dojde k vyฤerpรกnรญ kvรณty pล™edplatnรฉho, automaticky se pล™esmฤ›ruje na klรญฤ API โ†’ Levnรฉ โ†’ Zdarma s nulovรฝm ruฤnรญm zรกsahem\n-**Sledovรกnรญ limitลฏ poskytovatele**โ€“ Snรญmky kvรณt v mezipamฤ›ti se obnovujรญ podle plรกnu na stranฤ› serveru (vรฝchozรญ `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) s moลพnostรญ ruฤnรญho obnovenรญ v uลพivatelskรฉm rozhranรญ\nโ€“**Podpora vรญce รบฤtลฏ**โ€“ Vรญce รบฤtลฏ na poskytovatele s automatickรฝm opakovรกnรญm โ€“ kdyลพ jeden dojde, pล™epne se na dalลกรญ\n-**Vlastnรญ komba**โ€“ Pล™izpลฏsobitelnรฉ zรกloลพnรญ ล™etฤ›zce s 9 strategiemi vyvaลพovรกnรญ (prioritnรญ, vรกลพenรก, na prvnรญm mรญstฤ›, s cyklem, P2C, nรกhodnรก, nejmรฉnฤ› pouลพรญvanรก, nรกkladovฤ› optimalizovanรก, striktnฤ› nรกhodnรก)\n-**Codex Business Quotas**โ€” Sledovรกnรญ kvรณt Business/Tรฝm pracovnรญho prostoru pล™รญmo na ล™รญdicรญm panelu
\n\n\n๐Ÿ”Œ 2. โ€žPotล™ebuji pouลพรญvat vรญce poskytovatelลฏ, ale kaลพdรฝ mรก jinรฉ APIโ€œ\n\nOpenAI pouลพรญvรก jeden formรกt, Claude (Anthropic) jinรฝ a Gemini jeลกtฤ› jinรฝ. Pokud chce vรฝvojรกล™ testovat modely od rลฏznรฝch poskytovatelลฏ nebo mezi nimi couvnout, musรญ pล™ekonfigurovat sady SDK, zmฤ›nit koncovรฉ body, vypoล™รกdat se s nekompatibilnรญmi formรกty. Vlastnรญ poskytovatelรฉ (FriendLI, NIM) majรญ nestandardnรญ koncovรฉ body modelu.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n-**Unified Endpoint**โ€“ Jedinรฝ `http://localhost:20128/v1` slouลพรญ jako proxy pro vลกech 60+ poskytovatelลฏ\n-**Formรกtovรฝ pล™eklad**โ€” Automatickรฝ a transparentnรญ: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n-**Response Sanitization**โ€“ Odstraลˆuje nestandardnรญ pole (`x_groq`, `usage_breakdown`, `service_tier`), kterรก poruลกujรญ OpenAI SDK v1.83+\n-**Normalizace rolรญ**โ€” Pล™evรกdรญ `vรฝvojรกล™` โ†’ `systรฉm` pro poskytovatele, kteล™รญ nejsou OpenAI; `systรฉm` โ†’ `uลพivatel` pro GLM/ERNIE\nโ€“**Think Tag Extraction**โ€“ Extrahuje bloky โ€žโ€œ z modelลฏ jako DeepSeek R1 do standardizovanรฉho โ€žreasoning_contentโ€œ\n-**Strukturovanรฝ vรฝstup pro Gemini**โ€” `json_schema` โ†’ automatickรฝ pล™evod `responseMimeType`/`responseSchema`\n-**`stream` mรก vรฝchozรญ hodnotu `false`**โ€” Vyhovuje specifikaci OpenAI a zabraลˆuje neoฤekรกvanรฉmu SSE v sadรกch Python/Rust/Go SDK\n\n\n๐ŸŒ 3. โ€žMลฏj poskytovatel umฤ›lรฉ inteligence blokuje mลฏj region/zemฤ›โ€œ\n\nPoskytovatelรฉ jako OpenAI/Codex blokujรญ pล™รญstup z urฤitรฝch geografickรฝch oblastรญ. Bฤ›hem pล™ipojenรญ OAuth a rozhranรญ API se uลพivatelลฏm zobrazujรญ chyby jako โ€žunsupported_country_region_territoryโ€œ. To je frustrujรญcรญ zejmรฉna pro vรฝvojรกล™e z rozvojovรฝch zemรญ.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\nโ€“**3รบrovลˆovรก konfigurace proxy**โ€“ konfigurovatelnรฝ proxy na 3 รบrovnรญch: globรกlnรญ (veลกkerรฝ provoz), podle poskytovatele (pouze jeden poskytovatel) a podle pล™ipojenรญ/klรญฤe\n-**Barevnฤ› kรณdovanรฉ odznaky proxy**โ€” Vizuรกlnรญ indikรกtory: ๐Ÿขข globรกlnรญ proxy, ๐ŸŸก proxy poskytovatele, ๐Ÿ”ต proxy pล™ipojenรญ, vลพdy zobrazujรญcรญ IP\n-**Vรฝmฤ›na tokenลฏ OAuth pล™es proxy**โ€“ tok OAuth prochรกzรญ takรฉ pล™es proxy a ล™eลกรญ se `unsupported_country_region_territory`\n-**Testy pล™ipojenรญ pล™es proxy**โ€” Testy pล™ipojenรญ pouลพรญvajรญ nakonfigurovanรฝ proxy (uลพ ลพรกdnรฉ pล™รญmรฉ obchรกzenรญ)\n-**Podpora SOCKS5**โ€” Plnรก podpora proxy SOCKS5 pro odchozรญ smฤ›rovรกnรญ\n-**TLS Fingerprint Spoofing**โ€“ TLS otisk prstu podobnรฝ prohlรญลพeฤi pล™es `wreq-js` k obejitรญ detekce botลฏ\n-**๐Ÿ” CLI Fingerprint Matching**โ€“ Zmฤ›nรญ poล™adรญ hlaviฤek a polรญ tฤ›la tak, aby odpovรญdaly nativnรญm binรกrnรญm podpisลฏm CLI, ฤรญmลพ se vรฝraznฤ› snรญลพรญ riziko oznaฤenรญ รบฤtu. IP proxy serveru je zachovรกna โ€“ zรญskรกte souฤasnฤ› maskovรกnรญ IP maskovรกnรญ**a**utajenรญ\n\n\n๐Ÿ†“ 4. โ€žChci pouลพรญvat AI pro kรณdovรกnรญ, ale nemรกm penรญzeโ€œ\n\nNe kaลพdรฝ mลฏลพe platit 20โ€“200 $ mฤ›sรญฤnฤ› za pล™edplatnรฉ AI. Studenti, vรฝvojรกล™i z rozvรญjejรญcรญch se zemรญ, fandovรฉ a nezรกvislรญ pracovnรญci potล™ebujรญ pล™รญstup ke kvalitnรญm modelลฏm za nulovรฉ nรกklady.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n-**Vestavฤ›nรญ poskytovatelรฉ bezplatnรฝch รบrovnรญ**โ€” Nativnรญ podpora pro 100% bezplatnรฉ poskytovatele: Qoder (5 neomezenรฝch modelลฏ prostล™ednictvรญm OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezenรฉ modely: qwen3-qwender-lash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 000 tokenลฏ/mฤ›sรญc zdarma)\n-**Ollama Cloud**โ€“ modely Ollama hostovanรฉ v cloudu na `api.ollama.com` s bezplatnou รบrovnรญ โ€žLight useโ€œ; pouลพijte pล™edponu `ollamacloud/`\nโ€“**komba pouze zdarma**โ€“ ล™etฤ›zec `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = 0 $/mฤ›sรญc s nulovรฝmi prostoji\n-**Volnรฝ pล™รญstup NVIDIA NIM**โ€” ~40 RPM pro vรฝvojรกล™e - navลพdy bezplatnรฝ pล™รญstup k vรญce neลพ 70 modelลฏm na build.nvidia.com (pล™echod z kreditลฏ na limity ฤistรฉ sazby)\n-**Cost Optimized Strategy**โ€“ Strategie smฤ›rovรกnรญ, kterรก automaticky vybรญrรก nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n\n๐Ÿ”’ 5. โ€žPotล™ebuji chrรกnit svou brรกnu AI pล™ed neoprรกvnฤ›nรฝm pล™รญstupemโ€œ\n\nPล™i vystavenรญ brรกny AI do sรญtฤ› (LAN, VPS, Docker) mลฏลพe kdokoli s adresou spotล™ebovat tokeny/kvรณtu vรฝvojรกล™e. Bez ochrany jsou rozhranรญ API zranitelnรก vลฏฤi zneuลพitรญ, rychlรฉmu vloลพenรญ a zneuลพitรญ.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n-**Sprรกva klรญฤลฏ API**โ€“ Generovรกnรญ, rotace a rozsah podle poskytovatele pomocรญ vyhrazenรฉ strรกnky `/dashboard/api-manager`\n-**Oprรกvnฤ›nรญ na รบrovni modelu**โ€“ Omezte klรญฤe API na konkrรฉtnรญ modely (`openai/*`, vzory zรกstupnรฝch znakลฏ) pomocรญ pล™epรญnaฤe Povolit vลกe/Omezit\n-**API Endpoint Protection**โ€“ Vyลพadovat klรญฤ pro `/v1/models` a blokovat konkrรฉtnรญ poskytovatele ze seznamu\n-**Auth Guard + ochrana CSRF**โ€“ Vลกechny cesty ล™รญdicรญho panelu chrรกnฤ›ny middlewarem โ€žwithAuthโ€œ + tokeny CSRF\n-**Rate Limiter**โ€” omezenรญ rychlosti na IP pomocรญ konfigurovatelnรฝch oken\n-**IP Filtering**โ€” Seznam povolenรฝch/blokovanรฝch pro ล™รญzenรญ pล™รญstupu\n-**Prompt Injection Guard**โ€“ Dezinfekce proti ลกkodlivรฝm vzorลฏm vรฝzev\n-**ล ifrovรกnรญ AES-256-GCM**โ€” Pล™ihlaลกovacรญ รบdaje jsou v klidu zaลกifrovรกny\n\n\n๐Ÿ›‘ 6. \"Mลฏj poskytovatel selhal a ztratil jsem tok kรณdovรกnรญ\"\n\nPoskytovatelรฉ umฤ›lรฉ inteligence se mohou stรกt nestabilnรญmi, vracet chyby 5xx nebo narazit na doฤasnรฉ limity sazeb. Pokud vรฝvojรกล™ zรกvisรญ na jedinรฉm poskytovateli, je pล™eruลกen. Bez jistiฤลฏ mohou opakovanรฉ pokusy zpลฏsobit selhรกnรญ aplikace.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n-**Jistiฤ pro kaลพdรฝ model**โ€” Automatickรฉ otevรญrรกnรญ/zavรญrรกnรญ s konfigurovatelnรฝmi prahovรฝmi hodnotami a ochlazenรญm (zavล™eno/otevล™eno/polootevล™eno), s rozsahem pro kaลพdรฝ model, aby se zabrรกnilo kaskรกdovรฝm blokลฏm\n-**Exponential Backoff**โ€” Progresivnรญ zpoลพdฤ›nรญ opakovรกnรญ\n-**Anti-Thundering Herd**โ€” Mutex + semaforovรก ochrana proti soubฤ›ลพnรฝm opakovanรฝm bouล™รญm\n-**Combo Fallback Chains**โ€” Pokud primรกrnรญ poskytovatel selลพe, automaticky projde ล™etฤ›zcem bez zรกsahu\n-**Combo Circuit Breaker**โ€“ Automaticky deaktivuje selhรกvajรญcรญ poskytovatele v rรกmci kombinovanรฉho ล™etฤ›zce\nโ€“**Health Dashboard**โ€“ Monitorovรกnรญ provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti, latence p50/p95/p99\n\n\n๐Ÿ”ง 7. โ€žKonfigurace kaลพdรฉho nรกstroje umฤ›lรฉ inteligence je รบnavnรก a opakujรญcรญ seโ€œ\n\nVรฝvojรกล™i pouลพรญvajรญ Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Kaลพdรฝ nรกstroj potล™ebuje jinou konfiguraci (API endpoint, klรญฤ, model). Pล™ekonfigurovรกnรญ pล™i zmฤ›nฤ› poskytovatele nebo modelu je ztrรกta ฤasu.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n-**CLI Tools Dashboard**โ€“ Vyhrazenรก strรกnka s nastavenรญm jednรญm kliknutรญm pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\nโ€“**GitHub Copilot Config Generator**โ€“ Generuje `chatLanguageModels.json` pro kรณd VS s hromadnรฝm vรฝbฤ›rem modelu\n-**Prลฏvodce pล™ihlรกลกenรญm**โ€“ Prลฏvodce nastavenรญm ve 4 krocรญch pro zaฤรญnajรญcรญ uลพivatele\nโ€“**Jeden koncovรฝ bod, vลกechny modely**โ€“ Jednou nakonfigurujte `http://localhost:20128/v1`, zรญskรกte pล™รญstup k vรญce neลพ 60 poskytovatelลฏm\n\n\n๐Ÿ”‘ 8. โ€žSprรกva tokenลฏ OAuth od vรญce poskytovatelลฏ je pekloโ€œ\n\nClaude Code, Codex, Gemini CLI, Copilot โ€“ vลกechny pouลพรญvajรญ OAuth 2.0 s konฤรญcรญmi tokeny. Vรฝvojรกล™i se musรญ neustรกle znovu autentizovat, ล™eลกit `client_secret is missing`, `redirect_uri_mismatch` a selhรกnรญ na vzdรกlenรฝch serverech. Zvlรกลกtฤ› problematickรฉ je OAuth na LAN/VPS.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n-**Automatickรฉ obnovenรญ tokenu**โ€“ Tokeny OAuth se pล™ed vyprลกenรญm platnosti obnovujรญ na pozadรญ\n-**Vestavฤ›nรฝ OAuth 2.0 (PKCE)**โ€” Automatickรฝ tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\nโ€“**Multi-Account OAuth**โ€“ Vรญce รบฤtลฏ na poskytovatele prostล™ednictvรญm extrakce tokenลฏ JWT/ID\n-**OAuth LAN/Remote Fix**โ€” Detekce privรกtnรญ IP adresy pro `redirect_uri` + ruฤnรญ reลพim URL pro vzdรกlenรฉ servery\n-**OAuth Behind Nginx**โ€“ Pouลพรญvรก `window.location.origin` pro zpฤ›tnou kompatibilitu proxy\nโ€“**Prลฏvodce vzdรกlenรฝm OAuth**โ€“ Podrobnรฝ prลฏvodce pro pล™ihlaลกovacรญ รบdaje Google Cloud na VPS/Docker\n\n\n๐Ÿ“Š 9. \"Nevรญm, kolik a kde utrรกcรญm\"\n\nVรฝvojรกล™i vyuลพรญvajรญ vรญce placenรฝch poskytovatelลฏ, ale nemajรญ jednotnรฝ pohled na vรฝdaje. Kaลพdรฝ poskytovatel mรก svลฏj vlastnรญ panel fakturace, ale neexistuje ลพรกdnรฉ konsolidovanรฉ zobrazenรญ. Neoฤekรกvanรฉ nรกklady se mohou nahromadit.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n-**Cost Analytics Dashboard**โ€“ Sledovรกnรญ nรกkladลฏ na token a sprรกva rozpoฤtu na poskytovatele\n-**Rozpoฤtovรฉ limity na รบroveลˆ**โ€“ Strop รบtraty na รบroveลˆ, kterรฝ spouลกtรญ automatickou rezervu\n-**Konfigurace cen za model**โ€“ Konfigurovatelnรฉ ceny za model\n-**Statistika vyuลพitรญ na klรญฤ API**โ€” Poฤet poลพadavkลฏ a naposledy pouลพitรฉ ฤasovรฉ razรญtko na klรญฤ\nโ€“**Panel Analytics**โ€“ Statistickรฉ karty, graf vyuลพitรญ modelu, tabulka poskytovatelลฏ s mรญrou รบspฤ›ลกnosti a latencรญ\n\n\n๐Ÿ› 10. โ€žNemohu diagnostikovat chyby a problรฉmy ve volรกnรญch AIโ€œ\n\nKdyลพ se volรกnรญ nezdaล™รญ, vรฝvojรกล™ nevรญ, zda to byl limit sazby, vyprลกela platnost tokenu, nesprรกvnรฝ formรกt nebo chyba poskytovatele. Fragmentovanรฉ protokoly napล™รญฤ rลฏznรฝmi terminรกly. Bez pozorovatelnosti je ladฤ›nรญ metodou pokus-omyl.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n-**Sjednocenรฝ panel protokolลฏ**โ€“ 4 karty: Protokoly poลพadavkลฏ, Protokoly proxy, Protokoly auditu, Konzole\n-**Console Log Viewer**โ€” Prohlรญลพeฤ ve stylu terminรกlu v reรกlnรฉm ฤase s barevnฤ› odliลกenรฝmi รบrovnฤ›mi, automatickรฝm posouvรกnรญm, vyhledรกvรกnรญm, filtrem\n-**Protokoly SQLite Proxy**โ€” Trvalรฉ protokoly, kterรฉ vydrลพรญ restartovรกnรญ serveru\n-**Translator Playground**โ€” 4 reลพimy ladฤ›nรญ: Playground (pล™eklad formรกtu), Tester chatu (zpรกteฤnรญ), Test Bench (dรกvka), Live Monitor (v reรกlnรฉm ฤase)\nโ€“**Poลพadavek na telemetrii**โ€“ latence p50/p95/p99 + sledovรกnรญ X-Request-Id\n-**Protokolovรกnรญ zaloลพenรฉ na souborech s rotacรญ**โ€“ Protokoly aplikacรญ se stล™รญdajรญ podle velikosti, dnลฏ uchovรกnรญ a poฤtu archivลฏ; Artefakty protokolu hovorลฏ rotujรญ podle dnลฏ uchovรกnรญ a poฤtu souborลฏ\n-**System Info Report**โ€” `npm run system-info` vygeneruje `system-info.txt` s vaลกรญm รบplnรฝm prostล™edรญm (verze uzlu, verze OmniRoute, OS, nรกstroje CLI, stav Docker/PM2). Pล™ipojte jej pล™i hlรกลกenรญ problรฉmลฏ pro okamลพitรฉ tล™รญdฤ›nรญ.\n\n\n๐Ÿ—๏ธ 11. โ€žNasazenรญ a รบdrลพba brรกny je sloลพitรกโ€œ\n\nInstalace, konfigurace a รบdrลพba AI proxy v rลฏznรฝch prostล™edรญch (mรญstnรญ, VPS, Docker, cloud) je nรกroฤnรก na prรกci. Problรฉmy jako pevnฤ› zakรณdovanรฉ cesty, โ€žEACCESโ€œ v adresรกล™รญch, konflikty portลฏ a sestavenรญ napล™รญฤ platformami zvyลกujรญ tล™enรญ.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n-**Globรกlnรญ instalace npm**โ€“ `npm install -g omniroute && omniroute` โ€“ hotovo\n-**Docker Multi-Platform**โ€“ nativnรญ AMD64 + ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n-**Docker Compose Profiles**โ€“ `base` (ลพรกdnรฉ nรกstroje CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n-**Electron Desktop App**โ€“ nativnรญ aplikace pro Windows/macOS/Linux se systรฉmovou liลกtou, automatickรฝm spuลกtฤ›nรญm, offline reลพimem\n-**Split-Port Mode**โ€“ API a Dashboard na samostatnรฝch portech pro pokroฤilรฉ scรฉnรกล™e (reverznรญ proxy, kontejnerovรก sรญลฅ)\n-**Cloud Sync**โ€” Konfigurace synchronizace mezi zaล™รญzenรญmi pomocรญ Cloudflare Workers\n-**DB Backups**โ€” Automatickรฉ zรกlohovรกnรญ, obnova, export a import vลกech nastavenรญ s `DISABLE_SQLITE_AUTO_BACKUP` pro externฤ› spravovanรฉ zรกlohy\n\n\n๐ŸŒ 12. \"Rozhranรญ je pouze v angliฤtinฤ› a mลฏj tรฝm nemluvรญ anglicky\"\n\nTรฝmy v neanglicky mluvรญcรญch zemรญch, zejmรฉna v Latinskรฉ Americe, Asii a Evropฤ›, se potรฝkajรญ s rozhranรญm pouze v angliฤtinฤ›. Jazykovรฉ bariรฉry sniลพujรญ pล™ijetรญ a zvyลกujรญ chyby konfigurace.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n-**Dashboard i18n โ€” 30 jazykลฏ**โ€” Vลกech 500+ klรกves pล™eloลพeno vฤetnฤ› arabลกtiny, bulharลกtiny, dรกnลกtiny, nฤ›mฤiny, ลกpanฤ›lลกtiny, finลกtiny, francouzลกtiny, hebrejลกtiny, hindลกtiny, maฤarลกtiny, indonรฉลกtiny, italลกtiny, japonลกtiny, korejลกtiny, malajลกtiny, holandลกtiny, norลกtiny, polลกtiny, portugalลกtiny (PT/BR), rumunลกtiny, ruลกtiny, slovenลกtiny, ลกvรฉdลกtiny, thajลกtiny, filipรญnลกtiny, vietnamลกtiny, angliฤtiny\n-**Podpora RTL**โ€” Podpora zprava doleva pro arabลกtinu a hebrejลกtinu\n-**Vรญcejazyฤnรฉ README**โ€” 30 kompletnรญch pล™ekladลฏ dokumentace\n-**Language Selector**โ€” Ikona zemฤ›koule v zรกhlavรญ pro pล™epรญnรกnรญ v reรกlnรฉm ฤase\n\n\n๐Ÿ”„ 13. โ€žPotล™ebuji vรญc neลพ jen chat โ€“ potล™ebuji vloลพenรญ, obrรกzky, zvukโ€œ\n\nAI nenรญ jen dokonฤenรญ chatu. Vรฝvojรกล™i potล™ebujรญ generovat obrรกzky, pล™episovat zvuk, vytvรกล™et vloลพenรญ pro RAG, mฤ›nit hodnocenรญ dokumentลฏ a moderovat obsah. Kaลพdรฉ API mรก jinรฝ koncovรฝ bod a formรกt.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n-**Vloลพenรญ**โ€” `/v1/embeddings` se 6 poskytovateli a 9+ modely\n-**Generace obrรกzkลฏ**โ€” `/v1/images/generations` s 10 poskytovateli a 20+ modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n-**Text-to-Video**โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) a SD WebUI\n-**Text-to-Music**โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n-**Audio Transscription**โ€” `/v1/audio/transscriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n-**Text-to-Speech**โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3,**Inworld**,**Cartesia**,**PlayHT**, + stรกvajรญcรญ poskytovatelรฉ\n-**Moderations**โ€” `/v1/moderations` โ€” Kontroly bezpeฤnosti obsahu\n-**Pล™ehodnocenรญ**โ€” `/v1/rerank` โ€” Zmฤ›na poล™adรญ podle relevance dokumentu\n-**Responses API**โ€” Plnรก podpora `/v1/responses` pro Codex\n\n\n๐Ÿงช 14. โ€žNemรกm zpลฏsob, jak testovat a porovnรกvat kvalitu napล™รญฤ modelyโ€œ\n\nVรฝvojรกล™i chtฤ›jรญ vฤ›dฤ›t, kterรฝ model je pro jejich pล™รญpad pouลพitรญ nejlepลกรญ โ€“ kรณd, pล™eklad, uvaลพovรกnรญ โ€“ ale ruฤnรญ porovnรกvรกnรญ je pomalรฉ. Neexistujรญ ลพรกdnรฉ integrovanรฉ nรกstroje eval.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n-**Hodnocenรญ LLM**โ€“ Testovรกnรญ zlatรฉ sady s 10 pล™edem nahranรฝmi pล™รญpady zahrnujรญcรญmi pozdravy, matematiku, geografii, generovรกnรญ kรณdu, soulad s JSON, pล™eklad, markdown, bezpeฤnostnรญ odmรญtnutรญ\n-**4 strategie shody**โ€“ `pล™esnรฉ`, `obsahuje`, `regulรกrnรญ vรฝraz`, `vlastnรญ` (funkce JS)\n-**Testovacรญ stolice pro pล™ekladatelskรฉ hล™iลกtฤ›**โ€“ Dรกvkovรฉ testovรกnรญ s vรญce vstupy a oฤekรกvanรฝmi vรฝstupy, porovnรกnรญ mezi poskytovateli\n-**Chat Tester**โ€“ Kompletnรญ zpรกteฤnรญ cesta s vykreslovรกnรญm vizuรกlnรญ odezvy\n-**Live Monitor**โ€” Tok vลกech poลพadavkลฏ prochรกzejรญcรญch pล™es proxy v reรกlnรฉm ฤase\n\n\n๐Ÿ“ˆ 15. โ€žPotล™ebuji ลกkรกlovat bez ztrรกty vรฝkonuโ€œ\n\nJak roste objem poลพadavkลฏ, bez uklรกdรกnรญ stejnรฝch otรกzek do mezipamฤ›ti vznikajรญ duplicitnรญ nรกklady. Bez idempotence duplikรกt poลพaduje zpracovรกnรญ odpadu. Musรญ bรฝt dodrลพeny limity sazeb na poskytovatele.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n-**Sรฉmantickรก mezipamฤ›ลฅ**โ€“ Dvouvrstvรก mezipamฤ›ลฅ (podpis + sรฉmantickรก) sniลพuje nรกklady a latenci\n-**Idempotency poลพadavku**โ€” 5s deduplikaฤnรญ okno pro identickรฉ poลพadavky\nโ€“**Detekce limitu rychlosti**โ€“ RPM na poskytovatele, minimรกlnรญ mezera a maximรกlnรญ soubฤ›ลพnรฉ sledovรกnรญ\n-**Upravitelnรฉ limity rychlosti**โ€“ Konfigurovatelnรฉ vรฝchozรญ hodnoty v Nastavenรญ โ†’ Odolnost s perzistencรญ\n-**API Key Validation Cache**โ€“ 3vrstvรก mezipamฤ›ลฅ pro produkฤnรญ vรฝkon\nโ€“**Health Dashboard s telemetriรญ**โ€“ latence p50/p95/p99, statistiky mezipamฤ›ti, doba provozu\n\n\n๐Ÿค– 16. โ€žChci globรกlnฤ› ovlรกdat chovรกnรญ modeluโ€œ\n\nVรฝvojรกล™i, kteล™รญ chtฤ›jรญ vลกechny odpovฤ›di v konkrรฉtnรญm jazyce, s konkrรฉtnรญm tรณnem nebo chtฤ›jรญ omezit tokeny uvaลพovรกnรญ. Konfigurace tohoto v kaลพdรฉm nรกstroji/poลพadavku je nepraktickรก.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n-**System Prompt Injection**โ€“ Globรกlnรญ vรฝzva aplikovanรก na vลกechny poลพadavky\n-**Thinking Budget Validation**โ€” ล˜รญzenรญ alokace tokenลฏ na zรกkladฤ› poลพadavku (prลฏchozรญ, automatickรฉ, vlastnรญ, adaptivnรญ)\n-**9 smฤ›rovacรญch strategiรญ**โ€” Globรกlnรญ strategie, kterรฉ urฤujรญ zpลฏsob distribuce poลพadavkลฏ\n-**Wildcard Router**โ€“ vzory `poskytovatel/*` se dynamicky smฤ›rujรญ k libovolnรฉmu poskytovateli\n-**Povolit/zakรกzat pล™epรญnรกnรญ komba**โ€” Pล™epรญnejte komba pล™รญmo z ล™รญdicรญho panelu\n-**Pล™epnutรญ poskytovatele**โ€” Povolรญ/zakรกลพe vลกechna pล™ipojenรญ pro poskytovatele jednรญm kliknutรญm\nโ€“**Blokovanรญ poskytovatelรฉ**โ€“ vylouฤenรญ konkrรฉtnรญch poskytovatelลฏ ze seznamu `/v1/models`\n\n\n๐Ÿงฐ 17. โ€žPotล™ebuji nรกstroje MCP jako prvotล™รญdnรญ moลพnosti produktuโ€œ\n\nMnoho bran AI odhaluje MCP pouze jako skrytรฝ detail implementace. Tรฝmy potล™ebujรญ viditelnou a spravovatelnou provoznรญ vrstvu.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n- MCP se objevรญ na navigaฤnรญm panelu a na kartฤ› protokolu koncovรฉho bodu\n- Vyhrazenรก strรกnka sprรกvy MCP s procesem, nรกstroji, rozsahy a auditem\n- Vestavฤ›nรฝ rychlรฝ start pro `omniroute --mcp` a pล™ihlรกลกenรญ klienta\n\n\n๐Ÿง  18. โ€žPotล™ebuji orchestraci A2A s cestami synchronizace + streamovรกnรญโ€œ\n\nPracovnรญ postupy agentลฏ vyลพadujรญ jak pล™รญmรฉ odpovฤ›di, tak dlouhotrvajรญcรญ streamovanรฉ spouลกtฤ›nรญ s ล™รญzenรญm ลพivotnรญho cyklu.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\nโ€“ Koncovรฝ bod A2A JSON-RPC (`POST /a2a`) s `zprรกvou/odeslat` a `zprรกvou/streamem`\n- SSE streamovรกnรญ s ลกรญล™enรญm koncovรฉho stavu\n- Rozhranรญ API ลพivotnรญho cyklu รบloh pro `tasks/get` a `tasks/cancel`\n\n\n๐Ÿ›ฐ๏ธ 19. โ€žPotล™ebuji skuteฤnรฝ stav procesu MCP, nikoli odhadovanรฝ stavโ€œ\n\nOperaฤnรญ tรฝmy potล™ebujรญ vฤ›dฤ›t, zda je MCP skuteฤnฤ› naลพivu, nejen zda je API dosaลพitelnรฉ.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n- Soubor srdeฤnรญho tepu za bฤ›hu s PID, ฤasovรฝmi razรญtky, transportem, poฤtem nรกstrojลฏ a reลพimem rozsahu\n- Stavovรฉ API MCP kombinujรญcรญ srdeฤnรญ tep + nedรกvnou aktivitu\n- Stavovรฉ karty uลพivatelskรฉho rozhranรญ pro aktuรกlnost procesu / provozuschopnosti / srdeฤnรญho tepu\n\n\n๐Ÿ“‹ 20. โ€žPotล™ebuji provรกdฤ›nรญ auditovatelnรฉho nรกstroje MCPโ€œ\n\nKdyลพ nรกstroje mutujรญ konfiguraci nebo spouลกtฤ›jรญ operace operacรญ, tรฝmy potล™ebujรญ forenznรญ sledovatelnost.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n- Protokolovรกnรญ auditu podporovanรฉ SQLite pro volรกnรญ nรกstrojลฏ MCP\n- Filtry podle nรกstroje, รบspฤ›chu/neรบspฤ›chu, klรญฤe API a strรกnkovรกnรญ\n- Tabulka auditu ล™รญdicรญho panelu + statistiky koncovรฝch bodลฏ pro automatizaci\n\n\n๐Ÿ” 21. โ€žPotล™ebuji omezenรก oprรกvnฤ›nรญ MCP na integraciโ€œ\n\nRลฏznรญ klienti by mฤ›li mรญt nejmรฉnฤ› privilegovanรฝ pล™รญstup ke kategoriรญm nรกstrojลฏ.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n- 10 granulรกrnรญch rozsahลฏ MCP pro ล™รญzenรฝ pล™รญstup k nรกstrojลฏm\n- Vynucenรญ rozsahu a viditelnost v uลพivatelskรฉm rozhranรญ sprรกvy MCP\n- Bezpeฤnรก vรฝchozรญ poloha pro provoznรญ nรกstroje\n\n\nโš™๏ธ 22. โ€žPotล™ebuji provoznรญ kontroly bez pล™erozdฤ›lovรกnรญโ€œ\n\nTรฝmy potล™ebujรญ rychlรฉ zmฤ›ny bฤ›hovรฉho prostล™edรญ bฤ›hem incidentลฏ nebo nรกkladovรฝch udรกlostรญ.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n- Aktivace kombinace pล™epรญnaฤลฏ pล™รญmo z ล™รญdicรญho panelu MCP\n- Pouลพijte profily odolnosti z pล™eddefinovanรฝch balรญฤkลฏ zรกsad\n- Resetujte stav jistiฤe ze stejnรฉho ovlรกdacรญho panelu\n\n\n๐Ÿ”„ 23. โ€žPotล™ebuji ลพivou viditelnost a zruลกenรญ ลพivotnรญho cyklu รบkolu A2Aโ€œ\n\nBez viditelnosti ลพivotnรญho cyklu je obtรญลพnรฉ tล™รญdit incidenty รบkolลฏ.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n- Seznam รบkolลฏ / filtrovรกnรญ podle stavu / dovednostรญ se strรกnkovรกnรญm\n- Podrobnฤ›jลกรญ informace o metadatech รบkolลฏ, udรกlostech a artefaktech\n- Koncovรฝ bod zruลกenรญ รบlohy a akce uลพivatelskรฉho rozhranรญ s potvrzenรญm\n\n\n๐ŸŒŠ 24. โ€žPotล™ebuji aktivnรญ metriky streamu pro zatรญลพenรญ A2Aโ€œ\n\nStreamovacรญ pracovnรญ postupy vyลพadujรญ provoznรญ pล™ehled o soubฤ›ลพnรฝch a ลพivรฝch pล™ipojenรญch.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n- Aktivnรญ ฤรญtaฤe toku integrovanรฉ do stavu A2A\n- ฤŒasovรฉ razรญtko poslednรญho รบkolu a poฤty za stav\n- Karty palubnรญ desky A2A pro monitorovรกnรญ operacรญ v reรกlnรฉm ฤase\n\n\n๐Ÿชช 25. โ€žPotล™ebuji pro klienty zjiลกลฅovรกnรญ standardnรญch agentลฏโ€œ\n\nExternรญ klienti a orchestrรกtoล™i potล™ebujรญ strojovฤ› ฤitelnรก metadata pro integraci.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n- Karta agenta vystavena na adrese `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazenรฉ v uลพivatelskรฉm rozhranรญ pro sprรกvu\n- A2A status API obsahuje metadata zjiลกลฅovรกnรญ pro automatizaci\n\n\n๐Ÿงญ 26. โ€žPotล™ebuji zjistitelnost protokolu v uลพivatelskรฉm rozhranรญ produktuโ€œ\n\nPokud uลพivatelรฉ nemohou objevit protokolovรฉ povrchy, kvalita pล™ijetรญ a podpory klesรก.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\nโ€“ Konsolidovanรก strรกnka**Koncovรฉ body**s kartami pro koncovรฉ body proxy, MCP, A2A a API\n- Pล™epรญnรกnรญ stavu inline sluลพby (Online/Offline) pro MCP a A2A\n- Odkazy z pล™ehledu na vyhrazenรฉ karty sprรกvy\n\n\n๐Ÿงช 27. โ€žPotล™ebuji komplexnรญ ovฤ›ล™enรญ protokolu se skuteฤnรฝmi klientyโ€œ\n\nFaleลกnรฉ testy nestaฤรญ k ovฤ›ล™enรญ kompatibility protokolu pล™ed vydรกnรญm.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n- Sada E2E, kterรก spouลกtรญ aplikaci a pouลพรญvรก skuteฤnรฝ pล™enos klienta MCP SDK\n- Klient A2A testuje toky zjiลกลฅovรกnรญ, odesรญlรกnรญ, streamovรกnรญ, zรญskรกvรกnรญ a ruลกenรญ\n- Kล™รญลพovรก kontrola tvrzenรญ proti auditu MCP a API รบloh A2A\n\n\n๐Ÿ“ก 28. โ€žPotล™ebuji jednotnou pozorovatelnost napล™รญฤ vลกemi rozhranรญmiโ€œ\n\nRozdฤ›lenรญ pozorovatelnosti protokolem vytvรกล™รญ slepรก mรญsta a delลกรญ MTTR.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n- Sjednocenรฉ dashboardy/logy/analรฝzy v jednom produktu\n- Zdravรญ + audit + telemetrie poลพadavkลฏ napล™รญฤ vrstvami OpenAI, MCP a A2A\n- Provoznรญ API pro stav a automatizaci\n\n\n๐Ÿ’ผ 29. \"Potล™ebuji jeden runtime pro proxy + nรกstroje + orchestraci agenta\"\n\nProvozovรกnรญ mnoha samostatnรฝch sluลพeb zvyลกuje provoznรญ nรกklady a zpลฏsoby selhรกnรญ.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n- Proxy, MCP server a A2A server v jednom zรกsobnรญku kompatibilnรญ s OpenAI\n- Sdรญlenรก autentizace, odolnost, รบloลพiลกtฤ› dat a pozorovatelnost\n- Konzistentnรญ model politiky na vลกech interakฤnรญch plochรกch\n\n\n๐Ÿš€ 30. โ€žPotล™ebuji odeslat agentskรฉ pracovnรญ postupy bez rozลกiล™ovรกnรญ kรณdu lepidlaโ€œ\n\nTรฝmy ztrรกcejรญ rychlost pล™i spojovรกnรญ vรญce ad-hoc sluลพeb a skriptลฏ.\n\n**Jak to ล™eลกรญ OmniRoute:**\n\n- Jednotnรก strategie koncovรฝch bodลฏ pro klienty a agenty\n- Vestavฤ›nรก uลพivatelskรก rozhranรญ pro sprรกvu protokolลฏ a cesty ovฤ›ล™ovรกnรญ kouล™e\n- Zรกklady pล™ipravenรฉ na vรฝrobu (zabezpeฤenรญ, protokolovรกnรญ, odolnost, zรกlohovรกnรญ)\n\n### Example Playbooks (Integrated Use Cases)\n\n**Pล™รญruฤka A: Maximalizujte placenรฉ pล™edplatnรฉ + levnรฉ zรกlohovรกnรญ**```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n````\n\n**Pล™รญruฤka B: Sada kรณdovรกnรญ s nulovรฝmi nรกklady**```txt\nCombo: \"free-forever\"\n\n1. gc/gemini-3-flash\n2. if/kimi-k2-thinking\n3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n\n````\n\n**Pล™รญruฤka C: 24/7 vลพdy zapnutรฝ zรกloลพnรญ ล™etฤ›zec**```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n````\n\n**Pล™รญruฤka D: Operace agenta s MCP + A2A**```txt\n\n1. Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2. Run A2A tasks via `message/send` and `message/stream`\n3. Observe via /dashboard/endpoint (MCP and A2A tabs)\n4. Toggle services via inline status controls\n\n````\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Nastavenรญ kรณdovรกnรญ AI bฤ›hem nฤ›kolika minut za**$0/mฤ›sรญc**. Propojte tyto bezplatnรฉ รบฤty a pouลพijte vestavฤ›nou kombinaci**Free Stack**.\n\n| Krok | Akce | Poskytovatelรฉ odemฤeni |\n| ---- | --------------------------------------------------- | ------------------------------------------------------------------- |\n| 1 | Connect**Kiro**(AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€”**neomezeno**|\n| 2 | Pล™ipojte**Qoder**(Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€”**bez omezenรญ**|\n| 3 | Pล™ipojte**Qwen**(kรณd zaล™รญzenรญ) | qwen3-coder-plus, qwen3-coder-flash... โ€”**bez omezenรญ**|\n| 4 | Pล™ipojte**Gemini CLI**(Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€”**180 000/mฤ›sรญc zdarma**|\n| 5 | `/dashboard/combos` โ†’ ล ablona**Free Stack (0 $)**| Round-robin vลกechny bezplatnรฉ poskytovatele automaticky |\n\n**Nasmฤ›rujte libovolnรฉ IDE/CLI na:**`http://localhost:20128/v1` ยท Klรญฤ API: `any-string` ยท Hotovo.\n\n>**Volitelnรฉ dodateฤnรฉ pokrytรญ (takรฉ zdarma):**Klรญฤ Groq API (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelลฏ), Cerebras (1 M token/den), LongCat API klรญฤ (50 M tokenลฏ/den!), Cloudflare Workers AI (10 000 neuronลฏ/den, 50+ modelลฏ).## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n````\n\n> **Uลพivatelรฉ pnpm:**Po instalaci spusลฅte pล™รญkaz `pnpm accept-builds -g`, abyste povolili nativnรญ skripty sestavenรญ vyลพadovanรฉ `better-sqlite3` a `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm schvรกlit-builds -g # Vybrat vลกechny balรญฤky โ†’ schvรกlit\n> omniroute\n> ```\n\nDashboard se otevล™e na adrese `http://localhost:20128` a zรกkladnรญ adresa URL API je `http://localhost:20128/v1`.\n\n| Pล™รญkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------ |\n| \"vลกestrannรก cesta\" | Spustit server (`PORT=20128`, API a ล™รญdicรญ panel na stejnรฉm portu) |\n| `omniroute --port 3000` | Nastavte kanonickรฝ/API port na 3000 |\n| `omniroute --mcp` | Spustit MCP server (stdio transport) |\n| `omniroute --no-open` | Neotevรญrat automaticky prohlรญลพeฤ |\n| `omniroute --help` | Zobrazit nรกpovฤ›du |\n\nVolitelnรฝ reลพim rozdฤ›lenรฉho portu:```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n\n# API: http://localhost:20128/v1\n\n# Dashboard: http://localhost:20129\n\n````\n\n### Long-Running Streaming Timeouts\n\nPro vฤ›tลกinu nasazenรญ potล™ebujete pouze:\n\n| Promฤ›nnรก | Vรฝchozรญ | รšฤel |\n| ------------------------- | ------------------------------ | ------------------------------------------------------------- -------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | \"600 000\" | Sdรญlenรก zรกkladnรญ linie pro upstream naฤรญtรกnรญ, skrytรฉ ฤasovรฉ limity Undici, poลพadavky otiskลฏ prstลฏ TLS a ฤasovรฉ limity poลพadavkลฏ/proxy mostu API |\n| `STREAM_IDLE_TIMEOUT_MS` | zdฤ›dรญ `REQUEST_TIMEOUT_MS` | Maximรกlnรญ mezera mezi streamovanรฝmi bloky, neลพ OmniRoute pล™eruลกรญ stream SSE |\n\nZpฤ›tnรก kompatibilita je zachovรกna: stรกvajรญcรญ `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS` a dalลกรญ promฤ›nnรก ฤasovรฉho limitu pro jednotlivรฉ vrstvy stรกle fungujรญ a pล™episujรญ sdรญlenou zรกkladnรญ linii.\n\nPokud potล™ebujete jemnฤ›jลกรญ ovlรกdรกnรญ, jsou k dispozici pokroฤilรฉ pล™episy:| Promฤ›nnรก | Vรฝchozรญ | รšฤel |\n| ----------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | zdฤ›dรญ `REQUEST_TIMEOUT_MS` | Celkovรฝ ฤasovรฝ limit upstream poลพadavku pouลพitรฝ signรกlem pล™eruลกenรญ hlavnรญho naฤรญtรกnรญ |\n| `FETCH_HEADERS_TIMEOUT_MS` | zdฤ›dรญ `FETCH_TIMEOUT_MS` | Undici ฤasovรฝ limit pro pล™รญjem upstream hlaviฤek odpovฤ›dรญ |\n| `FETCH_BODY_TIMEOUT_MS` | zdฤ›dรญ `FETCH_TIMEOUT_MS` | Undici ฤasovรฝ limit mezi upstream body tฤ›la (`0` to zakรกลพe) |\n| `FETCH_CONNECT_TIMEOUT_MS` | \"30 000\" | Vyprลกel ฤasovรฝ limit pล™ipojenรญ Undici TCP |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | \"4000\" | Undici neฤinnรฝ keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | zdฤ›dรญ `FETCH_TIMEOUT_MS` | Vyprลกel ฤasovรฝ limit pro poลพadavky otisku TLS provedenรฉ prostล™ednictvรญm `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | zdฤ›dรญ `REQUEST_TIMEOUT_MS` nebo `30000` | ฤŒasovรฝ limit pro pล™esmฤ›rovรกnรญ proxy `/v1` z portu API na port ล™รญdicรญho panelu |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | ฤŒasovรฝ limit pล™รญchozรญho poลพadavku na serveru API mostu |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | \"60 000\" | ฤŒasovรฝ limit pล™รญchozรญ hlaviฤky na serveru API mostu |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | \"5000\" | Udrลพovacรญ ฤasovรฝ limit na serveru API mostu |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | \"0\" | ฤŒasovรฝ limit neฤinnosti soketu na serveru API mostu (`0` jej zakรกลพe) |\n\nPokud spouลกtรญte OmniRoute za Nginx, Caddy, Cloudflare nebo jinรฝm reverznรญm proxy, ujistฤ›te se, ลพe proxy\nฤasovรฉ limity jsou takรฉ vyลกลกรญ neลพ ฤasovรฉ limity streamu/naฤtenรญ OmniRoute.### 2) Connect providers and create your API key\n\n1. Otevล™ete Dashboard โ†’ `Providers` a pล™ipojte alespoลˆ jednoho poskytovatele (OAuth nebo API klรญฤ).\n2. Otevล™ete Dashboard โ†’ `Koncovรฉ body` a vytvoล™te klรญฤ API.\n3. (Volitelnรฉ) Otevล™ete Dashboard โ†’ `Komba` a nastavte svลฏj zรกloลพnรญ ล™etฤ›zec.### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n````\n\nPracuje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilnรญ s OpenAI.### 4) Enable and validate protocols (v2.0)\n\n**MCP (pro operace ล™รญzenรฉ nรกstrojem):**```bash\nomniroute --mcp\n\n````\n\nPotรฉ pล™ipojte svรฉho MCP klienta pล™es `stdio` a otestujte nรกstroje jako:\n\n- `omniroute_get_health`\n- `combos_omniroute_list_combos`\n\n**A2A (pro pracovnรญ postupy mezi agenty):**```bash\ncurl http://localhost:20128/.well-known/agent.json\n````\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ovฤ›ล™uje skuteฤnรฉ klientskรฉ toky MCP a A2A proti bฤ›ลพรญcรญ aplikaci.### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n\nVoid Linux (ลกablona `xbps-src`)\n\nPro uลพivatele Void Linuxu mลฏลพete vytvoล™it nativnรญ balรญฤek pomocรญ `xbps-src`. Uloลพte tento blok jako `srcpkgs/omniroute/template`:```bash\n\n# Template file for 'omniroute'\n\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"\\_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() { # Determine target CPU arch for node-gyp\nlocal \\_gyp_arch\ncase \"$XBPS_TARGET_MACHINE\" in\naarch64*) \\_gyp_arch=arm64 ;;\narmv7*|armv6*) \\_gyp_arch=arm ;;\ni686*) \\_gyp_arch=ia32 ;;\n\\*) \\_gyp_arch=x64 ;;\nesac\n\n # 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n # compiled separately below; better-sqlite3 is serverExternalPackage so\n # Next.js does not execute it during next build)\n NODE_ENV=development npm ci --ignore-scripts\n\n # 2) Build the Next.js standalone bundle\n npm run build\n\n # 3) Copy static assets into standalone\n cp -r .next/static .next/standalone/.next/static\n [ -d public ] && cp -r public .next/standalone/public || true\n\n # 4) Compile better-sqlite3 native binding for the target architecture.\n # Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n # without npm altering them.\n local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n (cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n # 5) Place the compiled binding into the standalone bundle\n local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n mkdir -p \"$_bs3_release\"\n cp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n # 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n # so sharp is not used at runtime; x64 .so files would break aarch64 strip\n rm -rf .next/standalone/node_modules/@img\n\n # 7) Copy pino runtime deps omitted by Next.js static analysis:\n # pino-abstract-transport โ€“ required by pino's worker thread\n # split2 โ€“ dep of pino-abstract-transport\n # process-warning โ€“ dep of pino itself\n for _mod in pino-abstract-transport split2 process-warning; do\n \tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n done\n\n}\n\ndo_check() {\nnpm run test:unit\n}\n\ndo_install() {\nvmkdir usr/lib/omniroute/.next\n\n vcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n # Prevent removal of empty Next.js app router dirs by the post-install hook\n for _d in \\\n \t.next/standalone/.next/server/app/dashboard \\\n \t.next/standalone/.next/server/app/dashboard/settings \\\n \t.next/standalone/.next/server/app/dashboard/providers; do\n \ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n done\n\n cat > \"${WRKDIR}/omniroute\" <<'EOF'\n\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport LOG_TO_FILE=\"${LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\nvlicense LICENSE\n}\n\n````\n\n\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute je k dispozici jako veล™ejnรฝ obrรกzek Dockeru na [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Rychlรฝ bฤ›h:**```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n````\n\n**Se souborem prostล™edรญ:**```bash\n\n# Copy and edit .env first\n\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n\n````\n\n**Pouลพitรญ Docker Compose:**```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n````\n\nPodpora ล™รญdicรญho panelu pro nasazenรญ Dockeru nynรญ zahrnuje**Cloudflare Quick Tunnel**na jedno kliknutรญ na `Dashboard โ†’ Endpoints`. Prvnรญ povolรญ stahovรกnรญ `cloudflared` pouze v pล™รญpadฤ› potล™eby, spustรญ doฤasnรฝ tunel k vaลกemu aktuรกlnรญmu koncovรฉmu bodu `/v1` a zobrazรญ vygenerovanou URL `https://*.trycloudflare.com/v1` pล™รญmo pod vaลกรญ normรกlnรญ veล™ejnou adresou URL.\n\nPoznรกmky:\n\n- URL Quick Tunnel jsou doฤasnรฉ a mฤ›nรญ se po kaลพdรฉm restartu.\n- Rychlรฉ tunely se po restartu OmniRoute nebo kontejneru automaticky neobnovรญ. V pล™รญpadฤ› potล™eby je znovu povolte z ล™รญdicรญho panelu.\n- Spravovanรก instalace aktuรกlnฤ› podporuje Linux, macOS a Windows na `x64` / `arm64`.\n- Spravovanรฉ rychlรฉ tunely jsou vรฝchozรญ pro pล™enos HTTP/2, aby se zabrรกnilo hluฤnรฝm varovรกnรญm vyrovnรกvacรญ pamฤ›ti QUIC UDP v prostล™edรญ s omezenรฝmi kontejnery. Pokud chcete jinรฝ pล™enos, nastavte `CLOUDFLARED_PROTOCOL=quic` nebo `auto`.\n- Obrazy Dockeru svazujรญ koล™eny systรฉmovรฉ CA a pล™edรกvajรญ je spravovanรฉmu `cloudflared`, coลพ zabraลˆuje selhรกnรญ dลฏvฤ›ryhodnosti TLS pล™i zavรกdฤ›nรญ tunelu uvnitล™ kontejneru.\n- SQLite bฤ›ลพรญ v reลพimu WAL. `Docker stop` by mฤ›lo bรฝt povoleno dokonฤit, aby OmniRoute mohl zkontrolovat nejnovฤ›jลกรญ zmฤ›ny zpฤ›t do `storage.sqlite`.\n- V pล™iloลพenรฝch souborech Compose je jiลพ nastavena doba odkladu 40 s. Pokud spouลกtรญte obraz pล™รญmo, ponechte hodnotu `--stop-timeout 40` (nebo podobnou), aby ruฤnรญ zastavenรญ nepล™eruลกilo ฤiลกtฤ›nรญ pล™i vypnutรญ.\n- Nastavte `CLOUDFLARED_BIN=/absolutnรญ/cesta/k/cloudflared`, pokud chcete, aby OmniRoute mรญsto stahovรกnรญ pouลพรญval existujรญcรญ binรกrnรญ soubor.\n\n**Pouลพitรญ Docker Compose s Caddy (HTTPS Auto-TLS):**\n\nOmniRoute lze bezpeฤnฤ› zpล™รญstupnit pomocรญ automatickรฉho zล™izovรกnรญ SSL Caddy. Ujistฤ›te se, ลพe zรกznam DNS A vaลกรญ domรฉny ukazuje na IP adresu vaลกeho serveru.```yaml\nservices:\nomniroute:\nimage: diegosouzapw/omniroute:latest\ncontainer_name: omniroute\nrestart: unless-stopped\nvolumes: - omniroute-data:/app/data\nenvironment: - PORT=20128 - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\ncaddy:\nimage: caddy:latest\ncontainer_name: caddy\nrestart: unless-stopped\nports: - \"80:80\" - \"443:443\"\ncommand: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\nomniroute-data:\n\n````\n\n| Obrรกzek | ล tรญtek | Velikost | Popis |\n| ------------------------- | -------- | ------ | ---------------------- |\n| `diegosouzapw/omniroute` | \"nejnovฤ›jลกรญ\" | ~250 MB | Poslednรญ stabilnรญ verze |\n| `diegosouzapw/omniroute` | \"1.0.3\" | ~250 MB | Aktuรกlnรญ verze |---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†•**NOVINKA!**OmniRoute je nynรญ k dispozici jako**nativnรญ desktopovรก aplikace**pro Windows, macOS a Linux.\n\nSpusลฅte OmniRoute jako samostatnou desktopovou aplikaci โ€“ pro mรญstnรญ modely nenรญ potล™eba ลพรกdnรฝ terminรกl, ลพรกdnรฝ prohlรญลพeฤ ani internet. Aplikace zaloลพenรก na Electronu zahrnuje:\n\n- ๐Ÿ–ฅ๏ธ**Nativnรญ okno**โ€” Vyhrazenรฉ okno aplikace s integracรญ na systรฉmovรฉ liลกtฤ›\n- ๐Ÿ”„**Auto-Start**โ€“ Spusลฅte OmniRoute pล™i pล™ihlรกลกenรญ do systรฉmu\n- ๐Ÿ””**Nativnรญ oznรกmenรญ**โ€“ Zรญskejte upozornฤ›nรญ na vyฤerpรกnรญ kvรณty nebo problรฉmy s poskytovatelem\n- โšก**Instalace jednรญm kliknutรญm**โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ**Reลพim offline**โ€“ Funguje plnฤ› offline s pล™ibalenรฝm serverem### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n````\n\n### System Tray\n\nKdyลพ je minimalizovรกn, OmniRoute ลพije v systรฉmovรฉ liลกtฤ› s rychlรฝmi akcemi:\n\n- Otevล™ete palubnรญ desku\n- Zmฤ›ลˆte port serveru\n- Ukonฤete aplikaci\n\n๐Ÿ“– รšplnรก dokumentace: [`electron/README.md`](electron/README.md)---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| รšroveลˆ | Poskytovatel | Cena | Obnovenรญ kvรณty | Nejlepลกรญ pro |\n| ----------------- | --------------------------- | ------------------------------- | --------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **๐Ÿ’ณ Pล˜EDPLATNร‰** | Claude Code (Pro) | 20 $/mฤ›sรญc | 5h + tรฝdnฤ› | Jiลพ pล™ihlรกลกeno |\n| | Codex (Plus/Pro) | 20โ€“200 USD/mฤ›sรญc | 5h + tรฝdnฤ› | Uลพivatelรฉ OpenAI |\n| | Gemini CLI | **ZDARMA** | 180 tis./mฤ›sรญc + 1 tis./den | Kaลพdรฝ! |\n| | GitHub Copilot | 10โ€“19 USD/mฤ›sรญc | Mฤ›sรญฤnฤ› | Uลพivatelรฉ GitHubu |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **ZDARMA**(dev forever) | ~40 RPM | 70+ otevล™enรฝch modelลฏ |\n| | Cerebras | **ZDARMA**(1 milion toku/den) | 60 000 TPM / 30 RPM | Nejrychlejลกรญ na svฤ›tฤ› |\n| | Groq | **ZDARMA**(30 RPM) | 14,4K RPD | Ultra rychlรก lama/gemma |\n| | DeepSeek V3.2 | 0,27 $ / 1,10 $ za 1 milion | ลฝรกdnรฉ | Nejlepลกรญ zdลฏvodnฤ›nรญ cena/kvalita |\n| | xAI Grok-4 Fast | **0,20 $/0,50 $ za 1M**๐Ÿ†• | ลฝรกdnรฉ | Nejrychlejลกรญ + volรกnรญ nรกstroje, ultranรญzkรฉ |\n| | xAI Grok-4 (standardnรญ) | 0,20 $/1,50 $ za 1M ๐Ÿ†• | ลฝรกdnรฉ | Reasoning vlajkovรก loฤ od xAI |\n| | Mistral | Vyzkouลกenรญ zdarma + placenรฉ | Omezenรก sazba | Evropskรก umฤ›lรก inteligence |\n| | OpenRouter | Platba za pouลพitรญ | ลฝรกdnรฉ | 100+ modelลฏ agr. |\n| **๐Ÿ’ฐ LEVNฤš** | GLM-5 (pล™es Z.AI) ๐Ÿ†• | 0,5 $/1 mil. | Dennฤ› 10:00 | 128K vรฝstup, nejnovฤ›jลกรญ vlajkovรก loฤ |\n| | GLM-4.7 | 0,6 $/1 mil. | Dennฤ› 10:00 | Zรกloha rozpoฤtu |\n| | MiniMax M2,5 ๐Ÿ†• | Vstup 0,3 $/1 milion | 5hodinovรฉ vรกlcovรกnรญ | รšvahy + agentskรฉ รบkoly |\n| | MiniMax M2.1 | 0,2 $/1 milion | 5hodinovรฉ vรกlcovรกnรญ | Nejlevnฤ›jลกรญ varianta |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Platba za pouลพitรญ | ลฝรกdnรฉ | Pล™รญmรฝ pล™รญstup Moonshot API |\n| | Kimi K2 | 9 $/mฤ›sรญc byt | 10 milionลฏ tokenลฏ/mฤ›sรญc | Pล™edvรญdatelnรฉ nรกklady |\n| **๐Ÿ†“ ZDARMA** | Qoder | **$0** | Neomezenรฉ | 5 modelลฏ neomezenฤ› |\n| | Qwen | **$0** | Neomezenรฉ | 4 modely neomezenฤ› |\n| | Kiro | **$0** | Neomezenรฉ | Claude Sonnet/Haiku (stavitel AWS) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0**(50 milionลฏ toku/den ๐Ÿ”ฅ) | 1 RPS | Nejvฤ›tลกรญ bezplatnรก kvรณta na Zemi |\n| | Opylovรกnรญ AI ๐Ÿ†• | **$0**(nenรญ potล™eba ลพรกdnรฝ klรญฤ) | 1 poลพadavek/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0**(10 000 neuronลฏ/den) | ~150 resp./den | 50+ modelลฏ, globรกlnรญ nรกskok |\n| | Scaleway AI ๐Ÿ†• | **$0**(celkem 1 milion tokenลฏ) | Omezenรก sazba | EU/GDPR, Qwen3 235B, Lama 70B | > ๐Ÿ†•**Pล™idanรฉ novรฉ modely (bล™ezen 2026):**Rodina Grok-4 Fast za 0,20 $/0,50 $/M (porovnรกvacรญ rychlost 1143 ms โ€“ o 30 % rychlejลกรญ neลพ Gemini 2.5 Flash), GLM-5 pล™es Z.AI s vรฝstupem 128K, aktualizovanรก cena MiniMax M2.5 V5, pล™รญmรฉ zdลฏvodnฤ›nรญ Kimi K2.2 Moon. |\n\n**๐Ÿ’ก Combo Stack 0 $ โ€” Kompletnรญ bezplatnรฉ nastavenรญ:**```\n\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\n\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n\n````\n\n**Nulovรฉ nรกklady. Nikdy nepล™estane kรณdovat.**Nakonfigurujte si to jako jednu kombinaci OmniRoute a vลกechna nouzovรก ล™eลกenรญ se stanou automaticky โ€“ ลพรกdnรฉ ruฤnรญ pล™epรญnรกnรญ.---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> Vลกechny nรญลพe uvedenรฉ modely jsou**100% zdarma bez nutnosti pouลพitรญ kreditnรญ karty**. OmniRoute mezi nimi automaticky smฤ›ruje, kdyลพ dojde jedna kvรณta โ€“ zkombinujte je vลกechny a zรญskรกte nerozbitnou kombinaci 0 $.### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Pล™edpona | Limit | Limit sazby |\n| -------------------- | ------ | ------------- | ---------------------- |\n| `claude-sonnet-4.5` | `kr/` |**Neomezeno**| ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-haiku-4,5` | `kr/` |**Neomezeno**| ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-opus-4.6` | `kr/` |**Neomezeno**| Nejnovฤ›jลกรญ Opus pล™es Kiro |### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Pล™edpona | Limit | Limit sazby |\n| ------------------- | ------ | ------------- | ---------------- |\n| \"kimi-k2-myลกlenรญ\" | `jestli/` |**Neomezeno**| ลฝรกdnรฝ nahlรกลกenรฝ strop |\n| `qwen3-coder-plus` | `jestli/` |**Neomezeno**| ลฝรกdnรฝ nahlรกลกenรฝ strop |\n| `deepseek-r1` | `jestli/` |**Neomezeno**| ลฝรกdnรฝ nahlรกลกenรฝ strop |\n| `minimax-m2.1` | `jestli/` |**Neomezeno**| ลฝรกdnรฝ nahlรกลกenรฝ strop |\n| \"kimi-k2\" | `jestli/` |**Neomezeno**| ลฝรกdnรฝ nahlรกลกenรฝ strop |\n\n> Doporuฤenรฝ zpลฏsob pล™ipojenรญ:**Personal Access Token + `qodercli`**. OAuth prohlรญลพeฤe je\n> experimentรกlnรญ a ve vรฝchozรญm nastavenรญ zakรกzรกno, pokud nejsou nakonfigurovรกny promฤ›nnรฉ prostล™edรญ `QODER_OAUTH_*`.### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Pล™edpona | Limit | Limit sazby |\n| -------------------- | ------ | ------------- | -------------------- |\n| `qwen3-coder-plus` | `qw/` |**Neomezeno**| ลฝรกdnรฝ nahlรกลกenรฝ strop |\n| `qwen3-coder-flash` | `qw/` |**Neomezeno**| ลฝรกdnรฝ nahlรกลกenรฝ strop |\n| `qwen3-coder-next` | `qw/` |**Neomezeno**| ลฝรกdnรฝ nahlรกลกenรฝ strop |\n| \"model vidฤ›nรญ\" | `qw/` |**Neomezeno**| Multimodรกlnรญ (obrรกzky) |### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Pล™edpona | Limit | Limit sazby |\n| ------------------------- | ------ | ---------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` |**180 tis./mฤ›sรญc**+ 1 tis./den | Mฤ›sรญฤnรญ reset |\n| `gemini-2.5-pro` | `gc/` | 180 tis./mฤ›sรญc (sdรญlenรฝ bazรฉn) | Vysokรก kvalita |### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| รšroveลˆ | Dennรญ limit | Limit sazby | Poznรกmky |\n| ---------- | ------------ | ----------- | ------------------------------------------------------- |\n| Zdarma (Dev) | ลฝรกdnรฝ token cap |**~40 RPM**| 70+ modelลฏ; pล™echod na limity ฤistรฉ sazby v polovinฤ› roku 2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| รšroveลˆ | Dennรญ limit | Limit sazby | Poznรกmky |\n| ---- | ------------------ | ----------------- | -------------------------------------------- |\n| Zdarma |**1 mil. tokenลฏ/den**| 60 000 TPM / 30 RPM | Svฤ›tovฤ› nejrychlejลกรญ odvozenรญ LLM; resetuje dennฤ› |\n\nDostupnรฉ zdarma: `lama-3.3-70b`, `lama-3.1-8b`, `deepseek-r1-distill-lama-70b`### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| รšroveลˆ | Dennรญ limit | Limit sazby | Poznรกmky |\n| ---- | ------------- | ----------------- | ------------------------------------------ |\n| Zdarma |**14,4K RPD**| 30 ot./min na model | ลฝรกdnรก kreditnรญ karta; 429 na limit, neรบฤtuje se |\n\nDostupnรฉ zdarma: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Pล™edpona | Dennรญ kvรณta zdarma | Poznรกmky |\n| ------------------------------ | ------ | ------------------ | ------------------------ |\n| \"LongCat-Flash-Lite\" | `lc/` |**50 milionลฏ tokenลฏ**๐Ÿ’ฅ | Nejvฤ›tลกรญ bezplatnรก kvรณta vลกech dob |\n| \"LongCat-Flash-Chat\" | `lc/` | 500 000 tokenลฏ | Vรญceotรกฤkovรฝ chat |\n| \"LongCat-Flash-Thinking\" | `lc/` | 500 000 tokenลฏ | Zdลฏvodnฤ›nรญ / CoT |\n| \"LongCat-Flash-Thinking-2601\" | `lc/` | 500 000 tokenลฏ | Verze z ledna 2026 |\n| \"LongCat-Flash-Omni-2603\" | `lc/` | 500 000 tokenลฏ | Multimodรกlnรญ |\n\n> 100 % zdarma ve veล™ejnรฉ beta verzi. Zaregistrujte se na [longcat.chat](https://longcat.chat) pomocรญ e-mailu nebo telefonu. Resetuje se dennฤ› v 00:00 UTC.### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Pล™edpona | Limit sazby | Poskytovatel za |\n| ---------- | ------ | ---------- | ------------------- |\n| \"openai\" | `pol/` | 1 poลพadavek/15s | GPT-5 |\n| \"claude\" | `pol/` | 1 poลพadavek/15s | Antropickรฝ Claude |\n| \"blรญลพenci\" | `pol/` | 1 poลพadavek/15s | Google Gemini |\n| \"hlubokรฉ vyhledรกvรกnรญ\" | `pol/` | 1 poลพadavek/15s | DeepSeek V3 |\n| \"lama\" | `pol/` | 1 poลพadavek/15s | Meta Llama 4 Scout |\n| \"mistrรกl\" | `pol/` | 1 poลพadavek/15s | Mistral AI |\n\n> โœจ**Nulovรฉ tล™enรญ:**ลฝรกdnรก registrace, ลพรกdnรฝ klรญฤ API. Pล™idejte poskytovatele Pollinations s prรกzdnรฝm polem klรญฤe a funguje to okamลพitฤ›.### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| รšroveลˆ | Dennรญ neurony | Ekvivalentnรญ pouลพitรญ | Poznรกmky |\n| ---- | ------------- | ---------------------------------------- | ------------------------ |\n| Zdarma |**10 000**| ~150 LLM resp / 500s audio / 15K vloลพenรญ | Global edge, 50+ modelลฏ |\n\nOblรญbenรฉ bezplatnรฉ modely: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (zvuk zdarma!), `@cf/qwen/qwen2.5-coder-`1\n\n> Vyลพaduje API Token + ID รบฤtu z [dash.cloudflare.com](https://dash.cloudflare.com). Uloลพte ID รบฤtu v nastavenรญ poskytovatele.### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| รšroveลˆ | Kvรณta zdarma | Umรญstฤ›nรญ | Poznรกmky |\n| ---- | ------------- | ------------ | ------------------------------------ |\n| Zdarma |**1 milion tokenลฏ**| ๐Ÿ‡ซ๐Ÿ‡ท Paล™รญลพ, EU | V rรกmci limitลฏ nenรญ potล™eba ลพรกdnรก kreditnรญ karta |\n\nDostupnรฉ zdarma: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> V souladu s EU/GDPR. Zรญskejte API klรญฤ na [console.scaleway.com](https://console.scaleway.com).\n\n>**๐Ÿ’ก The Ultimate Free Stack (11 poskytovatelลฏ, 0 $ navลพdy):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku NEOMEZENO\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€“ 50 milionลฏ tokenลฏ/den ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” nenรญ potล™eba ลพรกdnรฝ klรญฤ\n> Qwen (qw/) โ†’ modely qwen3-kodรฉr NEOMEZENร‰\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1 500 req/den zdarma\n> Cloudflare AI (cf/) โ†’ 50+ modelลฏ โ€” 10 000 neuronลฏ/den\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€“ 1M bezplatnรฝch tokenลฏ (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€“ ultrarychlรฉ 14,4 000 poลพadavkลฏ/den\n> NVIDIA NIM (nvidia/) โ†’ 70+ otevล™enรฝch modelลฏ โ€” 40 RPM navลพdy\n> Cerebras (cerebras/) โ†’ Nejrychlejลกรญ lama/Qwen na svฤ›tฤ› โ€“ 1 milion toku/den\n> ```## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Pล™epis jakรฉhokoli zvuku/videa za**$0**โ€” Deepgram vede s 200 $ zdarma, AssemblyAI 50 $ nouzovรฉ zรกlohy, Groq Whisper jako neomezenรฉ nouzovรฉ zรกlohovรกnรญ.\n\n| Poskytovatel | Kredity zdarma | Nejlepลกรญ modelka | Limit sazby |\n| ------------------ | ----------------------- | --------------------------------------------- | ----------------------------- |\n| ๐Ÿขข**Deepgram**|**200 $ zdarma**(registrace) | `nova-3` โ€” nejlepลกรญ pล™esnost, vรญce neลพ 30 jazykลฏ | ลฝรกdnรฝ limit RPM na bezplatnรฉ kredity |\n| ๐Ÿ”ต**SestavenรญAI**|**50 $ zdarma**(registrace) | `universal-3-pro` โ€” kapitoly, sentiment, PII | ลฝรกdnรฝ limit RPM na bezplatnรฉ kredity |\n| ๐Ÿ”ด**Groq**|**Navลพdy zdarma**| `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rychlost omezenรก) |\n\n**Doporuฤenรก kombinace v `/dashboard/combos`:**```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n````\n\nPotรฉ v `/dashboard/media` โ†’ karta**Pล™epis**: nahrajte jakรฝkoli zvukovรฝ nebo video soubor โ†’ vyberte svลฏj kombinovanรฝ koncovรฝ bod โ†’ zรญskejte pล™epis v podporovanรฝch formรกtech.## ๐Ÿ’ก Key Features\n\nOmniRoute v2.0 je postaven jako operaฤnรญ platforma, nikoli pouze jako pล™enosovรก proxy.### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Funkce | Co to dฤ›lรก |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |\n| โšก**Grok-4 Fast Family** | xAI modely za 0,20 $/0,50 $/M โ€“ srovnรกvacรญ 1143 ms (o 30 % rychlejลกรญ neลพ Gemini 2.5 Flash) |\n| ๐Ÿง **GLM-5 pล™es Z.AI** | 128 000 vรฝstupnรญ kontext, 0,5 $/1 milion โ€“ nejnovฤ›jลกรญ vlajkovรก loฤ z rodiny GLM |\n| ๐Ÿ”ฎ**MiniMax M2.5** | รšvahy + agentnรญ รบkoly za 0,30 $/1 milion โ€“ vรฝznamnรฝ upgrade z M2,1 |\n| ๐ŸŽฏ**toolCalling Flag na model** | โ€žToolCalling: true/falseโ€œ pro model v registru โ€“ AutoCombo pล™eskoฤรญ modely, kterรฉ nepodporujรญ nรกstroje |\n| ๐ŸŒ**Multilingual Intent Detection** | Klรญฤovรก slova PT/ZH/ES/AR v hodnocenรญ AutoCombo โ€“ lepลกรญ vรฝbฤ›r modelu pro neanglickรฝ obsah |\n| ๐Ÿ“Š**Zรกstupy zaloลพenรฉ na benchmarku** | Skuteฤnรก latence p95 z kombinovanรฉho bodovรกnรญ zdrojลฏ ลพivรฝch poลพadavkลฏ โ€“ AutoCombo se uฤรญ ze skuteฤnรฝch dat |\n| ๐Ÿ”**Poลพรกdat o deduplikaci** | Okno pro odstranฤ›nรญ duplicitnรญho obsahu zaloลพenรฉ na haลกovรกnรญ obsahu โ€“ bezpeฤnรฉ pro vรญce agentลฏ, zabraลˆuje duplicitnรญm poplatkลฏm |\n| ๐Ÿ”Œ**Strategie pล™ipojitelnรฉho smฤ›rovaฤe** | Rozลกiล™itelnรฉ rozhranรญ `RouterStrategy` โ€” pล™idejte vlastnรญ logiku smฤ›rovรกnรญ jako zรกsuvnรฉ moduly | ### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP |\n\n| Funkce | Co to dฤ›lรก |\n| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |\n| ๐ŸŽฎ**Modelovรฉ hล™iลกtฤ›** | Strรกnka ล™รญdicรญho panelu pro pล™รญmรฉ testovรกnรญ jakรฉhokoli modelu โ€” voliฤe poskytovatele/modelu/koncovรฉho bodu, editor Monaco, streamovรกnรญ, pล™eruลกenรญ, naฤasovรกnรญ |\n| ๐Ÿ”**CLI Fingerprint Matching** | Uspoล™รกdรกnรญ zรกhlavรญ/tฤ›la podle poskytovatele tak, aby odpovรญdalo nativnรญm signaturรกm CLI โ€“ pล™epnฤ›te podle poskytovatele v Nastavenรญ > Zabezpeฤenรญ.**Vaลกe IP adresa proxy je zachovรกna** |\n| ๐Ÿค**Podpora ACP (Protokol klienta agenta)** | Objevovรกnรญ agentลฏ CLI (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 dalลกรญch), proces spawner, koncovรฝ bod `/api/acp/agents` |\n| ๐Ÿค–**Hlavnรญ panel agentลฏ AKT** | Debug โ€บ Strรกnka Agenti โ€” mล™รญลพka 14 agentลฏ se stavem instalace, verzรญ, uลพivatelskรฝm formulรกล™em agenta pro libovolnรฝ nรกstroj CLI. Uลพivatelรฉ**OpenCode**zรญskajรญ tlaฤรญtko โ€žStรกhnout opencode.jsonโ€œ, kterรฉ automaticky vygeneruje konfiguraci pล™ipravenou k pouลพitรญ se vลกemi dostupnรฝmi modely. |\n| ๐Ÿ”ง**Smฤ›rovรกnรญ vlastnรญho modelu `apiFormat`** | Vlastnรญ modely s `apiFormat: \"responses\"` nynรญ sprรกvnฤ› smฤ›rujรญ do pล™ekladaฤe Responses API |\n| ๐Ÿข**Codex Workspace Isolation** | Vรญce pracovnรญch prostorลฏ Codex na e-mail โ€” OAuth sprรกvnฤ› oddฤ›luje pล™ipojenรญ podle ID pracovnรญho prostoru |\n| ๐Ÿ”„**Elektronovรก automatickรก aktualizace** | Desktopovรก aplikace kontroluje aktualizace + automatickรก instalace pล™i restartu | ### ๐Ÿค– Agent & Protocol Operations (v2.0) |\n\n| Funkce | Co to dฤ›lรก |\n| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |\n| ๐Ÿ”ง**MCP Server (25 nรกstrojลฏ)** | Nรกstroje IDE/agenta prostล™ednictvรญm 3 pล™enosลฏ: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 jader + 3 pamฤ›ti + 4 nรกstroje pro dovednosti |\n| ๐Ÿค**Server A2A (JSON-RPC + SSE)** | Provรกdฤ›nรญ รบlohy agent-agent se synchronizacรญ a streamovรกnรญm |\n| ๐Ÿงญ**Strรกnka konsolidovanรฝch koncovรฝch bodลฏ** | Strรกnka sprรกvy s kartami s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| ๐ŸŽš๏ธ**Pล™epรญnaฤe aktivace/deaktivace sluลพby** | Spรญnaฤe ON/OFF pro MCP a A2A s trvalรฝm nastavenรญm (vรฝchozรญ: OFF) |\n| ๐Ÿ›ฐ๏ธ**MCP Runtime Heartbeat** | Skuteฤnรฝ stav procesu (pid, doba provozu, doba srdeฤnรญho tepu, transport, reลพim rozsahu) |\n| ๐Ÿ“‹**MCP Audit Trail** | Filtrovatelnรฉ protokoly auditu s รบspฤ›chem/neรบspฤ›chem a pล™iล™azenรญm klรญฤe |\n| ๐Ÿ”**Vymรกhรกnรญ rozsahu MCP** | 10 podrobnรฝch oprรกvnฤ›nรญ k rozsahu pro ล™รญzenรฝ pล™รญstup k nรกstrojลฏm |\n| ๐Ÿ“ก**A2A Task Lifecycle Management** | Vypsat/filtrovat รบlohy, zkontrolovat udรกlosti/artefakty, zruลกit bฤ›ลพรญcรญ รบlohy |\n| ๐Ÿ“‹**Zjiลกtฤ›nรญ karty agenta** | `/.well-known/agent.json` pro automatickรฉ zjiลกลฅovรกnรญ klienta |\n| ๐Ÿงช**Protokol E2E Test Harness** | Skuteฤnรฝ MCP SDK + klient A2A toky v `test:protocols:e2e` |\n| โš™๏ธ**Provoznรญ ovlรกdacรญ prvky** | Kombinace pล™epรญnaฤลฏ, pouลพitรญ profilลฏ odolnosti, resetovรกnรญ jistiฤลฏ z jednรฉ ovlรกdacรญ plochy | ### ๐Ÿง  Routing & Intelligence |\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------- |\n| ๐ŸŽฏ**Chytrรฝ 4รบrovลˆovรฝ zรกloลพnรญ zdroj** | Automatickรก trasa: Pล™edplatnรฉ โ†’ Klรญฤ API โ†’ Levnรฉ โ†’ Zdarma |\n| ๐Ÿ“Š**Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** | ลฝivรฝ poฤet tokenลฏ + reset odpoฤรญtรกvรกnรญ na poskytovatele |\n| ๐Ÿ”„**Formรกtovรฝ pล™eklad** | OpenAI โ†” Claude โ†” Gemini โ†” Odpovฤ›di s pล™evody bezpeฤnรฝmi pro schรฉma |\n| ๐Ÿ‘ฅ**Podpora vรญce รบฤtลฏ** | Vรญce รบฤtลฏ na poskytovatele s inteligentnรญm vรฝbฤ›rem |\n| ๐Ÿ”„**Automatickรฉ obnovenรญ tokenu** | Tokeny OAuth se automaticky obnovujรญ s opakovรกnรญm |\n| ๐ŸŽจ**Vlastnรญ kombinace** | 9 vyvaลพovacรญch strategiรญ + ล™รญzenรญ zรกloลพnรญho ล™etฤ›zce |\n| ๐ŸŒ**Wildcard Router** | `poskytovatel/*` dynamickรฉ smฤ›rovรกnรญ |\n| ๐Ÿง **Pล™emรฝลกlenรญ o kontrolรกch rozpoฤtu** | Limity prลฏchozรญho, automatickรฉho, vlastnรญho a adaptivnรญho uvaลพovรกnรญ |\n| ๐Ÿ”€**Aliasy modelลฏ** | Vestavฤ›nรฝ + vlastnรญ model aliasing a bezpeฤnost migrace |\n| โšก**Degradace pozadรญ** | Smฤ›rujte รบlohy s nรญzkou prioritou na pozadรญ na levnฤ›jลกรญ modely |\n| ๐Ÿงช**Inteligentnรญ smฤ›rovรกnรญ s ohledem na รบkoly** | Automatickรฝ vรฝbฤ›r modelu podle typu obsahu (kรณdovรกnรญ/vize/analรฝza/souhrn) |\n| ๐Ÿ”„**Pracovnรญ postupy agentลฏ A2A** | Deterministickรฝ orchestrรกtor FSM pro stavovรฉ spouลกtฤ›nรญ agentลฏ ve vรญce krocรญch |\n| ๐Ÿ”€**Adaptivnรญ smฤ›rovรกnรญ** | Dynamickรฉ pล™episovรกnรญ strategie zaloลพenรฉ na objemu tokenลฏ a sloลพitosti vรฝzvy |\n| ๐ŸŽฒ**Rozmanitost poskytovatelลฏ** | Shannon entropie bodovรกnรญ vyvaลพovรกnรญ auto-kombo rozloลพenรญ provozu |\n| ๐Ÿ’ฌ**System Prompt Injection** | Globรกlnรญ ovlรกdacรญ prvky chovรกnรญ pouลพรญvanรฉ konzistentnฤ› |\n| ๐Ÿ“„**Kompatibilita rozhranรญ Responses API** | Plnรก podpora `/v1/responses` pro Codex a pokroฤilรฉ agentnรญ pracovnรญ postupy | ### ๐ŸŽต Multi-Modal APIs |\n\n| Funkce | Co to dฤ›lรก |\n| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |\n| ๐Ÿ–ผ๏ธ**Generovรกnรญ obrรกzkลฏ** | `/v1/images/generations` s cloudem a mรญstnรญmi backendy |\n| ๐Ÿ“**Vloลพenรญ** | `/v1/embeddings` pro vyhledรกvรกnรญ a potrubรญ RAG |\n| ๐ŸŽค**Pล™epis zvuku** | `/v1/audio/transscriptions` โ€” 7 poskytovatelลฏ (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), automatickรก detekce jazyka, podpora MP4/MP3/WAV |\n| ๐Ÿ”Š**Pล™evod textu na ล™eฤ** | `/v1/audio/speech` โ€” 10 poskytovatelลฏ (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) se sprรกvnรฝmi chybovรฝmi zprรกvami |\n| ๐ŸŽฌ**Generace videa** | `/v1/videos/generations` (pracovnรญ postupy ComfyUI + SD WebUI) |\n| ๐ŸŽต**Music Generation** | `/v1/music/generations` (pracovnรญ postupy ComfyUI) |\n| ๐Ÿ›ก๏ธ**Moderovรกnรญ** | `/v1/moderations` bezpeฤnostnรญ kontroly |\n| ๐Ÿ”€**Reranking** | `/v1/rerank` pro hodnocenรญ relevance |\n| ๐Ÿ”**Vyhledรกvรกnรญ na webu**๐Ÿ†• | `/v1/search` โ€” 5 poskytovatelลฏ (Serper, Brave, Perplexity, Exa, Tavily), 6 500+ zdarma/mฤ›sรญc, automatickรฉ pล™epnutรญ pล™i selhรกnรญ, mezipamฤ›ลฅ | ### ๐Ÿ›ก๏ธ Resilience, Security & Governance |\n\n| Funkce | Co to dฤ›lรก |\n| --------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------- |\n| ๐Ÿ”Œ**Jistiฤe** | Vypnutรญ/obnovenรญ pro kaลพdรฝ model s ovlรกdรกnรญm prahu |\n| ๐ŸŽฏ**Koncovรฉ modely** | Vlastnรญ modely deklarujรญ podporovanรฉ koncovรฉ body + formรกt API |\n| ๐Ÿ›ก๏ธ**Stรกdo proti hromลฏm** | Mutex + semaforovรฉ ochrany pล™i opakovรกnรญ/rychlosti udรกlostรญ |\n| ๐Ÿง **Sรฉmantickรก + mezipamฤ›ลฅ podpisลฏ** | Snรญลพenรญ nรกkladลฏ/latence se dvฤ›ma vrstvami mezipamฤ›ti |\n| โšก**ลฝรกdost o idempotenci** | Duplicitnรญ ochrannรฉ okno |\n| ๐Ÿ”’**TLS Fingerprint Spoofing** | Otisk TLS jako v prohlรญลพeฤi โ€”**sniลพuje detekci robotลฏ a nahlaลกovรกnรญ รบฤtu** |\n| ๐Ÿ”**CLI Fingerprint Matching** | Odpovรญdรก nativnรญm podpisลฏm poลพadavku CLI โ€”**sniลพuje riziko zรกkazu pล™i zachovรกnรญ proxy IP** |\n| ๐ŸŒ**Filtrovรกnรญ IP** | Kontrola seznamu povolenรฝch/blokovanรฝch pro vystavenรก nasazenรญ |\n| ๐Ÿ“Š**Upravitelnรฉ limity sazeb** | Konfigurovatelnรฉ globรกlnรญ limity/limity na รบrovni poskytovatele s perzistencรญ |\n| ๐Ÿ“‰**Pลฏvabnรก degradace** | Zรกloลพnรญ funkce vรญcevrstvรฉ ochrany chrรกnรญcรญ operace hlavnรญ brรกny |\n| ๐Ÿ“œ**Config Audit Trail** | Sledovรกnรญ zmฤ›n zaloลพenรฉ na rozdรญlech zabraลˆujรญcรญ provoznรญmu posunu s jednoduchรฝm vrรกcenรญm zpฤ›t |\n| โณ**Provider Health Sync** | Proaktivnรญ monitorovรกnรญ vyprลกenรญ platnosti tokenu spouลกtฤ›jรญcรญ vรฝstrahy pล™ed selhรกnรญm autorizace |\n| ๐Ÿšช**Automaticky zakรกzat zakรกzanรฉ รบฤty** | Provoznรญ jistiฤ automaticky zaplombuje trvale zablokovanรฉ tokenovรฉ รบฤty |\n| ๐Ÿ”‘**Sprรกva klรญฤลฏ API + rozsah** | Bezpeฤnรฉ vydรกvรกnรญ/otoฤenรญ klรญฤลฏ a ovlรกdรกnรญ modelu/poskytovatele |\n| ๐Ÿ‘๏ธ**Scoped API Key Reveal**๐Ÿ†• | Pล™ihlaste se k obnovฤ› klรญฤลฏ API prostล™ednictvรญm `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ**Chrรกnฤ›no `/modely`** | Volitelnรฉ ovฤ›ล™ovรกnรญ a skrytรญ poskytovatele pro katalog modelลฏ | ### ๐Ÿ“Š Observability & Analytics |\n\n| Funkce | Co to dฤ›lรก |\n| -------------------------------------- | ---------------------------------------------------------------------- | ---------------------------- |\n| ๐Ÿ“**Poลพadavek + protokolovรกnรญ proxy** | รšplnรฝ poลพadavek/odpovฤ›ฤ a protokolovรกnรญ proxy |\n| ๐Ÿ“‰**Streamovanรฉ podrobnรฉ protokoly**๐Ÿ†• | ฤŒistฤ› rekonstruuje datovรฉ proudy SSE do uลพivatelskรฉho rozhranรญ |\n| ๐Ÿ“‹**Sjednocenรฝ panel protokolลฏ** | Poลพadavek, proxy, audit a zobrazenรญ konzoly na jednรฉ strรกnce |\n| ๐Ÿ”**Poลพรกdejte o telemetrii** | p50/p95/p99 latence a sledovรกnรญ poลพadavkลฏ |\n| ๐Ÿฅ**Health Dashboard** | Doba provozuschopnosti, stavy jistiฤe, uzamฤenรญ, statistiky mezipamฤ›ti |\n| ๐Ÿ’ฐ**Sledovรกnรญ nรกkladลฏ** | Kontroly rozpoฤtu a viditelnost cen podle modelu |\n| ๐Ÿ“ˆ**Analytickรฉ vizualizace** | Statistiky vyuลพitรญ modelu/poskytovatele a zobrazenรญ trendลฏ |\n| ๐Ÿงช**Rรกmec hodnocenรญ** | Testovรกnรญ zlatรฉ sady s konfigurovatelnรฝmi strategiemi shody |\n| ๐Ÿ“ก**Live Diagnostics**๐Ÿ†• | Sรฉmantickรฉ vynechรกnรญ mezipamฤ›ti pro pล™esnรฉ kombinovanรฉ ลพivรฉ testovรกnรญ | ### โ˜๏ธ Deployment & Platform |\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------- | ---------------------------------------------------------------------------- | --------------------- |\n| ๐ŸŒ**Nasadit kdekoli** | Localhost, VPS, Docker, cloudovรก prostล™edรญ |\n| ๐Ÿš‡**Tunel Cloudflare**๐Ÿ†• | Integrace rychlรฉho tunelu jednรญm kliknutรญm z ล™รญdicรญho panelu |\n| ๐Ÿ”‘**Filtrovรกnรญ modelu klรญฤe API** | Nativnรญ odpovฤ›ฤ /v1/models filtrovanรก pล™es pล™iล™azenรฉ kontextovรฉ role nosiฤe |\n| โšก**Smart Cache Bypass** | Konfigurovatelnรก heuristika TTL a ovlรกdacรญ prvky nucenรฉho opฤ›tovnรฉho naฤtenรญ |\n| ๐Ÿ”„**Zรกlohovรกnรญ/Obnova** | Export/import a toky obnovy po havรกrii |\n| ๐Ÿง™**Prลฏvodce onboardingem** | Prvnรญ spuลกtฤ›nรญ prลฏvodce nastavenรญm |\n| ๐Ÿ”ง**CLI Tools Dashboard** | Nastavenรญ jednรญm kliknutรญm pro oblรญbenรฉ kรณdovacรญ nรกstroje |\n| ๐ŸŽฎ**Modelovรฉ hล™iลกtฤ›** | Otestujte libovolnรฉho poskytovatele/model/koncovรฝ bod z ล™รญdicรญho panelu |\n| ๐Ÿ”**CLI Fingerprint Toggle** | Shoda otiskลฏ prstลฏ jednotlivรฝch poskytovatelลฏ v Nastavenรญ > Zabezpeฤenรญ |\n| ๐ŸŒ**i18n (30 jazykลฏ)** | Plnรก podpora ล™รญdicรญho panelu + docs s pokrytรญm RTL |\n| ๐Ÿงน**Vymazat vลกechny modely** | Vymazรกnรญ seznamu modelลฏ jednรญm kliknutรญm v detailech poskytovatele |\n| ๐Ÿ‘๏ธ**Ovlรกdacรญ prvky postrannรญho panelu**๐Ÿ†• | Skrรฝt komponenty a integrace z Nastavenรญ vzhledu |\n| ๐Ÿ“‹**ล ablony vydรกnรญ** | Standardizovanรฉ ลกablony GitHub pro chyby a funkce |\n| ๐Ÿ“‚**Custom Data Directory** | Pล™epsรกnรญ `DATA_DIR` pro umรญstฤ›nรญ รบloลพiลกtฤ› | ### Feature Deep Dive |\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyลพ kvรณta, rychlost nebo stav selลพou, OmniRoute automaticky pล™ejde na dalลกรญho kandidรกta bez ruฤnรญho pล™epรญnรกnรญ.#### Protocol management that is visible and operable\n\n- MCP + A2A jsou zjistitelnรฉ v uลพivatelskรฉm rozhranรญ a dokumentech (nejsou skrytรฉ)\n- Rozhranรญ API stavu protokolu zpล™รญstupลˆujรญ ลพivรก provoznรญ data (`/api/mcp/*`, `/api/a2a/*`)\n- Panely obsahujรญ akce pro operace 2. dne (pล™epรญnรกnรญ kombinacรญ, resetovรกnรญ jistiฤe, zruลกenรญ รบkolu)#### Translator + validation workflow\n\nOblast pล™ekladatele zahrnuje:\n\n-**Hล™iลกtฤ›**: Vyลพรกdejte si kontroly transformace -**Chat Tester**: kompletnรญ zpรกteฤnรญ cesta na ลพรกdost/odpovฤ›ฤ -**Testovacรญ stolice**: vรญce pล™รญpadลฏ v jednom bฤ›hu -**Live Monitor**: zobrazenรญ dopravy v reรกlnรฉm ฤase\n\nPlus ovฤ›ล™enรญ protokolu se skuteฤnรฝmi klienty pomocรญ `npm run test:protocols:e2e`.\n\n> ๐Ÿ“–**[MCP Server README](open-sse/mcp-server/README.md)**โ€” Reference nรกstrojลฏ, konfigurace IDE a pล™รญklady klientลฏ\n>\n> ๐Ÿ“–**[A2A Server README](src/lib/a2a/README.md)**โ€” Dovednosti, metody JSON-RPC, streamovรกnรญ a ลพivotnรญ cyklus รบloh## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute obsahuje vestavฤ›nรฝ hodnotรญcรญ rรกmec pro testovรกnรญ kvality odezvy LLM oproti zlatรฉ sadฤ›. Pล™istupte k nฤ›mu pล™es**Analytics โ†’ Evals**na hlavnรญm panelu.### Built-in Golden Set\n\nPล™edinstalovanรก sada โ€žOmniRoute Golden Setโ€œ obsahuje testovacรญ pล™รญpady pro:\n\n- Pozdravy, matematika, zemฤ›pis, generovรกnรญ kรณdu\n- Kompatibilita formรกtu JSON, pล™eklad, generovรกnรญ markdown\n- Bezpeฤnostnรญ odmรญtnutรญ (ลกkodlivรฝ obsah), poฤรญtรกnรญ, booleovskรก logika### Evaluation Strategies\n\n| Strategie | Popis | Pล™รญklad |\n| ----------------- | ---------------------------------------------------------------------- | ------------------------------- | --- |\n| \"pล™esnรฝ\" | Vรฝstup se musรญ pล™esnฤ› shodovat | \"4\"\" |\n| \"obsahuje\" | Vรฝstup musรญ obsahovat podล™etฤ›zec (nerozliลกujรญ se malรก a velkรก pรญsmena) | \"Paล™รญลพ\" |\n| \"regulรกrnรญ vรฝraz\" | Vรฝstup musรญ odpovรญdat vzoru regulรกrnรญho vรฝrazu | `\"1.*2.*3\"` |\n| \"vlastnรญ\" | Vlastnรญ funkce JS vracรญ true/false | `(vรฝstup) => vรฝstup.dรฉlka > 10` | --- |\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n\n๐Ÿงฉ Nastavenรญ MCP (Model Context Protocol)\n\nSpusลฅte pล™enos MCP v reลพimu stdio:```bash\nomniroute --mcp\n\n````\n\nDoporuฤenรฝ postup ovฤ›ล™enรญ:\n\n1. Pล™ipojte svรฉho MCP klienta pล™es stdio.\n2. Spusลฅte `omniroute_get_health`.\n3. Spusลฅte `omniroute_list_combos`.\n4. Otevล™ete `/dashboard/mcp` pro potvrzenรญ prezenฤnรญho signรกlu, aktivity a auditu.\n\nUลพiteฤnรก rozhranรญ API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n\n๐Ÿค Nastavenรญ A2A (Agent2Agent)\n\nObjevte agenta:```bash\ncurl http://localhost:20128/.well-known/agent.json\n````\n\nOdeslat รบkol:```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n\n````\n\nSprรกva ลพivotnรญho cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvoznรญ uลพivatelskรฉ rozhranรญ:\n\n- `/dashboard/a2a` pro pozorovรกnรญ รบkolu/stavu/toku a akce kouล™e\n\n\n๐Ÿงช End-to-end validace protokolu\n\nOvฤ›ล™te oba protokoly se skuteฤnรฝmi klienty:```bash\nnpm run test:protocols:e2e\n````\n\nTรญm se ovฤ›ล™uje:\n\n- Pล™ipojenรญ/seznam/volรกnรญ klienta MCP SDK\n- A2A objev/odeslat/streamovat/zรญskat/zruลกit\n- Kล™รญลพovรก kontrola dat v MCP auditu a API pro sprรกvu รบloh A2A\n\n\n๐Ÿ’ณ Poskytovatelรฉ pล™edplatnรฉho### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionรกly:**Pouลพรญvejte Opus pro sloลพitรฉ รบkoly, Sonnet pro rychlost. OmniRoute sleduje kvรณtu na model!### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nKaลพdรฝ รบฤet Codexu mรก nynรญ pล™epรญnaฤe zรกsad v `Dashboard -> Providers`:\n\n- `5h` (ZAP/VYP): vynutit zรกsadu prahu 5hodinovรฉho okna.\n- `Tรฝdnฤ›` (ON/OFF): vynutit zรกsadu tรฝdennรญho prahu okna.\n- Prahovรฉ chovรกnรญ: kdyลพ povolenรฉ okno dosรกhne vyuลพitรญ >=90 %, danรฝ รบฤet je pล™eskoฤen.\n- Rotaฤnรญ chovรกnรญ: OmniRoute automaticky smฤ›ruje na dalลกรญ zpลฏsobilรฝ รบฤet Codex.\n- Resetovat chovรกnรญ: po uplynutรญ ฤasu `resetAt` poskytovatele se รบฤet automaticky znovu stane zpลฏsobilรฝm.\n\nScรฉnรกล™e:\n\n- `5h ON` + `Weekly ON`: รบฤet je pล™eskoฤen, kdyลพ kterรฉkoli okno dosรกhne prahovรฉ hodnoty.\n- `5h VYP` + `Tรฝdnฤ› ZAP`: รบฤet mลฏลพe zablokovat pouze pouลพรญvรกnรญ tรฝdnฤ›.\n- `5h ON` + `Tรฝdennรญ OFF`: รบฤet mลฏลพe zablokovat pouze 5 hodin pouลพรญvรกnรญ.\n- `resetAt` proลกlo: รบฤet automaticky znovu vstoupรญ do rotace (bez ruฤnรญho opฤ›tovnรฉho povolenรญ).### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepลกรญ hodnota:**Obrovskรก bezplatnรก รบroveลˆ! Pouลพijte to pล™ed placenรฝmi รบrovnฤ›mi.### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n\n\n\n๐Ÿ”‘ Poskytovatelรฉ klรญฤลฏ API### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Zaregistrujte se: [build.nvidia.com](https://build.nvidia.com)\n2. Zรญskejte bezplatnรฝ klรญฤ API (vฤetnฤ› 1000 kreditลฏ pro odvozenรญ)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ NVIDIA NIM:\n - Klรญฤ API: `nvapi-your-key`\n\n**Modely:**`nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` a 50+ dalลกรญch\n\n**Tip pro profesionรกly:**API kompatibilnรญ s OpenAI โ€“ bezproblรฉmovฤ› funguje s pล™ekladem formรกtu OmniRoute!### DeepSeek\n\n1. Zaregistrujte se: [platform.deepseek.com](https://platform.deepseek.com)\n2. Zรญskejte API klรญฤ\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ DeepSeek\n\n**Modely:**`deepseek/deepseek-chat`, `deepseek/deepseek-coder`### Groq (Free Tier Available!)\n\n1. Zaregistrujte se: [console.groq.com](https://console.groq.com)\n2. Zรญskejte klรญฤ API (vฤetnฤ› bezplatnรฉ รบrovnฤ›)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ Groq\n\n**Modely:**`groq/lama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Tip pro profesionรกly:**Ultra rychlรฉ vyvozovรกnรญ โ€“ nejlepลกรญ pro kรณdovรกnรญ v reรกlnรฉm ฤase!### OpenRouter (100+ Models)\n\n1. Zaregistrujte se: [openrouter.ai](https://openrouter.ai)\n2. Zรญskejte API klรญฤ\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ OpenRouter\n\n**Modely:**Zรญskejte pล™รญstup k vรญce neลพ 100 modelลฏm od vลกech hlavnรญch poskytovatelลฏ prostล™ednictvรญm jedinรฉho klรญฤe API.\n\n**Chovรกnรญ ล™รญdicรญho panelu:**Modely OpenRouter jsou spravovรกny z**Dostupnรฝch modelลฏ**. Ruฤnรญ pล™idรกnรญ, import a automatickรก synchronizace aktualizujรญ stejnรฝ seznam.\n\n\n๐Ÿ’ฐ Levnรญ poskytovatelรฉ (zรกloลพnรญ)### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Zaregistrujte se: [Zhipu AI](https://open.bigmodel.cn/)\n2. Zรญskejte API klรญฤ z Coding Plan\n3. Ovlรกdacรญ panel โ†’ Pล™idat klรญฤ API:\n - Poskytovatel: `glm`\n - Klรญฤ API: `vรกลก klรญฤ`\n\n**Pouลพitรญ:**`glm/glm-4.7`\n\n**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)\n\n1. Zaregistrujte se: [MiniMax](https://www.minimax.io/)\n2. Zรญskejte API klรญฤ\n3. Ovlรกdacรญ panel โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:**`minimax/MiniMax-M2.1`\n\n**Tip pro profesionรกly:**Nejlevnฤ›jลกรญ moลพnost pro dlouhรฝ kontext (1 milion tokenลฏ)!### Kimi K2 ($9/month flat)\n\n1. Pล™ihlaste se k odbฤ›ru: [Moonshot AI](https://platform.moonshot.ai/)\n2. Zรญskejte API klรญฤ\n3. Ovlรกdacรญ panel โ†’ Pล™idat klรญฤ API\n\n**Pouลพijte:**`kimi/kimi-latest`\n\n**Tip pro profesionรกly:**Pevnรก cena 9 $ mฤ›sรญฤnฤ› za 10 milionลฏ tokenลฏ = 0,90 $ / 1 milion efektivnรญch nรกkladลฏ!\n\n\n๐Ÿ†“ ZDARMA poskytovatelรฉ (nouzovรฉ zรกlohovรกnรญ)### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n\n\n\n๐ŸŽจ Vytvoล™it komba### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n\n\n\n๐Ÿ”ง Integrace CLI### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPouลพijte strรกnku**CLI Tools**na ล™รญdicรญm panelu pro konfiguraci jednรญm kliknutรญm nebo upravte `~/.claude/settings.json` ruฤnฤ›.### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Moลพnost 1 โ€“ Hlavnรญ panel (doporuฤeno):**```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n\n````\n\n**Moลพnost 2 โ€” Ruฤnฤ›:**Upravit `~/.openclaw/openclaw.json`:```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n````\n\n> **Poznรกmka:**OpenClaw funguje pouze s mรญstnรญ OmniRoute. Pouลพijte `127.0.0.1` mรญsto `localhost`, abyste se vyhnuli problรฉmลฏm s rozliลกenรญm IPv6.### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:**Pล™idejte OmniRoute jako vlastnรญho poskytovatele:```bash\nopencode\n/connect\n\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n\n````\n\n**Krok 2:**Vytvoล™te/upravte soubor `opencode.json` v koล™enovรฉm adresรกล™i projektu:```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n````\n\n**Krok 3:**Vyberte model v OpenCode:```bash\n/models\n\n# Select any OmniRoute model from the list\n\n````\n\n>**Tip:**Pล™idejte jakรฝkoli model dostupnรฝ v koncovรฉm bodu vaลกeho OmniRoute `/v1/models` do sekce `models`. Pouลพijte formรกt `provider/model-id` z ล™รญdicรญho panelu OmniRoute.\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n\nKliknutรญm rozbalรญte prลฏvodce odstraลˆovรกnรญm problรฉmลฏ\n\n**\"Jazykovรฝ model neposkytoval zprรกvy\"**\n\n- Kvรณta poskytovatele je vyฤerpรกna โ†’ Zkontrolujte sledovรกnรญ kvรณt na ล™รญdicรญm panelu\n- ล˜eลกenรญ: Pouลพijte nouzovou kombinaci nebo pล™ejdฤ›te na levnฤ›jลกรญ รบroveลˆ\n\n**Omezenรญ sazby**\n\n- Vyฤerpanรก kvรณta pล™edplatnรฉho โ†’ Zรกloลพnรญ reลพim GLM/MiniMax\n- Pล™idejte kombinaci: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vyprลกela**\n\n- Automaticky obnovovรกno OmniRoute\n- Pokud problรฉmy pล™etrvรกvajรญ: ล˜รญdicรญ panel โ†’ Poskytovatel โ†’ Znovu pล™ipojit\n\n**Vysokรฉ nรกklady**\n\n- Zkontrolujte statistiky vyuลพitรญ v Dashboard โ†’ Nรกklady\n- Pล™epnฤ›te primรกrnรญ model na GLM/MiniMax\n- Pouลพรญvejte bezplatnou vrstvu (Gemini CLI, Qoder) pro nekritickรฉ รบkoly\n\n**Porty ล™รญdicรญho panelu/API jsou chybnรฉ**\n\n- `PORT` je kanonickรฝ zรกkladnรญ port (a port API ve vรฝchozรญm nastavenรญ)\n- `API_PORT` pล™epรญลกe pouze posluchaฤe API kompatibilnรญ s OpenAI\n- `DASHBOARD_PORT` pล™epรญลกe pouze posluchaฤe dashboard/Next.js\nโ€“ Nastavte โ€žNEXT_PUBLIC_BASE_URLโ€œ na svลฏj ล™รญdicรญ panel/veล™ejnou adresu URL (pro zpฤ›tnรก volรกnรญ OAuth)\n\n**Chyby synchronizace cloudu**\n\n- Ovฤ›ล™te, ลพe `BASE_URL` odkazuje na vaลกi spuลกtฤ›nou instanci\n- Ovฤ›ล™te, ลพe `CLOUD_URL` odkazuje na oฤekรกvanรฝ koncovรฝ bod cloudu\n- Udrลพujte hodnoty `NEXT_PUBLIC_*` zarovnanรฉ s hodnotami na stranฤ› serveru\n\n**Prvnรญ pล™ihlรกลกenรญ nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v `.env`\n- Pokud nenรญ nastaveno, zรกloลพnรญ heslo je `123456`\n\n**ลฝรกdnรฉ protokoly poลพadavkลฏ**\n\n- Artefakty poลพadavku se zapisujรญ do `DATA_DIR/call_logs/` jako jeden soubor JSON na poลพadavek\n- Povolte zachycenรญ potrubรญ z ล™รญdicรญho panelu โ†’ Protokoly โ†’ Protokoly ลพรกdostรญ, pokud potล™ebujete podrobnรฉ uลพiteฤnรฉ zatรญลพenรญ pro jednotlivรฉ fรกze\n- Nastavte `APP_LOG_TO_FILE=true`, pokud chcete takรฉ protokoly konzoly aplikace v `logs/application/app.log`\nโ€“ Podle potล™eby upravte `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES` a `CALL_LOG_MAX_ENTRIES`\n\n**Test pล™ipojenรญ ukazuje โ€žNeplatnรฉโ€œ pro poskytovatele kompatibilnรญ s OpenAI**\n\n- Mnoho poskytovatelลฏ nevystavuje koncovรฝ bod `/models`\n- OmniRoute v1.0.6+ zahrnuje nouzovรฉ ovฤ›ล™enรญ prostล™ednictvรญm dokonฤenรญ chatu\n- Zajistฤ›te, aby zรกkladnรญ adresa URL obsahovala pล™รญponu `/v1`### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n>**โš ๏ธ Dลฏleลพitรฉ pro uลพivatele provozujรญcรญ OmniRoute na VPS, Dockeru nebo jakรฉmkoli vzdรกlenรฉm serveru**#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nPoskytovatelรฉ**Antigravity**a**Gemini CLI**pouลพรญvajรญ**Google OAuth 2.0**. Google vyลพaduje, aby parametr `redirect_uri` v toku OAuth pล™esnฤ› odpovรญdal jednomu z pล™edem registrovanรฝch URI v Google Cloud Console aplikace.\n\nPล™ihlaลกovacรญ รบdaje OAuth dodรกvanรฉ v OmniRoute jsou registrovรกny**pouze pro `localhost`**. Kdyลพ pล™istupujete k OmniRoute na vzdรกlenรฉm serveru (napล™. `https://omniroute.myserver.com`), Google odmรญtne ovฤ›ล™enรญ pomocรญ:```\nError 400: redirect_uri_mismatch\n````\n\n#### Solution: Configure your own OAuth credentials\n\nVe sluลพbฤ› Google Cloud Console musรญte vytvoล™it**OAuth 2.0 Client ID**s identifikรกtorem URI vaลกeho serveru.#### Step-by-step\n\n**1. Otevล™รญt Google Cloud Console**\n\nPล™ejdฤ›te na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvoล™it novรฉ ID klienta OAuth 2.0**\n\nโ€“ Kliknฤ›te na**\"+ Vytvoล™it pล™ihlaลกovacรญ รบdaje\"**โ†’**\"ID klienta OAuth\"**\n\n- Typ aplikace:**\"Webovรก aplikace\"**\n- Nรกzev: cokoliv se vรกm lรญbรญ (napล™. `OmniRoute Remote`)\n\n**3. Pล™idat identifikรกtory URI autorizovanรฉho pล™esmฤ›rovรกnรญ**\n\nDo pole**\"URI autorizovanรฉho pล™esmฤ›rovรกnรญ\"**pล™idejte:```\nhttps://your-server.com/callback\n\n````\n\n> Nahraฤte `vas-server.com` domรฉnou nebo IP svรฉho serveru (v pล™รญpadฤ› potล™eby uveฤte port, napล™. `http://45.33.32.156:20128/callback`).\n\n**4. Uloลพte a zkopรญrujte pล™ihlaลกovacรญ รบdaje**\n\nPo vytvoล™enรญ Google zobrazรญ**Client ID**a**Client Secret**.\n\n**5. Nastavit promฤ›nnรฉ prostล™edรญ**\n\nVe vaลกem `.env` (nebo promฤ›nnรฝch prostล™edรญ Docker):```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n````\n\n**6. Restartujte OmniRoute**```bash\n\n# npm:\n\nnpm run dev\n\n# Docker:\n\ndocker restart omniroute\n\n````\n\n**7. Zkuste se pล™ipojit znovu**\n\nOvlรกdacรญ panel โ†’ Poskytovatelรฉ โ†’ Antigravitace (nebo Gemini CLI) โ†’ OAuth\n\nGoogle se nynรญ sprรกvnฤ› pล™esmฤ›ruje na `https://vas-server.com/callback`.---\n\n#### Temporary workaround (without custom credentials)\n\nPokud si nynรญ nechcete nastavovat vlastnรญ pล™ihlaลกovacรญ รบdaje, mลฏลพete stรกle pouลพรญt**ruฤnรญ postup URL**:\n\n1. OmniRoute otevล™e autorizaฤnรญ URL Google\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (kterรฝ selลพe na vzdรกlenรฉm serveru)\n3.**Zkopรญrujte celou adresu URL**z adresnรญho ล™รกdku prohlรญลพeฤe (i kdyลพ se strรกnka nenaฤte)\n4. Vloลพte tuto adresu URL do pole zobrazenรฉho v modรกlu pล™ipojenรญ OmniRoute\n5. Kliknฤ›te na**\"Pล™ipojit\"**\n\n> Funguje to, protoลพe autorizaฤnรญ kรณd v adrese URL je platnรฝ bez ohledu na to, zda se strรกnka pล™esmฤ›rovรกnรญ naฤetla.---\n\n\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOsvedฤuje**Antigravity**a**Gemini CLI**pouลพรญvรกme**Google OAuth 2.0**pro autenticitu. O Google exige que a `redirect_uri` usada no fluxo OAuth seja**exatamente**uma das URIs prรฉ-cadastradas no Google Cloud Console to use.\n\nJako credenciais OAuth embutidas no OmniRoute estรฃo cadastradas**apenas para `localhost`**. Quando vocรช acessa o OmniRoute um um servidor remote (ex: `https://omniroute.meuservidor.com`), nebo Google rejeita a autenticaรงรฃo com:```\nError 400: redirect_uri_mismatch\n````\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um**OAuth 2.0 Client ID**no Google Cloud Console com a URI do seu server.#### Passo a passo\n\n**1. Pล™รญstup ke sluลพbฤ› Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Kliknฤ›te na**\"+ Vytvoล™it pล™ihlaลกovacรญ รบdaje\"**โ†’**\"ID klienta OAuth\"**\n- Tipo de aplicativo:**\"Webovรก aplikace\"**\n- Nome: escolha qualquer nome (napล™.: `OmniRoute Remote`)\n\n**3. Adicione jako Authorized Redirect URI**\n\nลฝรกdnรฉ pole**\"URI autorizovanรฉho pล™esmฤ›rovรกnรญ\"**, adicione:```\nhttps://seu-servidor.com/callback\n\n````\n\n> Substitua `seu-servidor.com` pelo domรญnio nebo IP do seu servidor (vฤetnฤ› portu se necessรกrio, napล™.: `http://45.33.32.156:20128/callback`).\n\n**4. Uloลพit a zkopรญrovat jako credenciais**\n\nApรณs criar, o Google mostrarรก o**Client ID**e o**Client Secret**.\n\n**5. Konfigurovat jako variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n````\n\n**6. Reinicie nebo OmniRoute**```bash\n\n# Se usando npm:\n\nnpm run dev\n\n# Se usando Docker:\n\ndocker restart omniroute\n\n````\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Poskytovatelรฉ โ†’ Antigravitace (nebo Gemini CLI) โ†’ OAuth\n\nAgora nebo Google redirecionamente corretamente para `https://seu-servidor.com/callback` a autenticaรงรฃo funcionarรก.---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nZjistฤ›te, jakรฉ jsou รบdaje o vaลกรญ kreditnรญ kartฤ›, a je moลพnรฉ, ลพe pouลพijete fluxo**pล™รญruฤku URL**:\n\n1. O OmniRoute abrirรก a URL autorizaรงรฃo Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3.**Zkopรญrujte รบplnou adresu URL**da barra de endereรงo do seu browser (mesmo que a pagina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Kliknฤ›te na**\"Pล™ipojit\"**\n\n> Toto ล™eลกenรญ funguje pomocรญ autorizaฤnรญho kรณdu na URL a nezรกvislรฉho pล™esmฤ›rovรกnรญ.\n\n---\n\n\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n\nKliknutรญm rozbalรญte podrobnosti o technologickรฉm zรกsobnรญku\n\n-**Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ nenรญ**podporovรกn**โ€“ nativnรญ binรกrnรญ soubory `better-sqlite3` jsou nekompatibilnรญ)\n-**Jazyk**: TypeScript 5.9 โ€”**100% TypeScript**napล™รญฤ `src/` a `open-sse/` (nula `any` v zรกkladnรญch modulech od verze 2.0)\n-**Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n-**Databรกze**: LowDB (JSON) + SQLite (stav domรฉny + protokoly proxy + audit MCP + rozhodnutรญ o smฤ›rovรกnรญ)\n-**Schรฉmata**: Zod (ovฤ›ล™enรญ I/O nรกstroje MCP, smlouvy API)\n-**Protokoly**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n-**Streamovรกnรญ**: Server-Sent Events (SSE)\n-**Auth**: OAuth 2.0 (PKCE) + JWT + API klรญฤe + MCP Scoped Authorization\n-**Testovรกnรญ**: Testovacรญ program Node.js + Vitest (vรญce neลพ 900 testลฏ vฤetnฤ› jednotky, integrace, E2E)\n-**CI/CD**: Akce GitHub (automatickรฉ publikovรกnรญ npm + Docker Hub pล™i vydรกnรญ)\n-**Web**: [omniroute.online](https://omniroute.online)\n-**Balรญk**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n-**Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n-**Odolnost**: Jistiฤ, exponenciรกlnรญ รบstup, stรกdo proti hromลฏm, TLS spoofing, auto-kombo samolรฉฤenรญ\n\n---\n\n## Dokumentace\n\n| Dokument | Popis |\n| ---------------------------------------------- | ---------------------------------------------------- |\n| [Uลพivatelskรก pล™รญruฤka](docs/USER_GUIDE.md) | Poskytovatelรฉ, komba, integrace CLI, nasazenรญ |\n| [Reference API](docs/API_REFERENCE.md) | Vลกechny koncovรฉ body s pล™รญklady |\n| [Server MCP](open-sse/mcp-server/README.md) | 16 MCP nรกstroje, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamovรกnรญ, sprรกva รบloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorovรฉ bodovรกnรญ, balรญฤky reลพimลฏ, samolรฉฤenรญ |\n| [Odstraลˆovรกnรญ problรฉmลฏ](docs/TROUBLESHOOTING.md) | Bฤ›ลพnรฉ problรฉmy a ล™eลกenรญ |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura systรฉmu a vnitล™nรญ ฤรกsti |\n| [Pล™ispรญvรก](CONTRIBUTING.md) | Vรฝvojovรฉ nastavenรญ a pokyny |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpeฤnostnรญ zรกsady](SECURITY.md) | Hlรกลกenรญ zranitelnosti a bezpeฤnostnรญ postupy |\n| [Deployment VM](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletnรญ prลฏvodce: Nastavenรญ VM + nginx + Cloudflare |\n| [Galerie funkcรญ](docs/FEATURES.md) | Vizuรกlnรญ prohlรญdka ล™รญdicรญho panelu se snรญmky obrazovky |\n| [Kontrolnรญ seznam vydรกnรญ](docs/RELEASE_CHECKLIST.md) | Kroky ovฤ›ล™enรญ pล™ed vydรกnรญm |---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute mรก naplรกnovรกno**210+ funkcรญ**v nฤ›kolika fรกzรญch vรฝvoje. Zde jsou klรญฤovรฉ oblasti:\n\n| Kategorie | Plรกnovanรฉ funkce | Hlavnรญ body |\n| ------------------------------ | ----------------- | -------------------------------------------------------------------------------------- |\n| ๐Ÿง **Smฤ›rovรกnรญ a inteligence**| 25+ | Smฤ›rovรกnรญ s nejniลพลกรญ latencรญ, smฤ›rovรกnรญ zaloลพenรฉ na znaฤkรกch, pล™edbฤ›ลพnรก kontrola kvรณt, vรฝbฤ›r รบฤtu P2C |\n| ๐Ÿ”’**Zabezpeฤenรญ a dodrลพovรกnรญ pล™edpisลฏ**| 20+ | Zpevnฤ›nรญ SSRF, maskovรกnรญ povฤ›ล™enรญ, rychlostnรญ limit na koncovรฝ bod, stanovenรญ rozsahu klรญฤe managementu |\n| ๐Ÿ“Š**Pozorovatelnost**| 15+ | Integrace OpenTelemetry, sledovรกnรญ kvรณt v reรกlnรฉm ฤase, sledovรกnรญ nรกkladลฏ na model |\n| ๐Ÿ”„**Integrace poskytovatelลฏ**| 20+ | Registr dynamickรฉho modelu, cooldowny poskytovatelลฏ, kodex pro vรญce รบฤtลฏ, analรฝza kvรณt Copilota |\n| โšก**Vรฝkon**| 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ**Ekosystรฉm**| 10+ | WebSocket API, konfigurace hot-reload, distribuovanรฉ รบloลพiลกtฤ› konfigurace, komerฤnรญ reลพim |### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”—**Integrace OpenCode**โ€“ Podpora nativnรญho poskytovatele pro IDE kรณdovรกnรญ OpenCode AI\n- ๐Ÿ”—**Integrace TRAE**โ€” Plnรก podpora pro vรฝvojovรฝ rรกmec TRAE AI\n- ๐Ÿ“ฆ**Batch API**โ€” Asynchronnรญ dรกvkovรฉ zpracovรกnรญ pro hromadnรฉ poลพadavky\n- ๐ŸŽฏ**Smฤ›rovรกnรญ zaloลพenรฉ na znaฤkรกch**โ€“ Smฤ›rovรกnรญ poลพadavkลฏ na zรกkladฤ› vlastnรญch znaฤek a metadat\n- ๐Ÿ’ฐ**Strategie nejniลพลกรญch nรกkladลฏ**โ€” Automaticky vyberte nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n> ๐Ÿ“ รšplnรฉ specifikace funkcรญ dostupnรฉ v [`docs/new-features/`](docs/new-features/) (217 podrobnรฝch specifikacรญ)---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Rozdฤ›lte รบloลพiลกtฤ›\n2. Vytvoล™te si vฤ›tev funkcรญ (`git checkout -b feature/amazing-feature`)\n3. Potvrฤte zmฤ›ny (`git commit -m 'Pล™idat รบลพasnou funkci'`)\n4. Push do vฤ›tve (`git Push origin feature/amazing-feature`)\n5. Otevล™ete ลพรกdost o staลพenรญ\n\nPodrobnรฉ pokyny najdete na [CONTRIBUTING.md](CONTRIBUTING.md).### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n````\n\n---\n\n## ๐Ÿ“Š Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## ๐Ÿ™ Acknowledgments\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ**[9router](https://github.com/decolua/9router)**od**[decolua](https://github.com/decolua)**โ€” pลฏvodnรญmu projektu, kterรฝ inspiroval tento fork. OmniRoute stavรญ na tomto neuvฤ›ล™itelnรฉm zรกkladu s dalลกรญmi funkcemi, multimodรกlnรญmi API a รบplnรฝm pล™epsรกnรญm TypeScriptu.\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ**[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)**โ€“ pลฏvodnรญ implementaci Go, kterรก inspirovala tento port JavaScriptu.---\n\n## Licence\n\nLicence MIT โ€“ podrobnosti viz [LICENCE](LICENCE).---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "bd281e5753a872fcae52091f909734e96710f61e": {"t": 1785764452.4125838, "n": 106636, "h": "403ccd17ab684fa1", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n\n![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red)\n![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red)\n\n![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red)\n![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue)\n\n[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers)\n[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues)\n[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main)\n[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute)\n[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed)\n[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags)\n[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)\n[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers)\n[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members)\n[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers)\n\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Gemini
\n Gemini CLI\n
\n โญ 94.7K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random)\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Circuit Breaker per-model** โ€” Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks\n- **Exponential Backoff** โ€” Progressive retry delays\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** โ€” Auto-disables failing providers within a combo chain\n- **Health Dashboard** โ€” Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** โ€” Configurable defaults in Settings โ†’ Resilience with persistence\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** |\n| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream fetch, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Total upstream request timeout used by the main fetch abort signal |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport LOG_TO_FILE=\"${LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v2.0 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | -------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿ“Š **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** ๐Ÿ†• | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| ---------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 16 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ€” the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "19f46eb81743cf9992edc6ff7af268a1da79ffe6": {"t": 1785764454.1418045, "n": 104159, "h": "c6ec9d472b2e7da4", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../hi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../tr/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![npm downloads](https://img.shields.io/npm/dm/omniroute?color=cb3837&logo=npm&label=npm%20downloads)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n[![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute?logo=docker&color=2496ED&label=docker%20pulls)](https://hub.docker.com/r/diegosouzapw/omniroute)\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Gemini
\n Gemini CLI\n
\n โญ 94.7K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Provider Limits Tracking** โ€” Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random)\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Circuit Breaker per-model** โ€” Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks\n- **Exponential Backoff** โ€” Progressive retry delays\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** โ€” Auto-disables failing providers within a combo chain\n- **Health Dashboard** โ€” Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** โ€” Configurable defaults in Settings โ†’ Resilience with persistence\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** |\n| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### Long-Running Streaming Timeouts\n\nFor most deployments, you only need:\n\n| Variable | Default | Purpose |\n| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream fetch, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts |\n| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream |\n\nBackward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline.\n\nAdvanced overrides are available if you need finer control:\n\n| Variable | Default | Purpose |\n| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |\n| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Total upstream request timeout used by the main fetch abort signal |\n| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers |\n| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) |\n| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout |\n| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout |\n| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` |\n| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `30000` | Timeout for `/v1` proxy forwarding from API port to dashboard port |\n| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server |\n| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server |\n| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server |\n| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) |\n\nIf you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy\ntimeouts are also higher than your OmniRoute stream/fetch timeouts.\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport LOG_TO_FILE=\"${LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --stop-timeout 40 \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.\n- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free PAT via qodercli)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is\n> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured.\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v2.0 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | -------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿ“Š **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** ๐Ÿ†• | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| ---------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 16 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ€” the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "bfeb1693d691d7e3e60da1fc1c81b3ccf113c42f": {"t": 1785764455.7594714, "n": 104221, "h": "a9584470182d688c", "c": "# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md)\n\n---\n\n### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.\n\n_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._\n\n**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript**\n\n---\n\n
\n\n[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)\n[![npm downloads](https://img.shields.io/npm/dm/omniroute?color=cb3837&logo=npm&label=npm%20downloads)](https://www.npmjs.com/package/omniroute)\n[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)\n[![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute?logo=docker&color=2496ED&label=docker%20pulls)](https://hub.docker.com/r/diegosouzapw/omniroute)\n[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)\n[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n\n
\n\n๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## Breaking Change: Unified Logging Upgrade\n\n> [!WARNING]\n> **This release changes both the on-disk request log layout and the logging environment variables.**\n>\n> If you are upgrading an existing instance:\n>\n> - Request logs now live in `DATA_DIR/call_logs/YYYY-MM-DD/` as **one JSON artifact per request**.\n> - The old `DATA_DIR/logs/` session folders and `DATA_DIR/log.txt` summary file are removed.\n> - On the first startup after upgrading, OmniRoute creates a safety backup at `DATA_DIR/log_archives/*.zip` before removing the deprecated request log layout.\n> - Legacy logging env vars such as `LOG_TO_FILE`, `LOG_FILE_PATH`, `LOG_MAX_FILE_SIZE`, `LOG_RETENTION_DAYS`, `LOG_LEVEL`, `LOG_FORMAT`, `ENABLE_REQUEST_LOGS`, `CALL_LOGS_MAX`, `CALL_LOG_PAYLOAD_MODE`, and `PROXY_LOG_MAX_ENTRIES` are no longer supported.\n> - Use the new env model instead:\n> - `APP_LOG_TO_FILE`\n> - `APP_LOG_FILE_PATH`\n> - `APP_LOG_MAX_FILE_SIZE`\n> - `APP_LOG_RETENTION_DAYS`\n> - `APP_LOG_MAX_FILES`\n> - `APP_LOG_LEVEL`\n> - `APP_LOG_FORMAT`\n> - `CALL_LOG_RETENTION_DAYS`\n> - `CALL_LOG_MAX_ENTRIES`\n>\n> For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md).\n\n---\n\n## ๐Ÿ†• What's New\n\n> **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.\n\n| Area | Change |\n| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |\n| โœ… **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` โ€” CI `check:route-validation:t06` passes |\n| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streaming responses (#585) |\n| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |\n| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG โ†’ generic fallback chain |\n| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |\n| ๐ŸŒ **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |\n| ๐Ÿ› **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |\n| ๐Ÿ› **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |\n| ๐Ÿ› **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |\n| ๐Ÿ› **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |\n| ๐Ÿ› **Login redirect** | Login no longer freezes after skipping password setup |\n| ๐Ÿ› **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\\...` automatically |\n\n---\n\n## ๐Ÿ–ผ๏ธ Main Dashboard\n\n
\n \"OmniRoute\n
\n\n---\n\n## ๐Ÿ“ธ Dashboard Preview\n\n
\nClick to see dashboard screenshots\n\n| Page | Screenshot |\n| -------------- | ------------------------------------------------- |\n| **Providers** | ![Providers](docs/screenshots/01-providers.png) |\n| **Combos** | ![Combos](docs/screenshots/02-combos.png) |\n| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |\n| **Health** | ![Health](docs/screenshots/04-health.png) |\n| **Translator** | ![Translator](docs/screenshots/05-translator.png) |\n| **Settings** | ![Settings](docs/screenshots/06-settings.png) |\n| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |\n| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |\n| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |\n\n
\n\n---\n\n### ๐Ÿค– Free AI Provider for your favorite coding agents\n\n_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \"OpenClaw\"
\n OpenClaw\n
\n โญ 205K\n 		\n \n \"NanoBot\"
\n NanoBot\n
\n โญ 20.9K\n 		\n \n \"PicoClaw\"
\n PicoClaw\n
\n โญ 14.6K\n 		\n \n \"ZeroClaw\"
\n ZeroClaw\n
\n โญ 9.9K\n 		\n \n \"IronClaw\"
\n IronClaw\n
\n โญ 2.1K\n
\n \n \"OpenCode\"
\n OpenCode\n
\n โญ 106K\n 		\n \n \"Codex
\n Codex CLI\n
\n โญ 60.8K\n 		\n \n \"Claude
\n Claude Code\n
\n โญ 67.3K\n 		\n \n \"Gemini
\n Gemini CLI\n
\n โญ 94.7K\n 		\n \n \"Kilo
\n Kilo Code\n
\n โญ 15.5K\n
\n\n๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota\n\n---\n\n## ๐Ÿค” Why OmniRoute?\n\n**Stop wasting money and hitting limits:**\n\n- Subscription quota expires unused every month\n- Rate limits stop you mid-coding\n- Expensive APIs ($20-50/month per provider)\n- Manual switching between providers\n\n**OmniRoute solves this:**\n\n- โœ… **Maximize subscriptions** - Track quota, use every bit before reset\n- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime\n- โœ… **Multi-account** - Round-robin between accounts per provider\n- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool\n\n---\n\n## ๐Ÿ“ง Support\n\n> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated.\n\n- **Website**: [omniroute.online](https://omniroute.online)\n- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`\n- **Original Project**: [9router by decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Reporting a Bug?\n\nWhen opening an issue, please run the system-info command and attach the generated file:\n\n```bash\nnpm run system-info\n```\n\nThis generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.\n\n---\n\n## ๐Ÿ”„ How It Works\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases\n\n> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.\n\n
\n๐Ÿ’ธ 1. \"I pay for an expensive subscription but still get interrupted by limits\"\n\nDevelopers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity.\n\n**How OmniRoute solves it:**\n\n- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention\n- **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly)\n- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next\n- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random)\n- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard\n\n
\n\n
\n๐Ÿ”Œ 2. \"I need to use multiple providers but each has a different API\"\n\nOpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints.\n\n**How OmniRoute solves it:**\n\n- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers\n- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+\n- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE\n- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content`\n- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion\n- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs\n\n
\n\n
\n๐ŸŒ 3. \"My AI provider blocks my region/country\"\n\nProviders like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries.\n\n**How OmniRoute solves it:**\n\n- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key\n- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP\n- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory`\n- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass)\n- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing\n- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection\n- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously\n\n
\n\n
\n๐Ÿ†“ 4. \"I want to use AI for coding but I have no money\"\n\nNot everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost.\n\n**How OmniRoute solves it:**\n\n- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free)\n- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free \"Light usage\" tier; use `ollamacloud/` prefix\n- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime\n- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits)\n- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider\n\n
\n\n
\n๐Ÿ”’ 5. \"I need to protect my AI gateway from unauthorized access\"\n\nWhen exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse.\n\n**How OmniRoute solves it:**\n\n- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page\n- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle\n- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing\n- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens\n- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows\n- **IP Filtering** โ€” Allowlist/blocklist for access control\n- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns\n- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest\n\n
\n\n
\n๐Ÿ›‘ 6. \"My provider went down and I lost my coding flow\"\n\nAI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application.\n\n**How OmniRoute solves it:**\n\n- **Circuit Breaker per-model** โ€” Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks\n- **Exponential Backoff** โ€” Progressive retry delays\n- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms\n- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention\n- **Combo Circuit Breaker** โ€” Auto-disables failing providers within a combo chain\n- **Health Dashboard** โ€” Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency\n\n
\n\n
\n๐Ÿ”ง 7. \"Configuring each AI tool is tedious and repetitive\"\n\nDevelopers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time.\n\n**How OmniRoute solves it:**\n\n- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline\n- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection\n- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users\n- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers\n\n
\n\n
\n๐Ÿ”‘ 8. \"Managing OAuth tokens from multiple providers is hell\"\n\nClaude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic.\n\n**How OmniRoute solves it:**\n\n- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration\n- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction\n- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers\n- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility\n- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker\n\n
\n\n
\n๐Ÿ“Š 9. \"I don't know how much I'm spending or where\"\n\nDevelopers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up.\n\n**How OmniRoute solves it:**\n\n- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider\n- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback\n- **Per-Model Pricing Configuration** โ€” Configurable prices per model\n- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key\n- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency\n\n
\n\n
\n๐Ÿ› 10. \"I can't diagnose errors and problems in AI calls\"\n\nWhen a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error.\n\n**How OmniRoute solves it:**\n\n- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console\n- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter\n- **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts\n- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time)\n- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing\n- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count\n- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.\n\n
\n\n
\n๐Ÿ—๏ธ 11. \"Deploying and maintaining the gateway is complex\"\n\nInstalling, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction.\n\n**How OmniRoute solves it:**\n\n- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done\n- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw)\n- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode\n- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking)\n- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers\n- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups\n\n
\n\n
\n๐ŸŒ 12. \"The interface is English-only and my team doesn't speak English\"\n\nTeams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors.\n\n**How OmniRoute solves it:**\n\n- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English\n- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew\n- **Multi-Language READMEs** โ€” 30 complete documentation translations\n- **Language Selector** โ€” Globe icon in header for real-time switching\n\n
\n\n
\n๐Ÿ”„ 13. \"I need more than chat โ€” I need embeddings, images, audio\"\n\nAI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format.\n\n**How OmniRoute solves it:**\n\n- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models\n- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI\n- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers\n- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks\n- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking\n- **Responses API** โ€” Full `/v1/responses` support for Codex\n\n
\n\n
\n๐Ÿงช 14. \"I have no way to test and compare quality across models\"\n\nDevelopers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist.\n\n**How OmniRoute solves it:**\n\n- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal\n- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function)\n- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison\n- **Chat Tester** โ€” Full round-trip with visual response rendering\n- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy\n\n
\n\n
\n๐Ÿ“ˆ 15. \"I need to scale without losing performance\"\n\nAs request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected.\n\n**How OmniRoute solves it:**\n\n- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency\n- **Request Idempotency** โ€” 5s deduplication window for identical requests\n- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking\n- **Editable Rate Limits** โ€” Configurable defaults in Settings โ†’ Resilience with persistence\n- **API Key Validation Cache** โ€” 3-tier cache for production performance\n- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime\n\n
\n\n
\n๐Ÿค– 16. \"I want to control model behavior globally\"\n\nDevelopers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical.\n\n**How OmniRoute solves it:**\n\n- **System Prompt Injection** โ€” Global prompt applied to all requests\n- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive)\n- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed\n- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider\n- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard\n- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click\n- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing\n\n
\n\n
\n๐Ÿงฐ 17. \"I need MCP tools as first-class product capabilities\"\n\nMany AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.\n\n**How OmniRoute solves it:**\n\n- MCP appears in the dashboard navigation and endpoint protocol tab\n- Dedicated MCP management page with process, tools, scopes, and audit\n- Built-in quick-start for `omniroute --mcp` and client onboarding\n\n
\n\n
\n๐Ÿง  18. \"I need A2A orchestration with sync + stream task paths\"\n\nAgent workflows need both direct replies and long-running streamed execution with lifecycle control.\n\n**How OmniRoute solves it:**\n\n- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`\n- SSE streaming with terminal state propagation\n- Task lifecycle APIs for `tasks/get` and `tasks/cancel`\n\n
\n\n
\n๐Ÿ›ฐ๏ธ 19. \"I need real MCP process health, not guessed status\"\n\nOperational teams need to know if MCP is actually alive, not just whether an API is reachable.\n\n**How OmniRoute solves it:**\n\n- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode\n- MCP status API combining heartbeat + recent activity\n- UI status cards for process/uptime/heartbeat freshness\n\n
\n\n
\n๐Ÿ“‹ 20. \"I need auditable MCP tool execution\"\n\nWhen tools mutate config or trigger ops actions, teams need forensic traceability.\n\n**How OmniRoute solves it:**\n\n- SQLite-backed audit logging for MCP tool calls\n- Filters by tool, success/failure, API key, and pagination\n- Dashboard audit table + stats endpoints for automation\n\n
\n\n
\n๐Ÿ” 21. \"I need scoped MCP permissions per integration\"\n\nDifferent clients should have least-privilege access to tool categories.\n\n**How OmniRoute solves it:**\n\n- 10 granular MCP scopes for controlled tool access\n- Scope enforcement and visibility in MCP management UI\n- Safe default posture for operational tooling\n\n
\n\n
\nโš™๏ธ 22. \"I need operational controls without redeploying\"\n\nTeams need quick runtime changes during incidents or cost events.\n\n**How OmniRoute solves it:**\n\n- Switch combo activation directly from MCP dashboard\n- Apply resilience profiles from pre-defined policy packs\n- Reset circuit breaker state from the same operations panel\n\n
\n\n
\n๐Ÿ”„ 23. \"I need live A2A task lifecycle visibility and cancellation\"\n\nWithout lifecycle visibility, task incidents become hard to triage.\n\n**How OmniRoute solves it:**\n\n- Task listing/filtering by state/skill with pagination\n- Drill-down on task metadata, events, and artifacts\n- Task cancellation endpoint and UI action with confirmation\n\n
\n\n
\n๐ŸŒŠ 24. \"I need active stream metrics for A2A load\"\n\nStreaming workflows require operational insight into concurrency and live connections.\n\n**How OmniRoute solves it:**\n\n- Active stream counters integrated into A2A status\n- Last task timestamp and per-state counts\n- A2A dashboard cards for real-time ops monitoring\n\n
\n\n
\n๐Ÿชช 25. \"I need standard agent discovery for clients\"\n\nExternal clients and orchestrators need machine-readable metadata for onboarding.\n\n**How OmniRoute solves it:**\n\n- Agent Card exposed at `/.well-known/agent.json`\n- Capabilities and skills shown in management UI\n- A2A status API includes discovery metadata for automation\n\n
\n\n
\n๐Ÿงญ 26. \"I need protocol discoverability in the product UX\"\n\nIf users cannot discover protocol surfaces, adoption and support quality drop.\n\n**How OmniRoute solves it:**\n\n- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints\n- Inline service status toggles (Online/Offline) for MCP and A2A\n- Links from overview to dedicated management tabs\n\n
\n\n
\n๐Ÿงช 27. \"I need end-to-end protocol validation with real clients\"\n\nMock tests are not enough to validate protocol compatibility before release.\n\n**How OmniRoute solves it:**\n\n- E2E suite that boots app and uses real MCP SDK client transport\n- A2A client tests for discovery, send, stream, get, and cancel flows\n- Cross-check assertions against MCP audit and A2A tasks APIs\n\n
\n\n
\n๐Ÿ“ก 28. \"I need unified observability across all interfaces\"\n\nSplitting observability by protocol creates blind spots and longer MTTR.\n\n**How OmniRoute solves it:**\n\n- Unified dashboards/logs/analytics in one product\n- Health + audit + request telemetry across OpenAI, MCP, and A2A layers\n- Operational APIs for status and automation\n\n
\n\n
\n๐Ÿ’ผ 29. \"I need one runtime for proxy + tools + agent orchestration\"\n\nRunning many separate services increases operational cost and failure modes.\n\n**How OmniRoute solves it:**\n\n- OpenAI-compatible proxy, MCP server, and A2A server in one stack\n- Shared auth, resilience, data store, and observability\n- Consistent policy model across all interaction surfaces\n\n
\n\n
\n๐Ÿš€ 30. \"I need to ship agentic workflows without glue-code sprawl\"\n\nTeams lose velocity when stitching multiple ad-hoc services and scripts.\n\n**How OmniRoute solves it:**\n\n- Unified endpoint strategy for clients and agents\n- Built-in protocol management UIs and smoke validation paths\n- Production-ready foundations (security, logging, resilience, backup)\n\n
\n\n### Example Playbooks (Integrated Use Cases)\n\n**Playbook A: Maximize paid subscription + cheap backup**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Playbook B: Zero-cost coding stack**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Playbook C: 24/7 always-on fallback chain**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Playbook D: Agent ops with MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost\n\n> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.\n\n| Step | Action | Providers Unlocked |\n| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |\n| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** |\n| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** |\n| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** |\n| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** |\n| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically |\n\n**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.\n\n> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).\n\n## Rychlรฝ start\n\n### 1) Install and run\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.\n\n| Command | Description |\n| ----------------------- | ----------------------------------------------------------- |\n| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |\n| `omniroute --port 3000` | Set canonical/API port to 3000 |\n| `omniroute --mcp` | Start MCP server (stdio transport) |\n| `omniroute --no-open` | Don't auto-open browser |\n| `omniroute --help` | Show help |\n\nOptional split-port mode:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Connect providers and create your API key\n\n1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key).\n2. Open Dashboard โ†’ `Endpoints` and create an API key.\n3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain.\n\n### 3) Point your coding tool to OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nWorks with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.\n\n### 4) Enable and validate protocols (v2.0)\n\n**MCP (for tool-driven operations):**\n\n```bash\nomniroute --mcp\n```\n\nThen connect your MCP client over `stdio` and test tools like:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (for agent-to-agent workflows):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Validate everything end-to-end (recommended)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis suite validates real MCP and A2A client flows against a running app.\n\n### Alternative: run from source\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n
\nVoid Linux (`xbps-src` template)\n\nFor Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`:\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.4.1\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts (no network in do_build, native modules\n\t# compiled separately below; better-sqlite3 is serverExternalPackage so\n\t# Next.js does not execute it during next build)\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding for the target architecture.\n\t# Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used\n\t# without npm altering them.\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true\n\t# so sharp is not used at runtime; x64 .so files would break aarch64 strip\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\t# pino-abstract-transport โ€“ required by pino's worker thread\n\t# split2 โ€“ dep of pino-abstract-transport\n\t# process-warning โ€“ dep of pino itself\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport LOG_TO_FILE=\"${LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).\n\n**Quick run:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**With environment file:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Using Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\nDashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL.\n\nNotes:\n\n- Quick Tunnel URLs are temporary and change after every restart.\n- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.\n- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.\n- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.\n\n**Using Docker Compose with Caddy (HTTPS Auto-TLS):**\n\nOmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.\n\n```yaml\nservices:\n omniroute:\n image: diegosouzapw/omniroute:latest\n container_name: omniroute\n restart: unless-stopped\n volumes:\n - omniroute-data:/app/data\n environment:\n - PORT=20128\n - NEXT_PUBLIC_BASE_URL=https://your-domain.com\n\n caddy:\n image: caddy:latest\n container_name: caddy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128\n\nvolumes:\n omniroute-data:\n```\n\n| Image | Tag | Size | Description |\n| ------------------------ | -------- | ------ | --------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Current version |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On\n\n> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.\n\nRun OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes:\n\n- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration\n- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login\n- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues\n- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### System Tray\n\nWhen minimized, OmniRoute lives in your system tray with quick actions:\n\n- Open dashboard\n- Change server port\n- Quit application\n\n๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |\n| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |\n| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |\n| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |\n| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow |\n| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI |\n| | Mistral | Free trial + paid | Rate limited | European AI |\n| | OpenRouter | Pay-per-use | None | 100+ models aggr. |\n| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship |\n| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |\n| | Qwen | **$0** | Unlimited | 4 models unlimited |\n| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |\n| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth |\n| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |\n| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |\n| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |\n\n> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.\n\n**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever.\n\n---\n\n---\n\n## ๐Ÿ†“ Free Models โ€” What You Actually Get\n\n> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo.\n\n### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | --------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap |\n| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro |\n\n### ๐ŸŸข QODER MODELS (Free OAuth โ€” No Credit Card)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------ | ------ | ------------- | --------------- |\n| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap |\n| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap |\n| `deepseek-r1` | `if/` | **Unlimited** | No reported cap |\n| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap |\n| `kimi-k2` | `if/` | **Unlimited** | No reported cap |\n\n### ๐ŸŸก QWEN MODELS (Device Code Auth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------- | ------ | ------------- | ------------------- |\n| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap |\n| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap |\n| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) |\n\n### ๐ŸŸฃ GEMINI CLI (Google OAuth)\n\n| Model | Prefix | Limit | Rate Limit |\n| ------------------------ | ------ | --------------------------- | ------------- |\n| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |\n| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |\n\n### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---------- | ------------ | ----------- | ------------------------------------------------------ |\n| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |\n\nPopular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ----------------- | ---------------- | ------------------------------------------- |\n| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily |\n\nAvailable free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com)\n\n| Tier | Daily Limit | Rate Limit | Notes |\n| ---- | ------------- | ---------------- | ----------------------------------------- |\n| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged |\n\nAvailable free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3`\n\n### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†•\n\n| Model | Prefix | Daily Free Quota | Notes |\n| ----------------------------- | ------ | ----------------- | ----------------------- |\n| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever |\n| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat |\n| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT |\n| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version |\n| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal |\n\n> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC.\n\n### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†•\n\n| Model | Prefix | Rate Limit | Provider Behind |\n| ---------- | ------ | ---------- | ------------------ |\n| `openai` | `pol/` | 1 req/15s | GPT-5 |\n| `claude` | `pol/` | 1 req/15s | Anthropic Claude |\n| `gemini` | `pol/` | 1 req/15s | Google Gemini |\n| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 |\n| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout |\n| `mistral` | `pol/` | 1 req/15s | Mistral AI |\n\n> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately.\n\n### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†•\n\n| Tier | Daily Neurons | Equivalent Usage | Notes |\n| ---- | ------------- | --------------------------------------- | ----------------------- |\n| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models |\n\nPopular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct`\n\n> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings.\n\n### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†•\n\n| Tier | Free Quota | Location | Notes |\n| ---- | ------------- | ------------ | ----------------------------------- |\n| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits |\n\nAvailable free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324`\n\n> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com).\n\n> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):**\n>\n> ```\n> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\n> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\n> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\n> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\n> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED\n> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free\n> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day\n> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\n> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast\n> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\n> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n> ```\n\n## ๐ŸŽ™๏ธ Free Transcription Combo\n\n> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.\n\n| Provider | Free Credits | Best Model | Rate Limit |\n| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |\n| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits |\n| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits |\n| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) |\n\n**Suggested combo in `/dashboard/combos`:**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nThen in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats.\n\n## ๐Ÿ’ก Key Features\n\nOmniRoute v2.0 is built as an operational platform, not just a relay proxy.\n\n### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026)\n\n| Feature | What It Does |\n| ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family |\n| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 |\n| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models |\n| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content |\n| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data |\n| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges |\n| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins |\n\n### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP\n\n| Feature | What It Does |\n| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing |\n| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** |\n| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |\n| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a \"Download opencode.json\" button that auto-generates a ready-to-use config with all available models. |\n| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: \"responses\"` now correctly route to the Responses API translator |\n| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID |\n| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart |\n\n### ๐Ÿค– Agent & Protocol Operations (v2.0)\n\n| Feature | What It Does |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools |\n| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |\n| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |\n| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |\n| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |\n| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |\n| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access |\n| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |\n| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |\n| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |\n| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |\n\n### ๐Ÿง  Routing & Intelligence\n\n| Feature | What It Does |\n| ---------------------------------- | ------------------------------------------------------------------------ |\n| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free |\n| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider |\n| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions |\n| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |\n| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |\n| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control |\n| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing |\n| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |\n| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety |\n| โšก **Background Degradation** | Route low-priority background tasks to cheaper models |\n| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) |\n| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions |\n| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity |\n| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution |\n| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently |\n| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |\n\n### ๐ŸŽต Multi-Modal APIs\n\n| Feature | What It Does |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |\n| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |\n| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |\n| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages |\n| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |\n| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |\n| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks |\n| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring |\n| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache |\n\n### ๐Ÿ›ก๏ธ Resilience, Security & Governance\n\n| Feature | What It Does |\n| ----------------------------------- | -------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Circuit Breakers** | Per-model trip/recover with threshold controls |\n| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |\n| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |\n| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |\n| โšก **Request Idempotency** | Duplicate protection window |\n| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** |\n| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** |\n| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments |\n| ๐Ÿ“Š **Editable Rate Limits** | Configurable global/provider-level limits with persistence |\n| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations |\n| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks |\n| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures |\n| ๐Ÿšช **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically |\n| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |\n\n### ๐Ÿ“Š Observability & Analytics\n\n| Feature | What It Does |\n| -------------------------------- | ----------------------------------------------------- |\n| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging |\n| ๐Ÿ“‰ **Streamed Detailed Logs** ๐Ÿ†• | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |\n| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing |\n| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |\n| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |\n| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views |\n| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies |\n| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing |\n\n### โ˜๏ธ Deployment & Platform\n\n| Feature | What It Does |\n| ------------------------------ | --------------------------------------------------------------------- |\n| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |\n| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard |\n| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles |\n| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls |\n| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows |\n| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup |\n| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools |\n| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard |\n| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security |\n| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location |\n\n### Feature Deep Dive\n\n#### Smart fallback with practical cost control\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nWhen quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.\n\n#### Protocol management that is visible and operable\n\n- MCP + A2A are discoverable in UI and docs (not hidden)\n- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)\n- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)\n\n#### Translator + validation workflow\n\nThe Translator area includes:\n\n- **Playground**: request transformation checks\n- **Chat Tester**: full request/response round-trip\n- **Test Bench**: multiple cases in one run\n- **Live Monitor**: real-time traffic view\n\nPlus protocol validation with real clients via `npm run test:protocols:e2e`.\n\n> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples\n>\n> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle\n\n## ๐Ÿงช Evaluations (Evals)\n\nOmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard.\n\n### Built-in Golden Set\n\nThe pre-loaded \"OmniRoute Golden Set\" contains test cases for:\n\n- Greetings, math, geography, code generation\n- JSON format compliance, translation, markdown generation\n- Safety refusal (harmful content), counting, boolean logic\n\n### Evaluation Strategies\n\n| Strategy | Description | Example |\n| ---------- | ------------------------------------------------ | -------------------------------- |\n| `exact` | Output must match exactly | `\"4\"` |\n| `contains` | Output must contain substring (case-insensitive) | `\"Paris\"` |\n| `regex` | Output must match regex pattern | `\"1.*2.*3\"` |\n| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Setup Guide\n\n### Protocol Setup (MCP + A2A)\n\n
\n๐Ÿงฉ MCP Setup (Model Context Protocol)\n\nStart MCP transport in stdio mode:\n\n```bash\nomniroute --mcp\n```\n\nRecommended validation flow:\n\n1. Connect your MCP client over stdio.\n2. Run `omniroute_get_health`.\n3. Run `omniroute_list_combos`.\n4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.\n\nUseful APIs for automation:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n\n
\n๐Ÿค A2A Setup (Agent2Agent)\n\nDiscover the agent:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nSend a task:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nManage lifecycle:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nOperational UI:\n\n- `/dashboard/a2a` for task/state/stream observability and smoke actions\n\n
\n\n
\n๐Ÿงช End-to-end protocol validation\n\nValidate both protocols with real clients:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nThis verifies:\n\n- MCP SDK client connect/list/call\n- A2A discovery/send/stream/get/cancel\n- Cross-check data in MCP audit and A2A task management APIs\n\n
\n\n
\n๐Ÿ’ณ Subscription Providers\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Codex Account Limit Management (5h + Weekly)\n\nEach Codex account now has policy toggles in `Dashboard -> Providers`:\n\n- `5h` (ON/OFF): enforce the 5-hour window threshold policy.\n- `Weekly` (ON/OFF): enforce the weekly window threshold policy.\n- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.\n- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.\n- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.\n\nScenarios:\n\n- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.\n- `5h OFF` + `Weekly ON`: only weekly usage can block the account.\n- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.\n- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).\n\n### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n
\n\n
\n๐Ÿ”‘ API Key Providers\n\n### NVIDIA NIM (FREE developer access โ€” 70+ models)\n\n1. Sign up: [build.nvidia.com](https://build.nvidia.com)\n2. Get free API key (1000 inference credits included)\n3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM:\n - API Key: `nvapi-your-key`\n\n**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more\n\n**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation!\n\n### DeepSeek\n\n1. Sign up: [platform.deepseek.com](https://platform.deepseek.com)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ DeepSeek\n\n**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`\n\n### Groq (Free Tier Available!)\n\n1. Sign up: [console.groq.com](https://console.groq.com)\n2. Get API key (free tier included)\n3. Dashboard โ†’ Add Provider โ†’ Groq\n\n**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`\n\n**Pro Tip:** Ultra-fast inference โ€” best for real-time coding!\n\n### OpenRouter (100+ Models)\n\n1. Sign up: [openrouter.ai](https://openrouter.ai)\n2. Get API key\n3. Dashboard โ†’ Add Provider โ†’ OpenRouter\n\n**Models:** Access 100+ models from all major providers through a single API key.\n\n**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.\n\n
\n\n
\n๐Ÿ’ฐ Cheap Providers (Backup)\n\n### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key:\n - Provider: `glm`\n - API Key: `your-key`\n\n**Use:** `glm/glm-4.7`\n\n**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1`\n\n**Pro Tip:** Cheapest option for long context (1M tokens)!\n\n### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key\n3. Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest`\n\n**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n
\n\n
\n๐Ÿ†“ FREE Providers (Emergency Backup)\n\n### Qoder (5 FREE models via OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 FREE models via Device Code)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n\n
\n๐ŸŽจ Create Combos\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n\n
\n๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nUse the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually.\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Option 1 โ€” Dashboard (recommended):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues.\n\n### Cline / Continue / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Step 1:** Add OmniRoute as a custom provider:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Step 2:** Create/edit `opencode.json` in your project root:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Step 3:** Select the model in OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.\n\n
\n\n---\n\n## ล˜eลกenรญ problรฉmลฏ\n\n
\nClick to expand troubleshooting guide\n\n**\"Language model did not provide messages\"**\n\n- Provider quota exhausted โ†’ Check dashboard quota tracker\n- Solution: Use combo fallback or switch to cheaper tier\n\n**Rate limiting**\n\n- Subscription quota out โ†’ Fallback to GLM/MiniMax\n- Add combo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**OAuth token expired**\n\n- Auto-refreshed by OmniRoute\n- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect\n\n**High costs**\n\n- Check usage stats in Dashboard โ†’ Costs\n- Switch primary model to GLM/MiniMax\n- Use free tier (Gemini CLI, Qoder) for non-critical tasks\n\n**Dashboard/API ports are wrong**\n\n- `PORT` is the canonical base port (and API port by default)\n- `API_PORT` overrides only OpenAI-compatible API listener\n- `DASHBOARD_PORT` overrides only dashboard/Next.js listener\n- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks)\n\n**Cloud sync errors**\n\n- Verify `BASE_URL` points to your running instance\n- Verify `CLOUD_URL` points to your expected cloud endpoint\n- Keep `NEXT_PUBLIC_*` values aligned with server-side values\n\n**First login not working**\n\n- Check `INITIAL_PASSWORD` in `.env`\n- If unset, fallback password is `123456`\n\n**No request logs**\n\n- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request\n- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads\n- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log`\n- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed\n\n**Connection test shows \"Invalid\" for OpenAI-compatible providers**\n\n- Many providers don't expose a `/models` endpoint\n- OmniRoute v1.0.6+ includes fallback validation via chat completions\n- Ensure base URL includes `/v1` suffix\n\n### ๐Ÿ” OAuth on a Remote Server\n\n\n\n\n> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server**\n\n#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?\n\nThe **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.\n\nThe OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Solution: Configure your own OAuth credentials\n\nYou need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI.\n\n#### Step-by-step\n\n**1. Open Google Cloud Console**\n\nGo to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Create a new OAuth 2.0 Client ID**\n\n- Click **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Application type: **\"Web application\"**\n- Name: anything you like (e.g. `OmniRoute Remote`)\n\n**3. Add Authorized Redirect URIs**\n\nIn the **\"Authorized redirect URIs\"** field, add:\n\n```\nhttps://your-server.com/callback\n```\n\n> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`).\n\n**4. Save and copy the credentials**\n\nAfter creating, Google will show the **Client ID** and **Client Secret**.\n\n**5. Set environment variables**\n\nIn your `.env` (or Docker environment variables):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restart OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Try connecting again**\n\nDashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth\n\nGoogle will now redirect correctly to `https://your-server.com/callback`.\n\n---\n\n#### Temporary workaround (without custom credentials)\n\nIf you don't want to set up your own credentials right now, you can still use the **manual URL flow**:\n\n1. OmniRoute opens the Google authorization URL\n2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server)\n3. **Copy the full URL** from your browser's address bar (even if the page doesn't load)\n4. Paste that URL into the field shown in the OmniRoute connection modal\n5. Click **\"Connect\"**\n\n> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded.\n\n---\n\n
\n๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs\n\n#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos?\n\nOs provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo.\n\nAs credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth\n\nVocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor.\n\n#### Passo a passo\n\n**1. Acesse o Google Cloud Console**\n\nAbra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Crie um novo OAuth 2.0 Client ID**\n\n- Clique em **\"+ Create Credentials\"** โ†’ **\"OAuth client ID\"**\n- Tipo de aplicativo: **\"Web application\"**\n- Nome: escolha qualquer nome (ex: `OmniRoute Remote`)\n\n**3. Adicione as Authorized Redirect URIs**\n\nNo campo **\"Authorized redirect URIs\"**, adicione:\n\n```\nhttps://seu-servidor.com/callback\n```\n\n> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`).\n\n**4. Salve e copie as credenciais**\n\nApรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**.\n\n**5. Configure as variรกveis de ambiente**\n\nNo seu `.env` (ou nas variรกveis de ambiente do Docker):\n\n```bash\n# Para Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n\n# Para Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret\n```\n\n**6. Reinicie o OmniRoute**\n\n```bash\n# Se usando npm:\nnpm run dev\n\n# Se usando Docker:\ndocker restart omniroute\n```\n\n**7. Tente conectar novamente**\n\nDashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth\n\nAgora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก.\n\n---\n\n#### Workaround temporรกrio (sem configurar credenciais prรณprias)\n\nSe nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**:\n\n1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google\n2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto)\n3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue)\n4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute\n5. Clique em **\"Connect\"**\n\n> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.\n\n
\n\n---\n\n
\n\n## ๐Ÿ› ๏ธ Tech Stack\n\n
\nClick to expand tech stack details\n\n- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible)\n- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)\n- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4\n- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)\n- **Schemas**: Zod (MCP tool I/O validation, API contracts)\n- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streaming**: Server-Sent Events (SSE)\n- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization\n- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)\n- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)\n- **Website**: [omniroute.online](https://omniroute.online)\n- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing\n\n
\n\n---\n\n## Dokumentace\n\n| Document | Description |\n| ---------------------------------------------- | --------------------------------------------------- |\n| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |\n| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |\n| [MCP Server](open-sse/mcp-server/README.md) | 16 MCP tools, IDE configs, Python/TS/Go clients |\n| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |\n| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |\n| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |\n| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |\n| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |\n| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |\n| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |\n| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |\n\n---\n\n## ๐Ÿ—บ๏ธ Roadmap\n\nOmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:\n\n| Category | Planned Features | Highlights |\n| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |\n| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |\n| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |\n| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |\n| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |\n| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |\n| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |\n\n### ๐Ÿ”œ Coming Soon\n\n- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE\n- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework\n- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests\n- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata\n- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider\n\n> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)\n\n---\n\n## ๐Ÿ‘ฅ Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Releasing a New Version\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Star History\n\n## Stargazers over time\n\n## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute)\n\n## ๐Ÿ™ Acknowledgments\n\nSpecial thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ€” the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.\n\nSpecial thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port.\n\n---\n\n## Licence\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n
\n Built with โค๏ธ for developers who code 24/7\n
\n omniroute.online\n
\n\n"}, "28123355b43a7d77c584d4655aa6f21ad05d1240": {"t": 1785764457.3647902, "n": 92692, "h": "09f5dc6c4ff08788", "c": "# ๐Ÿš€ OmniRoute โ€” Bezplatnรก brรกna umฤ›lรฉ inteligence\n\n### Nikdy nepล™estรกvejte s kรณdovรกnรญm. Chytrรฉ smฤ›rovรกnรญ k **BEZPLATNรM a levnรฝm modelลฏm AI** s automatickรฝm pล™epรญnรกnรญm mezi zรกloลพnรญmi systรฉmy.\n\n_Vรกลก univerzรกlnรญ API proxy โ€“ jeden endpoint, vรญce neลพ 44 poskytovatelลฏ, nulovรฉ vรฝpadky. Nynรญ s orchestracรญ agentลฏ **MCP a A2A** ._\n\n**Dokonฤenรญ chatu โ€ข Vklรกdรกnรญ โ€ข Generovรกnรญ obrรกzkลฏ โ€ข Video โ€ข Hudba โ€ข Audio โ€ข Zmฤ›na poล™adรญ โ€ข **Vyhledรกvรกnรญ na webu** โ€ข MCP server โ€ข A2A protokol โ€ข 100% TypeScript**\n\n---\n\n
\n
\n

\"verze\"Docker\"Licence\"\"Webovรฉ\"WhatsApp\"

\n

๐ŸŒ Webovรฉ strรกnky โ€ข ๐Ÿš€ Rychlรฝ start โ€ข ๐Ÿ’ก Funkce โ€ข ๐Ÿ“– Dokumentace โ€ข ๐Ÿ’ฐ Cenรญk โ€ข ๐Ÿ’ฌ WhatsApp

\n
\n\n๐ŸŒ **Dostupnรฉ v:** ๐Ÿ‡บ๐Ÿ‡ธ [Angliฤtina](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n### ๐Ÿ†• What's New in v3.0.0\n\n| Area | Change |\n| ------------------------------- | --------------------------------------------------------------------------------- |\n| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| โœ… **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |\n| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| ๐ŸŒ **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| ๐Ÿ”ง **926 Tests** | Full test suite passes with 0 failures |\n\n### ๐Ÿ†• What's New in v3.0.0\n\n| Area | Change |\n| -------------------------- | --------------------------------------------------------------------------------- |\n| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| โœ… **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |\n| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| ๐ŸŒ **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| ๐Ÿ”ง **926 Tests** | Full test suite passes with 0 failures |\n\n---\n\n## ๐Ÿ–ผ๏ธ Hlavnรญ ovlรกdacรญ panel\n\n
\"ล˜รญdicรญ
\n\n---\n\n## ๐Ÿ“ธ Nรกhled ล™รญdicรญho panelu\n\n
\nKliknutรญm zobrazรญte snรญmky obrazovky z ล™รญdicรญho panelu\n
\n\n| Strana | Snรญmek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelรฉ** | ![Poskytovatelรฉ](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdravรญ** | ![Zdravรญ](docs/screenshots/04-health.png) |\n| **Pล™ekladatel** | ![Pล™ekladatel](docs/screenshots/05-translator.png) |\n| **Nastavenรญ** | ![Nastavenรญ](docs/screenshots/06-settings.png) |\n| **Nรกstroje CLI** | ![Nรกstroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly pouลพรญvรกnรญ** | ![Pouลพรญvรกnรญ](docs/screenshots/08-usage.png) |\n| **Koncovรฉ body** | ![Koncovรฉ body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### ๐Ÿค– Bezplatnรฝ poskytovatel umฤ›lรฉ inteligence pro vaลกe oblรญbenรฉ programรกtory\n\n_Pล™ipojte libovolnรฝ nรกstroj IDE nebo CLI s umฤ›lou inteligencรญ pล™es OmniRoute โ€” bezplatnou API brรกnu pro neomezenรฉ kรณdovรกnรญ._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\"OpenClaw\"
OpenClaw
โญ 205 tisรญc 		\"NanoBot\"
NanoBot
โญ 20,9 tisรญc 		\"PicoClaw\"
PicoClaw
โญ 14,6 tisรญc 		\"ZeroClaw\"
ZeroClaw
โญ 9,9 tisรญc 		\"ลฝeleznรฝ
ลฝeleznรฝ drรกp
โญ 2,1 tisรญce
\"OpenCode\"
OpenCode
โญ 106 tisรญc 		\"Codex
Codex CLI
โญ 60,8 tisรญc 		\"Claude
Claude Code
โญ 67,3 tisรญc 		\"Gemini
Gemini CLI
โญ 94,7 tisรญc 		\"Kilo
Kilo kรณd
โญ 15,5 tisรญc
\n\n๐Ÿ“ก Vลกichni agenti se pล™ipojujรญ pล™es http://localhost:20128/v1 nebo http://cloud.omniroute.online/v1 โ€” jedna konfigurace, neomezenรฉ modely a kvรณty\n\n---\n\n## ๐Ÿค” Proฤ OmniRoute?\n\n**Pล™estaลˆte plรฝtvat penฤ›zi a narรกลพet na limity:**\n\n- Kvรณta pล™edplatnรฉho vyprลกรญ kaลพdรฝ mฤ›sรญc\n- Limity rychlosti vรกm zabrรกnรญ v kรณdovรกnรญ\n- Drahรก API (20โ€“50 USD/mฤ›sรญc na poskytovatele)\n- Ruฤnรญ pล™epรญnรกnรญ mezi poskytovateli\n\n**OmniRoute to ล™eลกรญ:**\n\n- โœ… **Maximalizujte pล™edplatnรฉ** โ€“ Sledujte kvรณtu, vyuลพijte kaลพdou ฤรกstku pล™ed resetovรกnรญm\n- โœ… **Automatickรฉ zรกloลพnรญ** โ€“ Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma, ลพรกdnรฉ vรฝpadky\n- โœ… **Vรญce รบฤtลฏ** โ€“ Round-robin mezi รบฤty u jednotlivรฝch poskytovatelลฏ\n- โœ… **Univerzรกlnรญ** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakรฝmkoli nรกstrojem CLI\n\n---\n\n## ๐Ÿ“ง Podpora\n\n> ๐Ÿ’ฌ **Pล™idejte se k naลกรญ komunitฤ›!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Zรญskejte pomoc, sdรญlejte tipy a buฤte v obraze.\n\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problรฉmy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitnรญ skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Pล™ispรญvรกnรญ** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevล™ete ลพรกdost o pล™รญspฤ›vek nebo si vyberte `good first issue`\n- **Pลฏvodnรญ projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Hlรกsรญte chybu?\n\nPล™i otevรญrรกnรญ problรฉmu spusลฅte pล™รญkaz system-info a pล™iloลพte vygenerovanรฝ soubor:\n\n```bash\nnpm run system-info\n```\n\nTรญm se vygeneruje soubor `system-info.txt` s verzรญ Node.js, verzรญ OmniRoute, podrobnostmi o operaฤnรญm systรฉmu, nainstalovanรฝmi nรกstroji CLI (qoder, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systรฉmovรฝmi balรญฤky โ€“ vลกe, co potล™ebujeme k rychlรฉ reprodukci vaลกeho problรฉmu. Soubor pล™iloลพte pล™รญmo k vaลกemu problรฉmu na GitHubu.\n\n---\n\n## ๐Ÿ”„ Jak to funguje\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ Co ล™eลกรญ OmniRoute โ€” 30 skuteฤnรฝch problรฉmลฏ a pล™รญpadลฏ pouลพitรญ\n\n> **Kaลพdรฝ vรฝvojรกล™ pouลพรญvajรญcรญ nรกstroje umฤ›lรฉ inteligence se s tฤ›mito problรฉmy setkรกvรก dennฤ›.** OmniRoute byl vytvoล™en tak, aby je vลกechny vyล™eลกil โ€“ od pล™ekroฤenรญ nรกkladลฏ po regionรกlnรญ bloky, od nefunkฤnรญch tokลฏ OAuth aลพ po operace s protokoly a sledovatelnost v podniku.\n\n
\n๐Ÿ’ธ 1. โ€žPlatรญm si drahรฉ pล™edplatnรฉ, ale stรกle mฤ› ruลกรญ limityโ€œ\n
\n\nVรฝvojรกล™i platรญ za Claude Pro, Codex Pro nebo GitHub Copilot 20โ€“200 dolarลฏ mฤ›sรญฤnฤ›. I pล™i platbฤ› mรก kvรณta strop โ€“ 5 hodin pouลพรญvรกnรญ, tรฝdennรญ limity nebo limity rychlosti za minutu. Uprostล™ed kรณdovacรญ relace poskytovatel pล™estane reagovat a vรฝvojรกล™ ztrรกcรญ plynulost a produktivitu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Inteligentnรญ ฤtyล™รบrovลˆovรก zรกloลพnรญ sluลพba** โ€“ Pokud dojde kvรณta pล™edplatnรฉho, โ€‹โ€‹automaticky se pล™esmฤ›ruje na API klรญฤ โ†’ Levnรฉ โ†’ Zdarma bez manuรกlnรญho zรกsahu\n- **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** โ€“ Zobrazuje spotล™ebu tokenลฏ v reรกlnรฉm ฤase s odpoฤรญtรกvรกnรญm resetovรกnรญ (5 hodin, dennฤ›, tรฝdnฤ›)\n- **Podpora vรญce รบฤtลฏ** โ€“ Vรญce รบฤtลฏ u jednoho poskytovatele s automatickรฝm pล™epรญnรกnรญm โ€“ kdyลพ jeden dojde, pล™epne se na dalลกรญ\n- **Vlastnรญ kombinace** โ€” Pล™izpลฏsobitelnรฉ zรกloลพnรญ ล™etฤ›zce se 6 strategiemi vyvaลพovรกnรญ (fill-first, round robin, P2C, nรกhodnรฉ, nejmรฉnฤ› pouลพรญvanรฉ, nรกkladovฤ› optimalizovanรฉ)\n- **Codex Business Quotas** โ€” Sledovรกnรญ kvรณt pracovnรญho prostoru firmy/tรฝmu pล™รญmo v dashboardu\n\n
\n๐Ÿ”Œ 2. โ€žPotล™ebuji pouลพรญt vรญce poskytovatelลฏ, ale kaลพdรฝ mรก jinรฉ APIโ€œ\n
\n\nOpenAI pouลพรญvรก jeden formรกt, Claude (Anthropic) jinรฝ a Gemini jeลกtฤ› tล™etรญ. Pokud chce vรฝvojรกล™ testovat modely od rลฏznรฝch poskytovatelลฏ nebo mezi nimi pล™echรกzet, musรญ pล™ekonfigurovat SDK, zmฤ›nit koncovรฉ body a vypoล™รกdat se s nekompatibilnรญmi formรกty. Vlastnรญ poskytovatelรฉ (FriendLI, NIM) majรญ nestandardnรญ koncovรฉ body modelลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sjednocenรฝ koncovรฝ bod** โ€” Jeden `http://localhost:20128/v1` slouลพรญ jako proxy pro vลกech 67+ poskytovatelลฏ.\n- **Pล™eklad formรกtu** โ€” Automatickรฝ a transparentnรญ: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Sanitizace odpovฤ›dรญ** โ€” Odstraลˆuje nestandardnรญ pole ( `x_groq` , `usage_breakdown` , `service_tier` ), kterรก poruลกujรญ OpenAI SDK v1.83+\n- **Normalizace rolรญ** โ€” Pล™evรกdรญ `developer` โ†’ `system` pro poskytovatele bez OpenAI; `system` โ†’ `user` pro GLM/ERNIE\n- **Extrakce tagลฏ Think** โ€” Extrahuje bloky `` z modelลฏ, jako je DeepSeek R1, do standardizovanรฉho `reasoning_content`\n- **Strukturovanรฝ vรฝstup pro Gemini** โ€” `json_schema` โ†’ automatickรก konverze `responseMimeType` / `responseSchema`\n- **Vรฝchozรญ hodnota `stream` je `false`** โ€“ Odpovรญdรก specifikaci OpenAI, ฤรญmลพ se zabrรกnรญ neoฤekรกvanรฉmu SSE v Python/Rust/Go SDK.\n\n
\n๐ŸŒ 3. โ€žMลฏj poskytovatel AI blokuje mลฏj region/zemiโ€œ\n
\n\nPoskytovatelรฉ jako OpenAI/Codex blokujรญ pล™รญstup z urฤitรฝch geografickรฝch oblastรญ. Uลพivatelรฉ se bฤ›hem pล™ipojenรญ OAuth a API dostรกvajรญ k chybรกm jako `unsupported_country_region_territory` . To je obzvlรกลกtฤ› frustrujรญcรญ pro vรฝvojรกล™e z rozvojovรฝch zemรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **3รบrovลˆovรก konfigurace proxy** โ€“ Konfigurovatelnรก proxy na 3 รบrovnรญch: globรกlnรญ (veลกkerรฝ provoz), pro jednotlivรฉ poskytovatele (pouze jeden poskytovatel) a pro jednotlivรฉ pล™ipojenรญ/klรญฤ\n- **Barevnฤ› kรณdovanรฉ odznaky proxy** โ€“ Vizuรกlnรญ indikรกtory: ๐ŸŸข globรกlnรญ proxy, ๐ŸŸก proxy poskytovatele, ๐Ÿ”ต proxy pล™ipojenรญ, vลพdy zobrazujรญcรญ IP adresu\n- **Vรฝmฤ›na tokenลฏ OAuth prostล™ednictvรญm proxy** โ€“ tok OAuth takรฉ prochรกzรญ pล™es proxy, ฤรญmลพ se ล™eลกรญ `unsupported_country_region_territory`\n- **Testy pล™ipojenรญ pล™es proxy** โ€“ Testy pล™ipojenรญ pouลพรญvajรญ nakonfigurovanรฝ proxy (jiลพ ลพรกdnรฉ pล™รญmรฉ obchรกzenรญ)\n- **Podpora SOCKS5** โ€” Plnรก podpora proxy SOCKS5 pro odchozรญ smฤ›rovรกnรญ\n- **TLS Fingerprint Spoofing** โ€” Otisk prstu TLS podobnรฝ prohlรญลพeฤi pomocรญ `wreq-js` pro obchรกzenรญ detekce botลฏ\n- **๐Ÿ” Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** โ€” Zmฤ›nรญ poล™adรญ zรกhlavรญ a polรญ v tฤ›le serveru tak, aby odpovรญdala nativnรญm binรกrnรญm podpisลฏm v CLI, ฤรญmลพ drasticky sniลพuje riziko nahlaลกovรกnรญ รบฤtu. IP adresa proxy je zachovรกna โ€” zรญskรกte souฤasnฤ› stealth **i** maskovรกnรญ IP adresy.\n\n
\n๐Ÿ†“ 4. โ€žChci pouลพรญvat umฤ›lou inteligenci pro kรณdovรกnรญ, ale nemรกm penรญzeโ€œ\n
\n\nNe kaลพdรฝ si mลฏลพe dovolit zaplatit 20โ€“200 dolarลฏ mฤ›sรญฤnฤ› za pล™edplatnรฉ AI. Studenti, vรฝvojรกล™i z rozvรญjejรญcรญch se zemรญ, amatรฉล™i a freelanceล™i potล™ebujรญ pล™รญstup ke kvalitnรญm modelลฏm za nulovou cenu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vestavฤ›nรญ poskytovatelรฉ bezplatnรฉ รบrovnฤ›** โ€” Nativnรญ podpora pro 100% bezplatnรฉ poskytovatele: Qoder (5 neomezenรฝch modelลฏ pล™es OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezenรฉ modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisรญc tokenลฏ/mฤ›sรญc zdarma)\n- **Ollama Cloud** โ€” Cloudovฤ› hostovanรฉ modely Ollama na `api.ollama.com` s bezplatnou รบrovnรญ โ€žLight usageโ€œ; pouลพijte prefix `ollamacloud/`\n- **Kombinace pouze zdarma** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = 0 $/mฤ›sรญc s nulovรฝmi prostoji\n- **NVIDIA NIM Free Access** โ€” ~40 RPM developerskรฝ pล™รญstup k vรญce neลพ 70 modelลฏm na build.nvidia.com (pล™echod z kreditลฏ na ฤistรฉ limity rychlosti)\n- **Strategie optimalizace nรกkladลฏ** โ€“ Strategie smฤ›rovรกnรญ, kterรก automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n
\n๐Ÿ”’ 5. โ€žPotล™ebuji chrรกnit svou brรกnu umฤ›lรฉ inteligence pล™ed neoprรกvnฤ›nรฝm pล™รญstupemโ€œ\n
\n\nPล™i zpล™รญstupnฤ›nรญ brรกny umฤ›lรฉ inteligence sรญti (LAN, VPS, Docker) mลฏลพe kdokoli s adresou spotล™ebovat tokeny/kvรณtu vรฝvojรกล™e. Bez ochrany jsou API zranitelnรก vลฏฤi zneuลพitรญ, prompt injection a dalลกรญmu zneuลพitรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sprรกva klรญฤลฏ API** โ€“ generovรกnรญ, rotace a vymezovรกnรญ rozsahu pro kaลพdรฉho poskytovatele s vyhrazenou strรกnkou `/dashboard/api-manager`\n- **Oprรกvnฤ›nรญ na รบrovni modelu** โ€“ Omezenรญ klรญฤลฏ API na konkrรฉtnรญ modely ( `openai/*` , zรกstupnรฉ znaky) pomocรญ pล™epรญnaฤe Povolit vลกe/Omezit\n- **Ochrana koncovรฝch bodลฏ API** โ€“ Vyลพaduje klรญฤ pro `/v1/models` a blokuje konkrรฉtnรญ poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** โ€” Vลกechny trasy dashboardu chrรกnฤ›nรฉ middlewarem `withAuth` + tokeny CSRF\n- **Omezovaฤ rychlosti** โ€” Omezovรกnรญ rychlosti na IP s konfigurovatelnรฝmi okny\n- **Filtrovรกnรญ IP adres** โ€” Seznam povolenรฝch/blokovanรฝch adres pro ล™รญzenรญ pล™รญstupu\n- **Ochrana proti vklรกdรกnรญ vรฝzev** โ€“ Sanitizace proti ลกkodlivรฝm vzorcลฏm vรฝzev\n- **ล ifrovรกnรญ AES-256-GCM** โ€“ pล™ihlaลกovacรญ รบdaje jsou v klidovรฉm stavu ลกifrovรกny\n\n
\n๐Ÿ›‘ 6. โ€žMลฏj poskytovatel selhal a jรก ztratil/a programovacรญ tokโ€œ\n
\n\nPoskytovatelรฉ umฤ›lรฉ inteligence se mohou stรกt nestabilnรญmi, vracet chyby 5xx nebo dosรกhnout doฤasnรฝch limitลฏ rychlosti. Pokud je vรฝvojรกล™ zรกvislรฝ na jedinรฉm poskytovateli, je jeho prรกce pล™eruลกena. Bez jistiฤลฏ mลฏลพe opakovanรฉ pokusy vรฉst k pรกdu aplikace.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Jistiฤ pro kaลพdรฝ model** โ€“ Automatickรฉ otevรญrรกnรญ/zavรญrรกnรญ s konfigurovatelnรฝmi prahovรฝmi hodnotami a dobou ochlazovรกnรญ (Zavล™eno/Otevล™eno/Poloviฤnรญ otevล™enรญ), rozsah definovanรฝ pro kaลพdรฝ model, aby se zabrรกnilo kaskรกdovรกnรญ blokลฏ\n- **Exponenciรกlnรญ odklad** โ€” Progresivnรญ zpoลพdฤ›nรญ opakovรกnรญ\n- **Anti-Thundering Herd** โ€” ochrana Mutex + semafor proti soubฤ›ลพnรฝm bouล™รญm s opakovanรฝmi pokusy\n- **Kombinovanรฉ zรกloลพnรญ ล™etฤ›zce** โ€“ Pokud primรกrnรญ poskytovatel selลพe, automaticky se propadne ล™etฤ›zcem bez zรกsahu.\n- **Kombinovanรฝ jistiฤ** โ€“ Automaticky deaktivuje selhรกvajรญcรญho poskytovatele v rรกmci kombinovanรฉho ล™etฤ›zce\n- **Dashboard stavu** โ€” Monitorovรกnรญ provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti, latence p50/p95/p99\n\n
\n๐Ÿ”ง 7. โ€žKonfigurace kaลพdรฉho nรกstroje umฤ›lรฉ inteligence je zdlouhavรก a opakujรญcรญ seโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Kaลพdรฝ nรกstroj potล™ebuje jinou konfiguraci (API endpoint, klรญฤ, model). Pล™ekonfigurovรกnรญ pล™i zmฤ›nฤ› poskytovatele nebo modelu je ztrรกta ฤasu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel nรกstrojลฏ CLI** โ€” Vyhrazenรก strรกnka s nastavenรญm jednรญm kliknutรญm pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generรกtor konfigurace GitHub Copilot** โ€“ Generuje `chatLanguageModels.json` pro VS Code s hromadnรฝm vรฝbฤ›rem modelu\n- **Prลฏvodce zavรกdฤ›nรญm** โ€“ 4krokovรฉ nastavenรญ pro zaฤรญnajรญcรญ uลพivatele\n- **Jeden koncovรฝ bod, vลกechny modely** โ€“ jednou nakonfigurujte `http://localhost:20128/v1` a zรญskejte pล™รญstup k vรญce neลพ 44 poskytovatelลฏm\n\n
\n๐Ÿ”‘ 8. โ€žSprรกva OAuth tokenลฏ od vรญce poskytovatelลฏ je pekloโ€œ\n
\n\nClaude Code, Codex, Gemini CLI, Copilot โ€“ vลกechny pouลพรญvajรญ OAuth 2.0 s tokeny s vyprลกenรญm platnosti. Vรฝvojรกล™i se musรญ neustรกle znovu autentizovat, ล™eลกit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdรกlenรฝch serverech. Obzvlรกลกtฤ› problematickรฝ je OAuth v LAN/VPS.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Automatickรก aktualizace tokenลฏ** โ€“ Tokeny OAuth se obnovujรญ na pozadรญ pล™ed vyprลกenรญm platnosti.\n- **Vestavฤ›nรฝ OAuth 2.0 (PKCE)** โ€“ Automatickรฝ tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Vรญce รบฤtลฏ na poskytovatele prostล™ednictvรญm extrakce tokenลฏ JWT/ID\n- **OAuth LAN/Remote Fix** โ€” Detekce privรกtnรญ IP adresy pro `redirect_uri` + manuรกlnรญ reลพim URL pro vzdรกlenรฉ servery\n- **OAuth Behind Nginx** โ€” Pouลพรญvรก `window.location.origin` pro kompatibilitu s reverznรญ proxy\n- **Prลฏvodce vzdรกlenรฝm OAuth** โ€“ Podrobnรฝ nรกvod k pล™ihlaลกovacรญm รบdajลฏm Google Cloud na VPS/Dockeru\n\n
\n๐Ÿ“Š 9. โ€žNevรญm, kolik utrรกcรญm ani kdeโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ vรญce placenรฝch poskytovatelลฏ, ale nemajรญ jednotnรฝ pล™ehled o vรฝdajรญch. Kaลพdรฝ poskytovatel mรก svลฏj vlastnรญ fakturaฤnรญ panel, ale neexistuje ลพรกdnรฝ konsolidovanรฝ pล™ehled. Mohou se hromadit neoฤekรกvanรฉ nรกklady.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard pro analรฝzu nรกkladลฏ** โ€“ Sledovรกnรญ nรกkladลฏ na token a sprรกva rozpoฤtu pro kaลพdรฉho poskytovatele\n- **Rozpoฤtovรฉ limity na รบroveลˆ** โ€“ Strop vรฝdajลฏ na รบroveลˆ, kterรฝ spouลกtรญ automatickรฝ zรกloลพnรญ reลพim\n- **Konfigurace cen podle modelu** โ€“ Konfigurovatelnรฉ ceny podle modelu\n- **Statistiky pouลพitรญ pro kaลพdรฝ klรญฤ API** โ€” Poฤet poลพadavkลฏ a ฤasovรฉ razรญtko poslednรญho pouลพitรญ pro kaลพdรฝ klรญฤ\n- **Analytickรฝ panel** โ€“ Statistickรฉ karty, graf vyuลพitรญ modelu, tabulka poskytovatelลฏ s mรญrou รบspฤ›ลกnosti a latencรญ\n\n
\n๐Ÿ› 10. โ€žNedokรกลพu diagnostikovat chyby a problรฉmy ve volรกnรญ umฤ›lรฉ inteligence.โ€œ\n
\n\nKdyลพ volรกnรญ selลพe, vรฝvojรกล™ nevรญ, zda se jednalo o limit rychlosti, vyprลกelรฝ token, ลกpatnรฝ formรกt nebo chybu poskytovatele. Fragmentovanรฉ protokoly napล™รญฤ rลฏznรฝmi terminรกly. Bez sledovatelnosti je ladฤ›nรญ metodou pokus-omyl.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel jednotnรฝch protokolลฏ** โ€“ 4 karty: Protokoly poลพadavkลฏ, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlรญลพeฤ protokolลฏ konzole** โ€” Prohlรญลพeฤ protokolลฏ v reรกlnรฉm ฤase ve stylu terminรกlu s barevnฤ› kรณdovanรฝmi รบrovnฤ›mi, automatickรฝm posouvรกnรญm, vyhledรกvรกnรญm a filtrovรกnรญm\n- **Protokoly proxy SQLite** โ€“ trvalรฉ protokoly, kterรฉ pล™eลพijรญ restart serveru\n- **Pล™ekladaฤskรฉ hล™iลกtฤ›** โ€” 4 reลพimy ladฤ›nรญ: Hล™iลกtฤ› (pล™eklad formรกtu), Tester chatu (okruลพnรญ), Testovacรญ stลฏl (dรกvkovรฝ), ลฝivรฝ monitor (v reรกlnรฉm ฤase)\n- **Telemetrie poลพadavkลฏ** โ€” latence p50/p95/p99 + trasovรกnรญ X-Request-Id\n- **Souborovรฉ protokolovรกnรญ s rotacรญ** โ€“ Konzolovรฝ interceptor zachycuje vลกe do protokolu JSON s rotacรญ na zรกkladฤ› velikosti\n- **Zprรกva o systรฉmovรฝch informacรญch** โ€” pล™รญkaz `npm run system-info` vygeneruje `system-info.txt` s kompletnรญm popisem vaลกeho prostล™edรญ (verze uzlu, verze OmniRoute, operaฤnรญ systรฉm, nรกstroje CLI, stav Dockeru/PM2). Pล™iloลพte jej pล™i hlรกลกenรญ problรฉmลฏ pro okamลพitรฉ tล™รญdฤ›nรญ.\n\n
\n๐Ÿ—๏ธ 11. โ€žNasazenรญ a รบdrลพba brรกny je sloลพitรกโ€œ\n
\n\nInstalace, konfigurace a รบdrลพba AI proxy v rลฏznรฝch prostล™edรญch (lokรกlnรญ, VPS, Docker, cloud) je pracnรก. Problรฉmy, jako jsou pevnฤ› zakรณdovanรฉ cesty, `EACCES` u adresรกล™ลฏ, konflikty portลฏ a multiplatformnรญ sestavenรญ, pล™ispรญvajรญ k obtรญลพรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **npm globรกlnรญ instalace** โ€” `npm install -g omniroute && omniroute` โ€” hotovo\n- **Docker Multi-Platform** โ€” AMD64 + nativnรญ ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** โ€” `base` (bez nรกstrojลฏ CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopovรก aplikace Electron** โ€” Nativnรญ aplikace pro Windows/macOS/Linux se systรฉmovou liลกtou, automatickรฝm spuลกtฤ›nรญm a offline reลพimem\n- **Reลพim rozdฤ›lenรฝch portลฏ** โ€“ API a ล™รญdicรญ panel na samostatnรฝch portech pro pokroฤilรฉ scรฉnรกล™e (reverznรญ proxy, sรญลฅovรกnรญ kontejnerลฏ)\n- **Cloud Sync** โ€“ Konfigurace synchronizace mezi zaล™รญzenรญmi pomocรญ Cloudflare Workers\n- **Zรกlohy databรกzรญ** โ€” Automatickรฉ zรกlohovรกnรญ, obnovenรญ, export a import vลกech nastavenรญ\n\n
\n๐ŸŒ 12. โ€žRozhranรญ je pouze v angliฤtinฤ› a mลฏj tรฝm nemluvรญ anglickyโ€œ\n
\n\nTรฝmy v neanglicky mluvรญcรญch zemรญch, zejmรฉna v Latinskรฉ Americe, Asii a Evropฤ›, se potรฝkajรญ s rozhranรญmi pouze v angliฤtinฤ›. Jazykovรฉ bariรฉry sniลพujรญ mรญru pล™ijetรญ a zvyลกujรญ chyby v konfiguraci.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard i18n โ€” 30 jazykลฏ** โ€” Vลกech 500+ klรกves je pล™eloลพeno vฤetnฤ› arabลกtiny, bulharลกtiny, dรกnลกtiny, nฤ›mฤiny, ลกpanฤ›lลกtiny, finลกtiny, francouzลกtiny, hebrejลกtiny, hindลกtiny, maฤarลกtiny, indonรฉลกtiny, italลกtiny, japonลกtiny, korejลกtiny, malajลกtiny, holandลกtiny, norลกtiny, polลกtiny, portugalลกtiny (PT/BR), rumunลกtiny, ruลกtiny, slovenลกtiny, ลกvรฉdลกtiny, thajลกtiny, ukrajinลกtiny, vietnamลกtiny, ฤรญnลกtiny, filipรญnลกtiny a angliฤtiny\n- **Podpora RTL** โ€“ Podpora psanรญ zprava doleva pro arabลกtinu a hebrejลกtinu\n- **Vรญcejazyฤnรฉ soubory README** โ€” 30 kompletnรญch pล™ekladลฏ dokumentace\n- **Vรฝbฤ›r jazyka** โ€” Ikona glรณbu v zรกhlavรญ pro pล™epรญnรกnรญ v reรกlnรฉm ฤase\n\n
\n๐Ÿ”„ 13. โ€žPotล™ebuji vรญc neลพ jen chat โ€“ potล™ebuji vloลพenรฉ soubory, obrรกzky, zvuk.โ€œ\n
\n\nUmฤ›lรก inteligence nenรญ jen dokonฤovรกnรญ chatu. Vรฝvojรกล™i potล™ebujรญ generovat obrรกzky, pล™episovat zvuk, vytvรกล™et embeddedy pro RAG, mฤ›nit poล™adรญ dokumentลฏ a moderovat obsah. Kaลพdรฉ API mรก jinรฝ koncovรฝ bod a formรกt.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vklรกdรกnรญ** โ€” `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generovรกnรญ obrรกzkลฏ** โ€” `/v1/images/generations` s 10 poskytovateli a vรญce neลพ 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Pล™evod textu na video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Pล™evod textu na hudbu** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Pล™epis zvuku** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Pล™evod textu na ล™eฤ** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a dalลกรญ stรกvajรญcรญ poskytovatelรฉ\n- **Moderovรกnรญ** โ€” `/v1/moderations` โ€” Kontroly bezpeฤnosti obsahu\n- **Zmฤ›na poล™adรญ** โ€” `/v1/rerank` โ€” Zmฤ›na poล™adรญ relevance dokumentu\n- **Responses API** โ€” Plnรก podpora `/v1/responses` pro Codex\n\n
\n๐Ÿงช 14. โ€žNemรกm zpลฏsob, jak testovat a porovnรกvat kvalitu napล™รญฤ modely.โ€œ\n
\n\nVรฝvojรกล™i chtฤ›jรญ vฤ›dฤ›t, kterรฝ model je pro jejich pล™รญpad pouลพitรญ nejlepลกรญ โ€“ kรณd, pล™eklad, uvaลพovรกnรญ โ€“ ale ruฤnรญ porovnรกvรกnรญ je pomalรฉ. Neexistujรญ ลพรกdnรฉ integrovanรฉ nรกstroje pro vyhodnocovรกnรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Hodnocenรญ LLM** โ€” Testovรกnรญ Golden setu s 10 pล™edinstalovanรฝmi pล™รญpady zahrnujรญcรญmi pozdravy, matematiku, geografii, generovรกnรญ kรณdu, dodrลพovรกnรญ JSON, pล™eklad, markdown, odmรญtnutรญ bezpeฤnostnรญch poลพadavkลฏ\n- **4 strategie shody** โ€” `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovacรญ lavice pro pล™ekladatelskรฉ hล™iลกtฤ›** โ€” Dรกvkovรฉ testovรกnรญ s vรญce vstupy a oฤekรกvanรฝmi vรฝstupy, porovnรกnรญ napล™รญฤ poskytovateli\n- **Tester chatu** โ€” Kompletnรญ okruลพnรญ cesta s vizuรกlnรญm vykreslovรกnรญm odpovฤ›dรญ\n- **ลฝivรฝ monitor** โ€” Stream vลกech poลพadavkลฏ prochรกzejรญcรญch proxy serverem v reรกlnรฉm ฤase\n\n
\n๐Ÿ“ˆ 15. โ€žPotล™ebuji ลกkรกlovat bez ztrรกty vรฝkonuโ€œ\n
\n\nS rostoucรญm objemem poลพadavkลฏ generujรญ stejnรฉ otรกzky bez uklรกdรกnรญ do mezipamฤ›ti duplicitnรญ nรกklady. Bez idempotence duplicitnรญ poลพadavky plรฝtvajรญ zpracovรกnรญm. Je nutnรฉ dodrลพovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sรฉmantickรก mezipamฤ›ลฅ** โ€” Dvouvrstvรก mezipamฤ›ลฅ (signatura + sรฉmantika) sniลพuje nรกklady a latenci\n- **Idempotence poลพadavku** โ€” 5s deduplikaฤnรญ okno pro identickรฉ poลพadavky\n- **Detekce limitu rychlosti** โ€“ sledovรกnรญ otรกฤek za minutu (RPM), minimรกlnรญ mezera a maximรกlnรญ soubฤ›ลพnรฉ sledovรกnรญ pro kaลพdรฉho poskytovatele\n- **Upravitelnรฉ limity rychlosti** โ€” Konfigurovatelnรฉ vรฝchozรญ hodnoty v Nastavenรญ โ†’ Odolnost s perzistencรญ\n- **Mezipamฤ›ลฅ pro ovฤ›ล™enรญ klรญฤลฏ API** โ€” tล™รญvrstvรก mezipamฤ›ลฅ pro vรฝkon produkฤnรญho prostล™edรญ\n- **Dashboard s telemetriรญ** โ€“ latence p50/p95/p99, statistiky mezipamฤ›ti, dostupnost\n\n
\n๐Ÿค– 16. โ€žChci mรญt chovรกnรญ modelลฏ globรกlnฤ› pod kontrolouโ€œ\n
\n\nVรฝvojรกล™i, kteล™รญ chtฤ›jรญ vลกechny odpovฤ›di v urฤitรฉm jazyce, se specifickรฝm tรณnem nebo chtฤ›jรญ omezit tokeny pro uvaลพovรกnรญ. Konfigurace tรฉto funkce v kaลพdรฉm nรกstroji/poลพadavku je nepraktickรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vloลพenรญ systรฉmovรฉho prompt** โ€“ Globรกlnรญ prompt aplikovanรฝ na vลกechny poลพadavky\n- **Validace rozpoฤtu Thinking** โ€” ล˜รญzenรญ alokace tokenลฏ na poลพadavek (prลฏchozรญ, automatickรฉ, vlastnรญ, adaptivnรญ)\n- **6 strategiรญ smฤ›rovรกnรญ** โ€“ Globรกlnรญ strategie, kterรฉ urฤujรญ, jak jsou poลพadavky distribuovรกny\n- **Smฤ›rovaฤ se zรกstupnรฝmi znaky** โ€” vzory `provider/*` dynamicky smฤ›rujรญ k libovolnรฉmu poskytovateli\n- **Pล™epรญnรกnรญ povolenรญ/zakรกzรกnรญ kombinacรญ** โ€“ Pล™epรญnรกnรญ kombinacรญ pล™รญmo z ล™รญdicรญho panelu\n- **Pล™epรญnรกnรญ poskytovatele** โ€“ Povolenรญ/zakรกzรกnรญ vลกech pล™ipojenรญ pro poskytovatele jednรญm kliknutรญm\n- **Blokovanรญ poskytovatelรฉ** โ€“ Vylouฤenรญ konkrรฉtnรญch poskytovatelลฏ ze seznamu `/v1/models`\n\n
\n๐Ÿงฐ 17. โ€žPotล™ebuji nรกstroje MCP jako prvotล™รญdnรญ produktovรฉ funkce.โ€œ\n
\n\nMnoho bran umฤ›lรฉ inteligence odhaluje MCP pouze jako skrytรฝ implementaฤnรญ detail. Tรฝmy potล™ebujรญ viditelnou a spravovatelnou operaฤnรญ vrstvu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- MCP se zobrazuje v navigaci na ล™รญdicรญm panelu a na kartฤ› protokolu koncovรฉho bodu.\n- Vyhrazenรก strรกnka pro sprรกvu MCP s procesy, nรกstroji, rozsahy a auditem\n- Vestavฤ›nรฝ rychlรฝ start pro `omniroute --mcp` a onboarding klienta\n\n
\n๐Ÿง  18. โ€žPotล™ebuji orchestraci A2A se synchronizacรญ a cestami รบloh streamu.โ€œ\n
\n\nPracovnรญ postupy agentลฏ vyลพadujรญ jak pล™รญmรฉ odpovฤ›di, tak dlouhodobรฉ streamovanรฉ provรกdฤ›nรญ s kontrolou ลพivotnรญho cyklu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Koncovรฝ bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamovรกnรญ SSE s ลกรญล™enรญm stavu terminรกlu\n- Rozhranรญ API ลพivotnรญho cyklu รบloh pro `tasks/get` a `tasks/cancel`\n\n
\n๐Ÿ›ฐ๏ธ 19. โ€žPotล™ebuji skuteฤnรฝ stav procesu MCP, ne odhadovanรฝ stav.โ€œ\n
\n\nProvoznรญ tรฝmy potล™ebujรญ vฤ›dฤ›t, zda je MCP skuteฤnฤ› aktivnรญ, nejen zda je API dosaลพitelnรฉ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Soubor bฤ›hovรฉho heartbeatu s PID, ฤasovรฝmi razรญtky, transportem, poฤtem nรกstrojลฏ a reลพimem rozsahu\n- API stavu MCP kombinujรญcรญ prezenฤnรญ signรกl a nedรกvnou aktivitu\n- Karty stavu uลพivatelskรฉho rozhranรญ pro zobrazenรญ aktuรกlnosti procesลฏ/provozuschopnosti/prezenฤnรญho signรกlu\n\n
\n๐Ÿ“‹ 20. โ€žPotล™ebuji auditovatelnรฉ provedenรญ nรกstroje MCPโ€œ\n
\n\nKdyลพ nรกstroje mฤ›nรญ konfiguraci nebo spouลกtฤ›jรญ operaฤnรญ akce, tรฝmy potล™ebujรญ forenznรญ sledovatelnost.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Protokolovรกnรญ auditu pro volรกnรญ nรกstrojลฏ MCP s podporou SQLite\n- Filtruje podle nรกstroje, รบspฤ›chu/neรบspฤ›chu, klรญฤe API a strรกnkovรกnรญ\n- Tabulka auditu dashboardu + koncovรฉ body statistik pro automatizaci\n\n
\n๐Ÿ” 21. โ€žPotล™ebuji omezenรก oprรกvnฤ›nรญ MCP pro kaลพdou integraci.โ€œ\n
\n\nRลฏznรญ klienti by mฤ›li mรญt pล™รญstup ke kategoriรญm nรกstrojลฏ s nejniลพลกรญmi oprรกvnฤ›nรญmi.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- 9 detailnรญch MCP sond pro kontrolovanรฝ pล™รญstup k nรกstrojลฏm\n- Vynucenรญ rozsahu a viditelnost v uลพivatelskรฉm rozhranรญ sprรกvy MCP\n- Bezpeฤnรก vรฝchozรญ poloha pro provoznรญ nรกstroje\n\n
\nโš™๏ธ 22. โ€žPotล™ebuji provoznรญ kontroly bez nutnosti pล™esouvรกnรญโ€œ\n
\n\nTรฝmy potล™ebujรญ rychlรฉ zmฤ›ny v bฤ›hovรฉm prostล™edรญ bฤ›hem incidentลฏ nebo nรกkladovรฝch udรกlostรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Pล™epnฤ›te aktivaci komba pล™รญmo z ล™รญdicรญho panelu MCP\n- Pouลพรญvejte profily odolnosti z pล™eddefinovanรฝch balรญฤkลฏ zรกsad\n- Resetujte stav jistiฤe ze stejnรฉho ovlรกdacรญho panelu\n\n
\n๐Ÿ”„ 23. โ€žPotล™ebuji ลพivรฝ pล™ehled o ลพivotnรญm cyklu รบkolลฏ A2A a jejich zruลกenรญ.โ€œ\n
\n\nBez pล™ehledu o ลพivotnรญm cyklu je obtรญลพnรฉ tล™รญdit incidenty รบkolลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Vรฝpis/filtrovรกnรญ รบkolลฏ podle stรกtu/dovednosti s strรกnkovรกnรญm\n- Podrobnรฝ pล™ehled metadat รบloh, udรกlostรญ a artefaktลฏ\n- Koncovรฝ bod zruลกenรญ รบlohy a akce uลพivatelskรฉho rozhranรญ s potvrzenรญm\n\n
\n๐ŸŒŠ 24. โ€žPotล™ebuji metriky aktivnรญho streamu pro A2A zรกtฤ›ลพโ€œ\n
\n\nStreamovacรญ pracovnรญ postupy vyลพadujรญ provoznรญ pล™ehled o soubฤ›ลพnosti a ลพivรฝch pล™ipojenรญch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- ฤŒรญtaฤe aktivnรญch streamลฏ integrovanรฉ do stavu A2A\n- ฤŒasovรฉ razรญtko poslednรญho รบkolu a poฤty pro jednotlivรฉ stavy\n- Karty A2A dashboardu pro monitorovรกnรญ provozu v reรกlnรฉm ฤase\n\n
\n๐Ÿชช 25. โ€žPotล™ebuji standardnรญ vyhledรกvรกnรญ agentลฏ pro klientyโ€œ\n
\n\nExternรญ klienti a orchestratoล™i potล™ebujรญ pro onboarding strojovฤ› ฤitelnรก metadata.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazenรฉ v uลพivatelskรฉm rozhranรญ pro sprรกvu\n- API pro stav A2A zahrnuje metadata pro zjiลกลฅovรกnรญ pro automatizaci\n\n
\n๐Ÿงญ 26. โ€žPotล™ebuji v uลพivatelskรฉm rozhranรญ produktu zjistitelnost protokolu.โ€œ\n
\n\nPokud uลพivatelรฉ nemohou objevit protokolovรฉ povrchy, kvalita pล™ijetรญ a podpory klesรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Strรกnka Konsolidovanรฉ **koncovรฉ body** s kartami pro koncovรฉ body Proxy, MCP, A2A a API\n- Pล™epรญnรกnรญ stavu inline sluลพby (Online/Offline) pro MCP a A2A\n- Odkazy z pล™ehledu na vyhrazenรฉ karty pro sprรกvu\n\n
\n๐Ÿงช 27. โ€žPotล™ebuji komplexnรญ ovฤ›ล™enรญ protokolu se skuteฤnรฝmi klienty.โ€œ\n
\n\nSimulovanรฉ testy nestaฤรญ k ovฤ›ล™enรญ kompatibility protokolu pล™ed vydรกnรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sada E2E, kterรก spouลกtรญ aplikaci a pouลพรญvรก skuteฤnรฝ transport klienta MCP SDK.\n- Klientskรฉ testy A2A pro toky zjiลกลฅovรกnรญ, odesรญlรกnรญ, streamovรกnรญ, naฤรญtรกnรญ a zruลกenรญ\n- Kล™รญลพovรก kontrola tvrzenรญ oproti API pro audit MCP a รบkoly A2A\n\n
\n๐Ÿ“ก 28. โ€žPotล™ebuji jednotnou pozorovatelnost napล™รญฤ vลกemi rozhranรญmiโ€œ\n
\n\nRozdฤ›lenรญ pozorovatelnosti podle protokolu vytvรกล™รญ slepรก mรญsta a delลกรญ MTTR.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรฉ dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie poลพadavkลฏ napล™รญฤ vrstvami OpenAI, MCP a A2A\n- Provoznรญ API pro stav a automatizaci\n\n
\n๐Ÿ’ผ 29. โ€žPotล™ebuji jeden runtime pro proxy + nรกstroje + orchestraci agentลฏโ€œ\n
\n\nSpouลกtฤ›nรญ mnoha samostatnรฝch sluลพeb zvyลกuje provoznรญ nรกklady a poฤet poruch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Proxy, MCP server a A2A server kompatibilnรญ s OpenAI v jednom balรญฤku\n- Sdรญlenรฉ ovฤ›ล™ovรกnรญ, odolnost, รบloลพiลกtฤ› dat a pozorovatelnost\n- Konzistentnรญ model politik napล™รญฤ vลกemi interakฤnรญmi plochami\n\n
\n๐Ÿš€ 30. โ€žPotล™ebuji agentskรฉ pracovnรญ postupy bez slepenรญ kรณdu.โ€œ\n
\n\nTรฝmy ztrรกcejรญ rychlost pล™i spojovรกnรญ vรญce ad-hoc sluลพeb a skriptลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรก strategie koncovรฝch bodลฏ pro klienty a agenty\n- Vestavฤ›nรก uลพivatelskรก rozhranรญ pro sprรกvu protokolลฏ a cesty pro ovฤ›ล™ovรกnรญ kouล™e\n- Zรกklady pล™ipravenรฉ pro produkฤnรญ prostล™edรญ (zabezpeฤenรญ, protokolovรกnรญ, odolnost, zรกlohovรกnรญ)\n\n### Pล™รญklady hernรญch plรกnลฏ (integrovanรฉ pล™รญpady uลพitรญ)\n\n**Pล™รญruฤka A: Maximalizace placenรฉho pล™edplatnรฉho + levnรฉ zรกlohovรกnรญ**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Pล™รญruฤka B: Kรณdovacรญ stack s nulovรฝmi nรกklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Pล™รญruฤka C: Nonstop zรกloลพnรญ ล™etฤ›zec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Pล™รญruฤka D: Operace agentลฏ s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Zaฤnฤ›te zdarma โ€” Nulovรฉ nรกklady na konfiguraci\n\n> Nastavte si kรณdovรกnรญ s umฤ›lou inteligencรญ bฤ›hem nฤ›kolika minut za **0 $/mฤ›sรญc** . Propojte tyto bezplatnรฉ รบฤty a vyuลพijte vestavฤ›nou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelรฉ odemฤeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Pล™ipojenรญ **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€“ **neomezenฤ›** |\n| 2 | Pล™ipojenรญ k **Qoder** (Google OAuth) | kimi-k2-myลกlenรญ, qwen3-coder-plus, deepseek-r1... โ€” **neomezenฤ›** |\n| 3 | Pล™ipojenรญ **Qwen** (kรณd zaล™รญzenรญ) | qwen3-coder-plus, qwen3-coder-flash... โ€” **neomezenฤ›** |\n| 4 | Pล™ipojenรญ **rozhranรญ pล™รญkazovรฉho ล™รกdku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180 000 GBP/mฤ›sรญc zdarma** |\n| 5 | `/dashboard/combos` โ†’ ล ablona **Free Stack (0 $)** | Automatickรฉ zaล™azenรญ vลกech bezplatnรฝch poskytovatelลฏ do routingu |\n\n**V libovolnรฉm IDE/CLI naveฤte:** `http://localhost:20128/v1` ยท Klรญฤ API: `any-string` ยท Hotovo.\n\n> **Volitelnรฉ doplลˆkovรฉ krytรญ (takรฉ zdarma):** Groq API klรญฤ (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelลฏ), Cerebras (1 milion tok/den).\n\n## โšก Rychlรฝ start\n\n### 1) Nainstalujte a spusลฅte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uลพivatelรฉ pnpm:** Po instalaci spusลฅte `pnpm approve-builds -g` , abyste povolili nativnรญ skripty pro sestavenรญ vyลพadovanรฉ programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard se otevรญrรก na `http://localhost:20128` a zรกkladnรญ URL API je `http://localhost:20128/v1` .\n\n| Pล™รญkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuลกtฤ›nรญ serveru ( `PORT=20128` , API a dashboard na stejnรฉm portu) |\n| `omniroute --port 3000` | Nastavte kanonickรฝ/API port na 3000 |\n| `omniroute --mcp` | Spuลกtฤ›nรญ MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevรญrat prohlรญลพeฤ automaticky |\n| `omniroute --help` | Zobrazit nรกpovฤ›du |\n\nVolitelnรฝ reลพim s rozdฤ›lenรฝm portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Pล™ipojte poskytovatele a vytvoล™te si klรญฤ API\n\n1. Otevล™ete Dashboard โ†’ `Providers` a pล™ipojte alespoลˆ jednoho poskytovatele (klรญฤ OAuth nebo API).\n2. Otevล™ete Dashboard โ†’ `Endpoints` a vytvoล™te API klรญฤ.\n3. (Volitelnรฉ) Otevล™ete Dashboard โ†’ `Combos` a nastavte zรกloลพnรญ ล™etฤ›zec.\n\n### 3) Nasmฤ›rujte svลฏj kรณdovacรญ nรกstroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilnรญmi s OpenAI.\n\n### 4) Povolenรญ a ovฤ›ล™enรญ protokolลฏ (v2.0)\n\n**MCP (pro operace ล™รญzenรฉ nรกstroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak pล™ipojte svรฉho MCP klienta pล™es `stdio` a otestujte nรกstroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovnรญ postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ovฤ›ล™te vลกe od zaฤรกtku do konce (doporuฤeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ovฤ›ล™uje skuteฤnรฉ toky klientลฏ MCP a A2A v porovnรกnรญ se spuลกtฤ›nou aplikacรญ.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute je k dispozici jako veล™ejnรฝ obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlรฝ bฤ›h:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostล™edรญ:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Pouลพรญvรกnรญ Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | ล tรญtek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovฤ›jลกรญ stabilnรญ verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuรกlnรญ verze |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktopovรก aplikace โ€“ offline a vลพdy zapnutรก\n\n> ๐Ÿ†• **NOVINKA!** OmniRoute je nynรญ k dispozici jako **nativnรญ desktopovรก aplikace** pro Windows, macOS a Linux.\n\nSpusลฅte OmniRoute jako samostatnou desktopovou aplikaci โ€“ pro lokรกlnรญ modely nenรญ potล™eba ลพรกdnรฝ terminรกl, prohlรญลพeฤ ani internet. Aplikace zaloลพenรก na platformฤ› Electron obsahuje:\n\n- ๐Ÿ–ฅ๏ธ **Nativnรญ okno** โ€” Vyhrazenรฉ okno aplikace s integracรญ do systรฉmovรฉ liลกty\n- ๐Ÿ”„ **Automatickรฉ spuลกtฤ›nรญ** โ€” Spuลกtฤ›nรญ OmniRoute po pล™ihlรกลกenรญ do systรฉmu\n- ๐Ÿ”” **Nativnรญ oznรกmenรญ** โ€“ Zรญskejte upozornฤ›nรญ na vyฤerpรกnรญ kvรณty nebo problรฉmy s poskytovateli\n- โšก **Instalace jednรญm kliknutรญm** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline reลพim** โ€” Funguje plnฤ› offline s pล™iloลพenรฝm serverem\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systรฉmovรฝ zรกsobnรญk\n\nPo minimalizaci se OmniRoute nachรกzรญ v systรฉmovรฉ liลกtฤ› a nabรญzรญ rychlรฉ akce:\n\n- Otevล™รญt ล™รญdicรญ panel\n- Zmฤ›nit port serveru\n- Ukonฤit aplikaci\n\n๐Ÿ“– รšplnรก dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pล™ehled cen\n\n| รšroveลˆ | Poskytovatel | Nรกklady | Obnovenรญ kvรณty | Nejlepลกรญ pro |\n| --------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **๐Ÿ’ณ Pล˜EDPLATNร‰** | Claude Code (profesionรกl) | 20 dolarลฏ mฤ›sรญฤnฤ› | 5 hodin + tรฝdnฤ› | Jiลพ pล™ihlรกลกen/a k odbฤ›ru |\n| Kodex (Plus/Pro) | 20โ€“200 USD/mฤ›sรญc | 5 hodin + tรฝdnฤ› | Uลพivatelรฉ OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisรญc mฤ›sรญฤnฤ› + 1 tisรญc dennฤ› | Kaลพdรฝ! |\n| GitHub Copilot | 10โ€“19 USD/mฤ›sรญc | Mฤ›sรญฤnรญ | Uลพivatelรฉ GitHubu |\n| **๐Ÿ”‘ KLรฤŒ API** | NVIDIA NIM | **ZDARMA** (vรฝvoj navลพdy) | ~40 ot./min | 70+ otevล™enรฝch modelลฏ |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ na svฤ›tฤ› |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisรญc otรกฤek za minutu | Ultrarychlรก lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | ลฝรกdnรฝ | Nejlepลกรญ zdลฏvodnฤ›nรญ ceny a kvality |\n| xAI Grok-4 Rychlรฝ | **0,20/0,50 USD za 1 milion** ๐Ÿ†• | ลฝรกdnรฝ | Nejrychlejลกรญ + volรกnรญ nรกstroje, ultranรญzkรฉ |\n| xAI Grok-4 (standardnรญ) | 0,20/1,50 USD za 1 milion ๐Ÿ†• | ลฝรกdnรฝ | Vlajkovรก loฤ Reasoning od xAI |\n| Mistral | Zkuลกebnรญ verze zdarma + placenรฉ | Omezenรก sazba | Evropskรก umฤ›lรก inteligence |\n| OpenRouter | Platba za pouลพitรญ | ลฝรกdnรฝ | Vรญce neลพ 100 modelลฏ agregovรกno. |\n| **๐Ÿ’ฐ LEVNร‰** | GLM-5 (pล™es Z.AI) ๐Ÿ†• | 0,5 USD/1 milion | Dennฤ› v 10:00 | Vรฝstup 128 tisรญc obrazovรฝch bodลฏ, nejnovฤ›jลกรญ vlajkovรก loฤ |\n| GLM-4.7 | 0,6 USD/1 milion | Dennฤ› v 10:00 | Zรกloha rozpoฤtu |\n| MiniMax M2.5 ๐Ÿ†• | Vstup 0,3 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | รšvaha + agentnรญ รบkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | Nejlevnฤ›jลกรญ varianta |\n| Kimi K2.5 (Moonshot API) ๐Ÿ†• | Platba za pouลพitรญ | ลฝรกdnรฝ | Pล™รญmรฝ pล™รญstup k Moonshot API |\n| Kimi K2 | 9 dolarลฏ mฤ›sรญฤnฤ› bez zรกvazkลฏ | 10 milionลฏ tokenลฏ/mฤ›sรญc | Pล™edvรญdatelnรฉ nรกklady |\n| **๐Ÿ†“ ZDARMA** | Qoder | **0 dolarลฏ** | Neomezenรฝ | 5 modelลฏ neomezenฤ› |\n| Qwen | **0 dolarลฏ** | Neomezenรฝ | 4 modely neomezenฤ› |\n| Kiro | **0 dolarลฏ** | Neomezenรฝ | Claude Sonnet/Haiku (tvorce AWS) |\n\n> ๐Ÿ†• **Pล™idรกny novรฉ modely (bล™ezen 2026):** ล™ada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkovรกno na 1143 ms โ€“ o 30 % rychlejลกรญ neลพ Gemini 2.5 Flash), GLM-5 pล™es Z.AI s vรฝstupem 128K, uvaลพovรกnรญ MiniMax M2.5, aktualizovanรฉ ceny DeepSeek V3.2, Kimi K2.5 pล™es Moonshot Direct API.\n\n**๐Ÿ’ก Kombinovanรฝ balรญk za 0 $ โ€” Kompletnรญ bezplatnรก instalace:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Nulovรฉ nรกklady. Nikdy nepล™estรกvejte s kรณdovรกnรญm.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a vลกechny zรกloลพnรญ reลพimy se provede automaticky โ€“ ลพรกdnรฉ ruฤnรญ pล™epรญnรกnรญ.\n\n---\n\n---\n\n## ๐Ÿ†“ Bezplatnรฉ modely โ€“ Co skuteฤnฤ› zรญskรกte\n\n> Vลกechny nรญลพe uvedenรฉ modely jsou **100% zdarma a nevyลพadujรญ ลพรกdnou kreditnรญ kartu** . OmniRoute mezi nimi automaticky propojรญ trasy, kdyลพ dojde jedna kvรณta โ€“ zkombinujte je vลกechny a zรญskejte tak nerozluฤnou kombinaci za 0 dolarลฏ.\n\n### ๐Ÿ”ต CLAUDE MODELS (pล™es Kiro โ€” AWS Builder ID)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-opus-4.6` | `kr/` | **Neomezenรฝ** | Nejnovฤ›jลกรญ opus od Kira |\n\n### ๐ŸŸข MODELY QODER (Bezplatnรฉ OAuth โ€” bez nutnosti platit kreditnรญ kartou)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-plus` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `deepseek-r1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `minimax-m2.1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `kimi-k2` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n\n### ๐ŸŸก MODELY QWEN (Ovฤ›ล™enรญ kรณdu zaล™รญzenรญ)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-next` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `vision-model` | `qw/` | **Neomezenรฝ** | Multimodรกlnรญ (obrรกzky) |\n\n### ๐ŸŸฃ Rozhranรญ GEMINI CLI (Google OAuth)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisรญc tok/mฤ›sรญc** + 1 tisรญc/den | Mฤ›sรญฤnรญ reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisรญc mฤ›sรญฤnฤ› (sdรญlenรฝ bazรฉn) | Vysokรก kvalita |\n\n### โšซ NVIDIA NIM (Bezplatnรฝ klรญฤ API โ€” build.nvidia.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vรฝvojรกล™) | ลฝรกdnรฝ limit tokenลฏ | **~40 ot./min** | Vรญce neลพ 70 modelลฏ; pล™echod na ฤistรฉ limity sazeb v polovinฤ› roku 2025 |\n\nOblรญbenรฉ bezplatnรฉ modely: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct` , `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Bezplatnรฝ klรญฤ API โ€” inference.cerebras.ai)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenลฏ/den** | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ inference LLM na svฤ›tฤ›; dennฤ› se resetuje |\n\nDostupnรฉ zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Bezplatnรฝ API klรญฤ โ€” console.groq.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisรญc otรกฤek za minutu** | 30 ot./min na model | ลฝรกdnรก kreditnรญ karta; limit 429, neรบฤtovรกno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **๐Ÿ’ก Ultimรกtnรญ bezplatnรฝ zรกsobnรญk:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> โ†’ Qoder (5 models, unlimited)\n> โ†’ Qwen (4 models, unlimited)\n> โ†’ Gemini CLI (180K/mo)\n> โ†’ Cerebras (1M tok/day)\n> โ†’ Groq (14.4K req/day)\n> โ†’ NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a uลพ nikdy nebudete platit za umฤ›lou inteligenci.\n\n## ๐ŸŽ™๏ธ Kombinovanรก transkripce zdarma\n\n> Pล™episujte libovolnรฉ audio/video za **0 $** โ€“ Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako zรกloลพnรญ nรกstroj, Groq Whisper jako neomezenรก nouzovรก zรกloha.\n\n| Poskytovatel | Bezplatnรฉ kredity | Nejlepลกรญ model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| ๐ŸŸข **Deepgram** | **200 dolarลฏ zdarma** (registrace) | `nova-3` โ€” nejvyลกลกรญ pล™esnost, vรญce neลพ 30 jazykลฏ | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ต **AssemblyAI** | **50 dolarลฏ zdarma** (registrace) | `universal-3-pro` โ€” kapitoly, sentiment, osobnรญ รบdaje | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ด **Groq** | **Navลพdy zdarma** | `whisper-large-v3` โ€” OpenAI ล epot | 30 ot./min (omezenรก rychlost) |\n\n**Navrhovanรก kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nPak v `/dashboard/media` โ†’ zรกloลพka **Pล™epis** : nahrajte libovolnรฝ zvukovรฝ nebo video soubor โ†’ vyberte kombinovanรฝ koncovรฝ bod โ†’ zรญskejte pล™epis v podporovanรฝch formรกtech.\n\n## ๐Ÿ’ก Klรญฤovรฉ vlastnosti\n\nOmniRoute v2.0 je navrลพen jako operaฤnรญ platforma, nikoli pouze jako proxy pro relรฉ.\n\n### ๐Ÿค– Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dฤ›lรก |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (16 nรกstrojลฏ)** | Nรกstroje IDE/agent prostล™ednictvรญm 3 transportลฏ: stdio, SSE ( `/api/mcp/sse` ), Streamovatelnรฝ HTTP ( `/api/mcp/stream` ) |\n| ๐Ÿค **A2A server (JSON-RPC + SSE)** | Spouลกtฤ›nรญ รบloh mezi agenty se synchronizacรญ a streamovรกnรญm |\n| ๐Ÿงญ **Konsolidovanรก strรกnka koncovรฝch bodลฏ** | Strรกnka pro sprรกvu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| ๐ŸŽš๏ธ **Pล™epรญnaฤe pro povolenรญ/zakรกzรกnรญ sluลพby** | Pล™epรญnaฤe ZAP/VYP pro MCP a A2A s trvalรฝm nastavenรญm (vรฝchozรญ: VYP) |\n| ๐Ÿ›ฐ๏ธ **Srdeฤnรญ tep za bฤ›hu MCP** | Skuteฤnรฝ stav procesu (pid, doba provozuschopnosti, stรกล™รญ heartbeatu, transport, reลพim rozsahu) |\n| ๐Ÿ“‹ **Auditnรญ zรกznam MCP** | Filtrovatelnรฉ protokoly auditu s hodnocenรญm รบspฤ›chu/neรบspฤ›chu a klรญฤovรฝm pล™iล™azenรญm |\n| ๐Ÿ” **Vynucovรกnรญ rozsahu MCP** | 9 podrobnรฝch oprรกvnฤ›nรญ pro ล™รญzenรฝ pล™รญstup k nรกstrojลฏm |\n| ๐Ÿ“ก **Sprรกva ลพivotnรญho cyklu รบkolลฏ A2A** | Seznam/filtrovรกnรญ รบloh, kontrola udรกlostรญ/artefaktลฏ, zruลกenรญ spuลกtฤ›nรฝch รบloh |\n| ๐Ÿ“‹ **Objevenรญ karty agenta** | `/.well-known/agent.json` pro automatickรฉ vyhledรกvรกnรญ klientลฏ |\n| ๐Ÿงช **Testovacรญ postroj Protocol E2E** | Skuteฤnรฉ MCP SDK + toky klientลฏ A2A v `test:protocols:e2e` |\n| โš™๏ธ **Provoznรญ kontroly** | Kombinace pล™epรญnaฤลฏ, pouลพitรญ profilลฏ odolnosti, resetovรกnรญ jistiฤลฏ z jednoho ovlรกdacรญho panelu |\n\n### ๐Ÿง  Smฤ›rovรกnรญ a inteligence\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| ๐ŸŽฏ **Inteligentnรญ ฤtyล™รบrovลˆovรฝ zรกloลพnรญ systรฉm** | Automatickรก trasa: Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma |\n| ๐Ÿ“Š **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** | Poฤet tokenลฏ v reรกlnรฉm ฤase + odpoฤet resetovรกnรญ pro kaลพdรฉho poskytovatele |\n| ๐Ÿ”„ **Pล™eklad formรกtu** | OpenAI โ†” Claude โ†” Gemini โ†” Odpovฤ›di s konverzemi bezpeฤnรฝmi pro schรฉma |\n| ๐Ÿ‘ฅ **Podpora vรญce รบฤtลฏ** | Vรญce รบฤtลฏ na poskytovatele s inteligentnรญm vรฝbฤ›rem |\n| ๐Ÿ”„ **Automatickรก aktualizace tokenลฏ** | Tokeny OAuth se automaticky obnovujรญ pล™i opakovanรฉm pokusu. |\n| ๐ŸŽจ **Vlastnรญ kombinace** | 6 vyvaลพovacรญch strategiรญ + ล™รญzenรญ zรกloลพnรญho ล™etฤ›zce |\n| ๐ŸŒ **Smฤ›rovaฤ se zรกstupnรฝmi znaky** | dynamickรฉ smฤ›rovรกnรญ `provider/*` |\n| ๐Ÿง  **Pล™emรฝลกlenรญ o rozpoฤtovรฝch kontrolรกch** | Limity pro prลฏchozรญ, automatickรฉ, vlastnรญ a adaptivnรญ uvaลพovรกnรญ |\n| ๐Ÿ”€ **Aliasy modelลฏ** | Vestavฤ›nรฉ + vlastnรญ aliasovรกnรญ modelลฏ a bezpeฤnost migrace |\n| โšก **Degradace pozadรญ** | Smฤ›rujte รบlohy na pozadรญ s nรญzkou prioritou na levnฤ›jลกรญ modely |\n| ๐Ÿงช **Chytrรฉ smฤ›rovรกnรญ s ohledem na รบkoly** | Automatickรฝ vรฝbฤ›r modelu podle typu obsahu (kรณdovรกnรญ/vize/analรฝza/sumarizace) |\n| ๐Ÿ’ฌ **Vstล™ikovรกnรญ do systรฉmu** | Globรกlnรญ kontroly chovรกnรญ uplatลˆovanรฉ konzistentnฤ› |\n| ๐Ÿ“„ **Kompatibilita API pro odpovฤ›di** | Plnรก podpora `/v1/responses` pro Codex a pokroฤilรฉ agentickรฉ pracovnรญ postupy |\n\n### ๐ŸŽต Multimodรกlnรญ API\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Generovรกnรญ obrรกzkลฏ** | `/v1/images/generations` s cloudovรฝm a lokรกlnรญm backendem |\n| ๐Ÿ“ **Vloลพenรญ** | `/v1/embeddings` pro vyhledรกvรกnรญ a RAG pipelines |\n| ๐ŸŽค **Pล™epis zvuku** | `/v1/audio/transcriptions` (Whisper a dalลกรญ poskytovatelรฉ) |\n| ๐Ÿ”Š **Pล™evod textu na ล™eฤ** | `/v1/audio/speech` (vรญce enginลฏ/poskytovatelลฏ) |\n| ๐ŸŽฌ **Generovรกnรญ videa** | `/v1/videos/generations` (pracovnรญ postupy ComfyUI + SD WebUI) |\n| ๐ŸŽต **Hudebnรญ generace** | `/v1/music/generations` (pracovnรญ postupy ComfyUI) |\n| ๐Ÿ›ก๏ธ **Moderovรกnรญ** | Bezpeฤnostnรญ kontroly `/v1/moderations` |\n| ๐Ÿ”€ **Zmฤ›na poล™adรญ** | `/v1/rerank` pro hodnocenรญ relevance |\n| ๐Ÿ” **Vyhledรกvรกnรญ na webu** ๐Ÿ†• | `/v1/search` โ€” 5 poskytovatelลฏ (Serper, Brave, Perplexity, Exa, Tavily), vรญce neลพ 6 500 zdarma/mฤ›sรญc, automatickรฉ pล™epnutรญ na zรกloลพnรญ systรฉm, mezipamฤ›ลฅ |\n\n### ๐Ÿ›ก๏ธ Odolnost, bezpeฤnost a sprรกva vฤ›cรญ veล™ejnรฝch\n\n| Funkce | Co to dฤ›lรก |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Jistiฤe** | Vypnutรญ/obnovenรญ pro kaลพdรฝ model s ovlรกdรกnรญm prahovรฝch hodnot |\n| ๐ŸŽฏ **Modely s ohledem na koncovรฉ body** | Vlastnรญ modely deklarujรญ podporovanรฉ koncovรฉ body + formรกt API |\n| ๐Ÿ›ก๏ธ **Stรกdo proti hromลฏm** | Ochrana mutexu a semaforu pล™i udรกlostech opakovรกnรญ/rychlosti |\n| ๐Ÿง  **Sรฉmantickรก + podpisovรก mezipamฤ›ลฅ** | Snรญลพenรญ nรกkladลฏ/latence dรญky dvฤ›ma vrstvรกm mezipamฤ›ti |\n| โšก **ลฝรกdost o idempotenci** | Okno ochrany proti duplikacรญm |\n| ๐Ÿ”’ **Falลกovรกnรญ otiskลฏ prstลฏ pomocรญ TLS** | Otisk TLS podobnรฝ prohlรญลพeฤi โ€“ **sniลพuje detekci botลฏ a nahlaลกovรกnรญ รบฤtลฏ** |\n| ๐Ÿ” **Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** | Shoduje se s nativnรญmi podpisy poลพadavkลฏ CLI โ€“ **sniลพuje riziko zablokovรกnรญ a zรกroveลˆ zachovรกvรก IP adresu proxy** |\n| ๐ŸŒ **Filtrovรกnรญ IP adres** | Ovlรกdรกnรญ seznamu povolenรฝch/blokovanรฝch poloลพek pro odhalenรก nasazenรญ |\n| ๐Ÿ“Š **Upravitelnรฉ limity rychlosti** | Konfigurovatelnรฉ globรกlnรญ/na รบrovni poskytovatele limity s perzistencรญ |\n| ๐Ÿ”‘ **Sprรกva klรญฤลฏ API a stanovenรญ rozsahu** | Bezpeฤnรฉ vydรกvรกnรญ/rotace klรญฤลฏ a kontroly modelu/poskytovatele |\n| ๐Ÿ›ก๏ธ **Chrรกnฤ›nรฉ `/models`** | Volitelnรฉ ovฤ›ล™ovรกnรญ a skrytรญ poskytovatele pro katalog modelลฏ |\n\n### ๐Ÿ“Š Pozorovatelnost a analytika\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| ๐Ÿ“ **ลฝรกdost + protokolovรกnรญ proxy** | รšplnรฉ protokolovรกnรญ poลพadavkลฏ/odpovฤ›dรญ a proxy |\n| ๐Ÿ“‰ **Streamed Detailed Logs** ๐Ÿ†• | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿ“‹ **Sjednocenรฝ panel protokolลฏ** | Zobrazenรญ poลพadavkลฏ, proxy, auditu a konzole na jednรฉ strรกnce |\n| ๐Ÿ” **Vyลพรกdat si telemetrii** | Latence p50/p95/p99 a trasovรกnรญ poลพadavkลฏ |\n| ๐Ÿฅ **Panel zdravรญ** | Doba provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti |\n| ๐Ÿ’ฐ **Sledovรกnรญ nรกkladลฏ** | Kontrola rozpoฤtu a pล™ehled o cenรกch pro jednotlivรฉ modely |\n| ๐Ÿ“ˆ **Analytickรฉ vizualizace** | Pล™ehledy vyuลพitรญ modelลฏ/poskytovatelลฏ a zobrazenรญ trendลฏ |\n| ๐Ÿงช **Rรกmec hodnocenรญ** | Testovรกnรญ zlatรฉ sady s konfigurovatelnรฝmi strategiemi shody |\n\n### โ˜๏ธ Nasazenรญ a platforma\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| ๐ŸŒ **Nasazenรญ kdekoli** | Localhost, VPS, Docker, cloudovรก prostล™edรญ |\n| ๐Ÿ’พ **Synchronizace s cloudem** | Synchronizace konfigurace pล™es cloud worker |\n| ๐Ÿ”„ **Zรกlohovรกnรญ/Obnovenรญ** | Toky exportu/importu a obnovy po havรกrii |\n| ๐Ÿง™ **Prลฏvodce nรกstupem** | Prลฏvodce prvnรญm spuลกtฤ›nรญm |\n| ๐Ÿ”ง **Panel nรกstrojลฏ CLI** | Nastavenรญ oblรญbenรฝch kรณdovacรญch nรกstrojลฏ jednรญm kliknutรญm |\n| ๐ŸŽฎ **Modelovรฉ hล™iลกtฤ›** | Otestujte libovolnรฉho poskytovatele/model/koncovรฝ bod z ล™รญdicรญho panelu |\n| ๐Ÿ” **Pล™epรญnaฤ otiskลฏ prstลฏ v pล™รญkazovรฉm ล™รกdku** | Porovnรกvรกnรญ otiskลฏ prstลฏ podle poskytovatele v Nastavenรญ > Zabezpeฤenรญ |\n| ๐ŸŒ **i18n (30 jazykลฏ)** | Plnรก jazykovรก podpora dashboardu a dokumentace s psanรญm zprava doleva |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Adresรกล™ vlastnรญch dat** | Pล™epsรกnรญ `DATA_DIR` pro umรญstฤ›nรญ รบloลพiลกtฤ› |\n\n### Hlubokรฝ pohled na funkce\n\n#### Chytrรก zรกloลพnรญ funkce s praktickou kontrolou nรกkladลฏ\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyลพ selลพe kvรณta, rychlost nebo stav, OmniRoute automaticky pล™ejde k dalลกรญmu kandidรกtovi bez nutnosti ruฤnรญho pล™epรญnรกnรญ.\n\n#### Sprรกva protokolลฏ, kterรก je viditelnรก a ovladatelnรก\n\n- MCP + A2A jsou viditelnรฉ v uลพivatelskรฉm rozhranรญ a dokumentaci (nejsou skrytรฉ)\n- API pro stav protokolu zpล™รญstupลˆujรญ ลพivรก provoznรญ data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnujรญ akce pro operace 2. dne (pล™epรญnรกnรญ kombinacรญ, resetovรกnรญ jistiฤลฏ, zruลกenรญ รบkolลฏ)\n\n#### Pracovnรญ postup pล™ekladatele + validace\n\nOblast pล™ekladatele zahrnuje:\n\n- **Hล™iลกtฤ›** : kontroly transformace poลพadavkลฏ\n- **Tester chatu** : kompletnรญ okruลพnรญ cesta poลพadavku/odpovฤ›di\n- **Testovacรญ stolice** : vรญce pล™รญpadลฏ v jednom bฤ›hu\n- **ลฝivรฝ monitor** : zobrazenรญ provozu v reรกlnรฉm ฤase\n\nPlus validace protokolu se skuteฤnรฝmi klienty pomocรญ `npm run test:protocols:e2e` .\n\n> ๐Ÿ“– **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** โ€” Referenฤnรญ informace o nรกstrojรญch, konfigurace IDE a pล™รญklady klientลฏ\n>\n> ๐Ÿ“– **[Soubor README pro A2A Server](src/lib/a2a/README.md)** โ€” Dovednosti, metody JSON-RPC, streamovรกnรญ a ลพivotnรญ cyklus รบloh\n\n## ๐Ÿงช Hodnocenรญ (Evals)\n\nOmniRoute obsahuje vestavฤ›nรฝ hodnotรญcรญ rรกmec pro testovรกnรญ kvality odpovฤ›dรญ LLM v porovnรกnรญ se zlatou sadou. Pล™รญstup k nฤ›mu je moลพnรฝ pล™es **Analรฝzy โ†’ Hodnocenรญ** v dashboardu.\n\n### Vestavฤ›nรก zlatรก sada\n\nPล™edinstalovanรก sada โ€žOmniRoute Golden Setโ€œ obsahuje testovacรญ pล™รญpady pro:\n\n- Zdravรญm, matematika, zemฤ›pis, generovรกnรญ kรณdu\n- Shoda s formรกtem JSON, pล™eklad, generovรกnรญ markdownลฏ\n- Bezpeฤnostnรญ odmรญtnutรญ (ลกkodlivรฝ obsah), poฤรญtรกnรญ, booleovskรก logika\n\n### Strategie hodnocenรญ\n\n| Strategie | Popis | Pล™รญklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Vรฝstup se musรญ pล™esnฤ› shodovat | `\"4\"` |\n| `contains` | Vรฝstup musรญ obsahovat podล™etฤ›zec (bez rozliลกenรญ velkรฝch a malรฝch pรญsmen) | `\"Paris\"` |\n| `regex` | Vรฝstup musรญ odpovรญdat vzoru regulรกrnรญch vรฝrazลฏ | `\"1.*2.*3\"` |\n| `custom` | Vlastnรญ JS funkce vracรญ true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Prลฏvodce nastavenรญm\n\n### Nastavenรญ protokolu (MCP + A2A)\n\n
\n๐Ÿงฉ Nastavenรญ MCP (Model Context Protocol)\n
\n\nSpuลกtฤ›nรญ MCP transportu v reลพimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporuฤenรฝ postup ovฤ›ล™enรญ:\n\n1. Pล™ipojte svรฉho MCP klienta pล™es stdio.\n2. Spusลฅte `omniroute_get_health` .\n3. Spusลฅte `omniroute_list_combos` .\n4. Otevล™ete `/dashboard/mcp` pro ovฤ›ล™enรญ prezenฤnรญho signรกlu, aktivity a auditu.\n\nUลพiteฤnรก API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n๐Ÿค Nastavenรญ A2A (Agent2Agent)\n
\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat รบkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSprรกva ลพivotnรญho cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvoznรญ uลพivatelskรฉ rozhranรญ:\n\n- `/dashboard/a2a` pro pozorovatelnost รบloh/stavลฏ/streamลฏ a akce kouล™enรญ\n\n
\n๐Ÿงช Komplexnรญ validace protokolu\n
\n\nOvฤ›ล™te oba protokoly se skuteฤnรฝmi klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTรญm se ovฤ›ล™uje:\n\n- Pล™ipojenรญ/seznam/volรกnรญ klienta MCP SDK\n- A2A objevovรกnรญ/odesรญlรกnรญ/streamovรกnรญ/zรญskรกvรกnรญ/zruลกenรญ\n- Kล™รญลพovรก kontrola dat v auditu MCP a API pro sprรกvu รบloh A2A\n\n
\n๐Ÿ’ณ Poskytovatelรฉ pล™edplatnรฉho\n
\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionรกly:** Pro sloลพitรฉ รบkoly pouลพรญvejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvรณtu pro kaลพdรฝ model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Sprรกva limitลฏ รบฤtu Codex (5h + tรฝdnฤ›)\n\nKaลพdรฝ รบฤet Codex mรก nynรญ pล™epรญnaฤe zรกsad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinovรฉho prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zรกsadu tรฝdennรญho prahu okna.\n- Prahovรฉ chovรกnรญ: kdyลพ povolenรฉ okno dosรกhne vyuลพitรญ >=90 %, je danรฝ รบฤet pล™eskoฤen.\n- Chovรกnรญ rotace: OmniRoute automaticky pล™esmฤ›ruje na dalลกรญ zpลฏsobilรฝ รบฤet Codex.\n- Chovรกnรญ pล™i resetovรกnรญ: Po `resetAt` urฤitรฉ doby se รบฤet automaticky opฤ›t stane zpลฏsobilรฝm.\n\nScรฉnรกล™e:\n\n- `5h ON` + `Weekly ON` : รบฤet je pล™eskoฤen, kdyลพ kterรฉkoli z oken dosรกhne prahovรฉ hodnoty.\n- `5h OFF` + `Weekly ON` : รบฤet mลฏลพe bรฝt zablokovรกn pouze tรฝdennรญm pouลพรญvรกnรญm.\n- `5h ON` + `Weekly OFF` : รบฤet mลฏลพe bรฝt zablokovรกn pouze pล™i 5hodinovรฉm pouลพรญvรกnรญ.\n- `resetAt` passed: รบฤet se automaticky znovu zapne (bez ruฤnรญho opฤ›tovnรฉho povolenรญ).\n\n### Gemini CLI (ZDARMA 180 000/mฤ›sรญc!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepลกรญ hodnota:** Obrovskรก bezplatnรก รบroveลˆ! Pouลพijte ji pล™ed placenรฝmi รบrovnฤ›mi.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n
\n๐Ÿ”‘ Poskytovatelรฉ klรญฤลฏ API\n
\n\n### NVIDIA NIM (BEZPLATNร pล™รญstup pro vรฝvojรกล™e โ€” vรญce neลพ 70 modelลฏ)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Zรญskejte zdarma klรญฤ API (vฤetnฤ› 1000 inferenฤnรญch kreditลฏ)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ NVIDIA NIM:\n - Klรญฤ API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a vรญce neลพ 50 dalลกรญch\n\n**Tip pro profesionรกly:** API kompatibilnรญ s OpenAI โ€“ funguje bez problรฉmลฏ s pล™ekladem formรกtลฏ OmniRoute!\n\n### Hlubokรฉ vyhledรกvรกnรญ\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatnรก รบroveลˆ!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Zรญskejte klรญฤ API (vฤetnฤ› bezplatnรฉ รบrovnฤ›)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionรกly:** Ultrarychlรก inference โ€“ nejlepลกรญ pro kรณdovรกnรญ v reรกlnรฉm ฤase!\n\n### OpenRouter (100+ modelลฏ)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ OpenRouter\n\n**Modely:** Zรญskejte pล™รญstup k vรญce neลพ 100 modelลฏm od vลกech hlavnรญch poskytovatelลฏ prostล™ednictvรญm jedinรฉho klรญฤe API.\n\n
\n๐Ÿ’ฐ Levnรญ poskytovatelรฉ (zรกloลพnรญ)\n
\n\n### GLM-4.7 (Dennรญ reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Zรญskejte klรญฤ API z kรณdovacรญho plรกnu\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API:\n - Poskytovatel: `glm`\n - Klรญฤ API: `your-key`\n\n**Pouลพitรญ:** `glm/glm-4.7`\n\n**Tip pro profesionรกly:** Programovacรญ plรกn nabรญzรญ 3ร— kvรณtu za cenu 1/7! Obnovuje se dennฤ› v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionรกly:** Nejlevnฤ›jลกรญ varianta pro dlouhรฝ kontext (1 milion tokenลฏ)!\n\n### Kimi K2 (pauลกรกlnรญ poplatek 9 dolarลฏ mฤ›sรญฤnฤ›)\n\n1. Odebรญrat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `kimi/kimi-latest`\n\n**Tip pro profesionรกly:** Fixnรญch 9 $/mฤ›sรญc za 10 milionลฏ tokenลฏ = efektivnรญ nรกklady 0,90 $/1 milion!\n\n
\n๐Ÿ†“ BEZPLATNร poskytovatelรฉ (nouzovรฉ zรกlohovรกnรญ)\n
\n\n### Qoder (5 BEZPLATNรCH modelลฏ pล™es OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kรณdem zaล™รญzenรญ)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n๐ŸŽจ Vytvoล™te kombinace\n
\n\n### Pล™รญklad 1: Maximalizace pล™edplatnรฉho โ†’ Levnรฉ zรกlohovรกnรญ\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Pล™รญklad 2: Pouze zdarma (nulovรฉ nรกklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n๐Ÿ”ง Integrace s rozhranรญm pล™รญkazovรฉho ล™รกdku\n
\n\n### IDE kurzoru\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jednรญm kliknutรญm pouลพijte strรกnku **Nรกstroje CLI** na ล™รญdicรญm panelu nebo ruฤnฤ› upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Moลพnost 1 โ€“ Dashboard (doporuฤeno):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Moลพnost 2 โ€“ Manuรกlnรญ รบprava:** รšprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznรกmka:** OpenClaw funguje pouze s lokรกlnรญm OmniRoute. Mรญsto `localhost` pouลพijte `127.0.0.1` , abyste se vyhnuli problรฉmลฏm s rozliลกenรญm IPv6.\n\n### Cline / Pokraฤovat / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Pล™idรกnรญ OmniRoute jako vlastnรญho poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvoล™te/upravte `opencode.json` v koล™enovรฉm adresรกล™i projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` pล™idejte jakรฝkoli model dostupnรฝ ve vaลกem koncovรฉm bodu OmniRoute `/v1/models` . Pouลพijte formรกt `provider/model-id` z vaลกeho dashboardu OmniRoute.\n\n---\n\n## ๐Ÿ› ล˜eลกenรญ problรฉmลฏ\n\n
\nKliknutรญm rozbalรญte prลฏvodce ล™eลกenรญm problรฉmลฏ\n
\n\n**\"Jazykovรฝ model neposkytoval zprรกvy\"**\n\n- Kvรณta poskytovatele vyฤerpรกna โ†’ Zkontrolujte sledovรกnรญ kvรณt na ล™รญdicรญm panelu\n- ล˜eลกenรญ: Pouลพijte zรกloลพnรญ kombinovanou variantu nebo pล™ejdฤ›te na levnฤ›jลกรญ รบroveลˆ\n\n**Omezenรญ rychlosti**\n\n- Kvรณta pล™edplatnรฉho vyฤerpรกna โ†’ Pล™echod na GLM/MiniMax\n- Pล™idat kombo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vyprลกela**\n\n- Automaticky aktualizovรกno sluลพbou OmniRoute\n- Pokud problรฉmy pล™etrvรกvajรญ: Ovlรกdacรญ panel โ†’ Poskytovatel โ†’ Znovu pล™ipojit\n\n**Vysokรฉ nรกklady**\n\n- Zkontrolujte statistiky vyuลพitรญ v sekci Nรกstฤ›nka โ†’ Nรกklady\n- Pล™epnout primรกrnรญ model na GLM/MiniMax\n- Pro nekritickรฉ รบlohy pouลพijte bezplatnou รบroveลˆ (Gemini CLI, Qoder).\n\n**Porty ล™รญdicรญho panelu/API jsou nesprรกvnรฉ**\n\n- `PORT` je kanonickรฝ zรกkladnรญ port (a standardnฤ› port API)\n- `API_PORT` pล™episuje pouze posluchaฤ API kompatibilnรญ s OpenAI.\n- `DASHBOARD_PORT` pล™episuje pouze posluchaฤ dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaลกi veล™ejnou URL adresu ล™รญdicรญho panelu (pro zpฤ›tnรก volรกnรญ OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ovฤ›ล™te, zda `BASE_URL` odkazuje na vaลกi spuลกtฤ›nou instanci.\n- Ovฤ›ล™te, zda `CLOUD_URL` odkazuje na vรกลก oฤekรกvanรฝ cloudovรฝ koncovรฝ bod.\n- Udrลพujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na stranฤ› serveru.\n\n**Prvnรญ pล™ihlรกลกenรญ nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud nenรญ nastaveno, zรกloลพnรญ heslo je `123456`\n\n**ลฝรกdnรฉ protokoly poลพadavkลฏ**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test pล™ipojenรญ ukazuje โ€žNeplatnรฉโ€œ pro poskytovatele kompatibilnรญ s OpenAI**\n\n- Mnoho poskytovatelลฏ nezpล™รญstupลˆuje koncovรฝ bod `/models`\n- OmniRoute v1.0.6+ zahrnuje zรกloลพnรญ ovฤ›ล™enรญ pomocรญ dokonฤenรญ chatu\n- Zajistฤ›te, aby zรกkladnรญ URL adresa obsahovala pล™รญponu `/v1`\n\n### ๐Ÿ” OAuth na vzdรกlenรฉm serveru\n\n\n\n> **โš ๏ธ Dลฏleลพitรฉ pro uลพivatele, kteล™รญ provozujรญ OmniRoute na VPS, Dockeru nebo jakรฉmkoli vzdรกlenรฉm serveru**\n\n#### Proฤ selhรกvรก OAuth v rozhranรญ CLI Antigravity / Gemini na vzdรกlenรฝch serverech?\n\nPoskytovatelรฉ rozhranรญ CLI **Antigravity** a **Gemini** pouลพรญvajรญ **Google OAuth 2.0** . Google vyลพaduje, aby se `redirect_uri` v toku OAuth pล™esnฤ› shodoval s jednรญm z pล™edregistrovanรฝch URI v konzoli Google Cloud Console aplikace.\n\nPล™ihlaลกovacรญ รบdaje OAuth, kterรฉ jsou souฤรกstรญ OmniRoute, jsou registrovรกny **pouze pro `localhost`** . Kdyลพ pล™istupujete k OmniRoute na vzdรกlenรฉm serveru (napล™. `https://omniroute.myserver.com` ), Google odmรญtne ovฤ›ล™enรญ pomocรญ:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### ล˜eลกenรญ: Nakonfigurujte si vlastnรญ pล™ihlaลกovacรญ รบdaje OAuth\n\nV Google Cloud Console je potล™eba vytvoล™it **ID klienta OAuth 2.0** s URI vaลกeho serveru.\n\n#### Krok za krokem\n\n**1. Otevล™ete konzoli Google Cloud**\n\nPล™ejdฤ›te na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvoล™te novรฉ ID klienta OAuth 2.0**\n\n- Kliknฤ›te na **โ€ž+ Vytvoล™it pล™ihlaลกovacรญ รบdajeโ€œ** โ†’ **โ€žID klienta OAuthโ€œ**\n- Typ aplikace: **โ€žWebovรก aplikaceโ€œ**\n- Nรกzev: cokoli chcete (napล™. `OmniRoute Remote` )\n\n**3. Pล™idejte autorizovanรฉ URI pro pล™esmฤ›rovรกnรญ**\n\nDo pole **โ€žAutorizovanรฉ identifikรกtory URI pro pล™esmฤ›rovรกnรญโ€œ** pล™idejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraฤte `your-server.com` domรฉnou nebo IP adresou vaลกeho serveru (v pล™รญpadฤ› potล™eby uveฤte i port, napล™. `http://45.33.32.156:20128/callback` ).\n\n**4. Uloลพte a zkopรญrujte pล™ihlaลกovacรญ รบdaje**\n\nPo vytvoล™enรญ Google zobrazรญ **ID klienta** a **tajnรฝ kรณd klienta** .\n\n**5. Nastavenรญ promฤ›nnรฝch prostล™edรญ**\n\nVe vaลกem souboru `.env` (nebo promฤ›nnรฝch prostล™edรญ Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu pล™ipojit**\n\nล˜รญdicรญ panel โ†’ Poskytovatelรฉ โ†’ Antigravity (nebo Gemini CLI) โ†’ OAuth\n\nGoogle nynรญ bude sprรกvnฤ› pล™esmฤ›rovรกvat na `https://your-server.com/callback` .\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nPokud si teฤ nechcete nastavovat vlastnรญ pล™ihlaลกovacรญ รบdaje, mลฏลพete stรกle pouลพรญt **ruฤnรญ postup pro URL** :\n\n1. OmniRoute otevรญrรก autorizaฤnรญ URL od Googlu\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru).\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe (i kdyลพ se strรกnka nenaฤte)\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute.\n5. Kliknฤ›te na **โ€žPล™ipojitโ€œ**\n\n> To funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na to, zda se naฤetla pล™esmฤ›rovacรญ strรกnka.\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nChcete-li zรญskat pล™รญstup k pล™ihlaลกovacรญm รบdajลฏm bez vlastnรญ konfigurace, mลฏลพete pouลพรญt nรกsledujรญcรญ postup:\n\n1. OmniRoute otevล™e URL autorizace Google\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru)\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute\n5. Kliknฤ›te na **โ€žPล™ipojit\"**\n\n> Toto ล™eลกenรญ funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na naฤtenรญ pล™esmฤ›rovacรญ strรกnky.\n\n---\n\n## ๐Ÿ› ๏ธ Technologickรฝ stack\n\n
\nKliknutรญm rozbalรญte podrobnosti o technologickรฉm stacku\n
\n\n- **Runtime** : Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ **nenรญ podporovรกn** โ€” nativnรญ binรกrnรญ soubory `better-sqlite3` jsou nekompatibilnรญ)\n- **Jazyk** : TypeScript 5.9 โ€” **100% TypeScript** napล™รญฤ `src/` a `open-sse/` ( `any` v zรกkladnรญch modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databรกze** : LowDB (JSON) + SQLite (stav domรฉny + protokoly proxy + audit MCP + rozhodnutรญ o smฤ›rovรกnรญ)\n- **Schรฉmata** : Zod (validace I/O nรกstrojลฏ MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamovรกnรญ** : Udรกlosti odeslanรฉ serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klรญฤe + autorizace s rozsahem MCP\n- **Testovรกnรญ** : Node.js test runner + Vitest (900+ testลฏ vฤetnฤ› unit, integraฤnรญch, E2E)\n- **CI/CD** : Akce GitHubu (automatickรฉ publikovรกnรญ v npm + Docker Hub pล™i vydรกnรญ)\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **Balรญฤek** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistiฤ, exponenciรกlnรญ odstavenรญ, ochrana proti hromลฏm, faleลกnรฉ TLS, automatickรฉ kombinovanรฉ samoopravovรกnรญ\n\n---\n\n## ๐Ÿ“– Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uลพivatelskรก pล™รญruฤka](docs/USER_GUIDE.md) | Poskytovatelรฉ, kombinace, integrace CLI, nasazenรญ |\n| [Referenฤnรญ informace k API](docs/API_REFERENCE.md) | Vลกechny koncovรฉ body s pล™รญklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nรกstrojลฏ MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamovรกnรญ, sprรกva รบloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorovรฉ bodovรกnรญ, balรญฤky reลพimลฏ, samolรฉฤba |\n| [Odstraลˆovรกnรญ problรฉmลฏ](docs/TROUBLESHOOTING.md) | Bฤ›ลพnรฉ problรฉmy a jejich ล™eลกenรญ |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a internรญ prvky systรฉmu |\n| [Pล™ispรญvรกnรญ](CONTRIBUTING.md) | Nastavenรญ a pokyny pro vรฝvoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpeฤnostnรญ zรกsady](SECURITY.md) | Hlรกลกenรญ zranitelnostรญ a bezpeฤnostnรญ postupy |\n| [Nasazenรญ virtuรกlnรญho poฤรญtaฤe](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletnรญ prลฏvodce: Nastavenรญ virtuรกlnรญho poฤรญtaฤe + nginx + Cloudflare |\n| [Galerie funkcรญ](docs/FEATURES.md) | Vizuรกlnรญ prohlรญdka ล™รญdicรญho panelu se snรญmky obrazovky |\n| [Kontrolnรญ seznam vydรกnรญ](docs/RELEASE_CHECKLIST.md) | Kroky ovฤ›ล™enรญ pล™ed vydรกnรญm |\n\n---\n\n## ๐Ÿ—บ๏ธ Plรกn\n\nOmniRoute mรก **v plรกnu vรญce neลพ 210 funkcรญ** v nฤ›kolika fรกzรญch vรฝvoje. Zde jsou klรญฤovรฉ oblasti:\n\n| Kategorie | Plรกnovanรฉ funkce | Hlavnรญ body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| ๐Ÿง  **Smฤ›rovรกnรญ a inteligence** | 25+ | Smฤ›rovรกnรญ s nejniลพลกรญ latencรญ, smฤ›rovรกnรญ zaloลพenรฉ na tagech, kontrola kvรณt pล™ed vรฝstupem, vรฝbฤ›r รบฤtu P2C |\n| ๐Ÿ”’ **Zabezpeฤenรญ a dodrลพovรกnรญ pล™edpisลฏ** | 20+ | Zpevnฤ›nรญ SSRF, maskovรกnรญ pล™ihlaลกovacรญch รบdajลฏ, limit rychlosti pro kaลพdรฝ koncovรฝ bod, stanovenรญ rozsahu klรญฤลฏ pro sprรกvu |\n| ๐Ÿ“Š **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledovรกnรญ kvรณt v reรกlnรฉm ฤase, sledovรกnรญ nรกkladลฏ podle modelu |\n| ๐Ÿ”„ **Integrace poskytovatelลฏ** | 20+ | Dynamickรฝ registr modelลฏ, doba zchlazenรญ poskytovatelลฏ, Codex pro vรญce รบฤtลฏ, analรฝza kvรณt Copilota |\n| โšก **Vรฝkon** | 15+ | Dvojitรก vrstva mezipamฤ›ti, mezipamฤ›ลฅ vรฝzev, mezipamฤ›ลฅ odpovฤ›dรญ, udrลพovรกnรญ streamovรกnรญ, dรกvkovรฉ API |\n| ๐ŸŒ **Ekosystรฉm** | 10+ | WebSocket API, horkรฉ opฤ›tovnรฉ naฤรญtรกnรญ konfigurace, distribuovanรฉ รบloลพiลกtฤ› konfigurace, komerฤnรญ reลพim |\n\n### ๐Ÿ”œ Jiลพ brzy\n\n- ๐Ÿ”— **Integrace OpenCode** โ€” Nativnรญ podpora poskytovatelลฏ pro IDE kรณdovรกnรญ s AI v OpenCode\n- ๐Ÿ”— **Integrace TRAE** โ€” Plnรก podpora vรฝvojovรฉho rรกmce TRAE pro umฤ›lou inteligenci\n- ๐Ÿ“ฆ **Dรกvkovรฉ API** โ€” Asynchronnรญ dรกvkovรฉ zpracovรกnรญ hromadnรฝch poลพadavkลฏ\n- ๐ŸŽฏ **Smฤ›rovรกnรญ na zรกkladฤ› tagลฏ** โ€” Smฤ›rovรกnรญ poลพadavkลฏ na zรกkladฤ› vlastnรญch tagลฏ a metadat\n- ๐Ÿ’ฐ **Strategie nejniลพลกรญch nรกkladลฏ** โ€“ Automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n> ๐Ÿ“ รšplnรฉ specifikace funkcรญ jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobnรฝch specifikacรญ)\n\n---\n\n## ๐Ÿ‘ฅ Pล™ispฤ›vatelรฉ\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Pล™ispฤ›vatelรฉ](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak pล™ispฤ›t\n\n1. Vytvoล™enรญ forku repozitรกล™e\n2. Vytvoล™te si vlastnรญ vฤ›tev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrฤte zmฤ›ny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do vฤ›tve ( `git push origin feature/amazing-feature` )\n5. Otevล™รญt ลพรกdost o zmฤ›ny (pull request)\n\nPodrobnรฉ pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydรกnรญ novรฉ verze\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Hvฤ›zdnรก historie\n\n## Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## ๐Ÿ™ Podฤ›kovรกnรญ\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** โ€“ pลฏvodnรญmu projektu, kterรฝ inspiroval tento fork. OmniRoute stavรญ na tomto neuvฤ›ล™itelnรฉm zรกkladu s dalลกรญmi funkcemi, multimodรกlnรญmi API a kompletnรญm pล™epsรกnรญm TypeScriptu.\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€“ pลฏvodnรญ implementaci Go, kterรก inspirovala tento JavaScriptovรฝ port.\n\n---\n\n## ๐Ÿ“„ Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n
\n Vytvoล™eno s โค๏ธ pro vรฝvojรกล™e, kteล™รญ programujรญ 24 hodin dennฤ›, 7 dnรญ v tรฝdnu\n
\n

omniroute.online

\n
\n\n"}, "b84e79362ea2195307dc36fff8a4f2dec5b203d0": {"t": 1785764459.1759288, "n": 92692, "h": "80ca04f6e2160f90", "c": "# ๐Ÿš€ OmniRoute โ€” Bezplatnรก brรกna umฤ›lรฉ inteligence\n\n### Nikdy nepล™estรกvejte s kรณdovรกnรญm. Chytrรฉ smฤ›rovรกnรญ k **BEZPLATNรM a levnรฝm modelลฏm AI** s automatickรฝm pล™epรญnรกnรญm mezi zรกloลพnรญmi systรฉmy.\n\n_Vรกลก univerzรกlnรญ API proxy โ€“ jeden endpoint, vรญce neลพ 44 poskytovatelลฏ, nulovรฉ vรฝpadky. Nynรญ s orchestracรญ agentลฏ **MCP a A2A** ._\n\n**Dokonฤenรญ chatu โ€ข Vklรกdรกnรญ โ€ข Generovรกnรญ obrรกzkลฏ โ€ข Video โ€ข Hudba โ€ข Audio โ€ข Zmฤ›na poล™adรญ โ€ข **Vyhledรกvรกnรญ na webu** โ€ข MCP server โ€ข A2A protokol โ€ข 100% TypeScript**\n\n---\n\n
\n
\n

\"verze\"Docker\"Licence\"\"Webovรฉ\"WhatsApp\"

\n

๐ŸŒ Webovรฉ strรกnky โ€ข ๐Ÿš€ Rychlรฝ start โ€ข ๐Ÿ’ก Funkce โ€ข ๐Ÿ“– Dokumentace โ€ข ๐Ÿ’ฐ Cenรญk โ€ข ๐Ÿ’ฌ WhatsApp

\n
\n\n๐ŸŒ **Dostupnรฉ v:** ๐Ÿ‡บ๐Ÿ‡ธ [Angliฤtina](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n### ๐Ÿ†• What's New in v3.0.0\n\n| Area | Change |\n| ------------------------------- | --------------------------------------------------------------------------------- |\n| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| โœ… **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |\n| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |\n| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| ๐ŸŒ **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| ๐Ÿ”ง **926 Tests** | Full test suite passes with 0 failures |\n\n### ๐Ÿ†• What's New in v3.0.0\n\n| Area | Change |\n| -------------------------- | --------------------------------------------------------------------------------- |\n| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| โœ… **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |\n| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| ๐ŸŒ **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| ๐Ÿ”ง **926 Tests** | Full test suite passes with 0 failures |\n\n---\n\n## ๐Ÿ–ผ๏ธ Hlavnรญ ovlรกdacรญ panel\n\n
\"ล˜รญdicรญ
\n\n---\n\n## ๐Ÿ“ธ Nรกhled ล™รญdicรญho panelu\n\n
\nKliknutรญm zobrazรญte snรญmky obrazovky z ล™รญdicรญho panelu\n
\n\n| Strana | Snรญmek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelรฉ** | ![Poskytovatelรฉ](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdravรญ** | ![Zdravรญ](docs/screenshots/04-health.png) |\n| **Pล™ekladatel** | ![Pล™ekladatel](docs/screenshots/05-translator.png) |\n| **Nastavenรญ** | ![Nastavenรญ](docs/screenshots/06-settings.png) |\n| **Nรกstroje CLI** | ![Nรกstroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly pouลพรญvรกnรญ** | ![Pouลพรญvรกnรญ](docs/screenshots/08-usage.png) |\n| **Koncovรฉ body** | ![Koncovรฉ body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### ๐Ÿค– Bezplatnรฝ poskytovatel umฤ›lรฉ inteligence pro vaลกe oblรญbenรฉ programรกtory\n\n_Pล™ipojte libovolnรฝ nรกstroj IDE nebo CLI s umฤ›lou inteligencรญ pล™es OmniRoute โ€” bezplatnou API brรกnu pro neomezenรฉ kรณdovรกnรญ._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\"OpenClaw\"
OpenClaw
โญ 205 tisรญc 		\"NanoBot\"
NanoBot
โญ 20,9 tisรญc 		\"PicoClaw\"
PicoClaw
โญ 14,6 tisรญc 		\"ZeroClaw\"
ZeroClaw
โญ 9,9 tisรญc 		\"ลฝeleznรฝ
ลฝeleznรฝ drรกp
โญ 2,1 tisรญce
\"OpenCode\"
OpenCode
โญ 106 tisรญc 		\"Codex
Codex CLI
โญ 60,8 tisรญc 		\"Claude
Claude Code
โญ 67,3 tisรญc 		\"Gemini
Gemini CLI
โญ 94,7 tisรญc 		\"Kilo
Kilo kรณd
โญ 15,5 tisรญc
\n\n๐Ÿ“ก Vลกichni agenti se pล™ipojujรญ pล™es http://localhost:20128/v1 nebo http://cloud.omniroute.online/v1 โ€” jedna konfigurace, neomezenรฉ modely a kvรณty\n\n---\n\n## ๐Ÿค” Proฤ OmniRoute?\n\n**Pล™estaลˆte plรฝtvat penฤ›zi a narรกลพet na limity:**\n\n- Kvรณta pล™edplatnรฉho vyprลกรญ kaลพdรฝ mฤ›sรญc\n- Limity rychlosti vรกm zabrรกnรญ v kรณdovรกnรญ\n- Drahรก API (20โ€“50 USD/mฤ›sรญc na poskytovatele)\n- Ruฤnรญ pล™epรญnรกnรญ mezi poskytovateli\n\n**OmniRoute to ล™eลกรญ:**\n\n- โœ… **Maximalizujte pล™edplatnรฉ** โ€“ Sledujte kvรณtu, vyuลพijte kaลพdou ฤรกstku pล™ed resetovรกnรญm\n- โœ… **Automatickรฉ zรกloลพnรญ** โ€“ Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma, ลพรกdnรฉ vรฝpadky\n- โœ… **Vรญce รบฤtลฏ** โ€“ Round-robin mezi รบฤty u jednotlivรฝch poskytovatelลฏ\n- โœ… **Univerzรกlnรญ** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakรฝmkoli nรกstrojem CLI\n\n---\n\n## ๐Ÿ“ง Podpora\n\n> ๐Ÿ’ฌ **Pล™idejte se k naลกรญ komunitฤ›!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Zรญskejte pomoc, sdรญlejte tipy a buฤte v obraze.\n\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problรฉmy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitnรญ skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Pล™ispรญvรกnรญ** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevล™ete ลพรกdost o pล™รญspฤ›vek nebo si vyberte `good first issue`\n- **Pลฏvodnรญ projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Hlรกsรญte chybu?\n\nPล™i otevรญrรกnรญ problรฉmu spusลฅte pล™รญkaz system-info a pล™iloลพte vygenerovanรฝ soubor:\n\n```bash\nnpm run system-info\n```\n\nTรญm se vygeneruje soubor `system-info.txt` s verzรญ Node.js, verzรญ OmniRoute, podrobnostmi o operaฤnรญm systรฉmu, nainstalovanรฝmi nรกstroji CLI (iflow, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systรฉmovรฝmi balรญฤky โ€“ vลกe, co potล™ebujeme k rychlรฉ reprodukci vaลกeho problรฉmu. Soubor pล™iloลพte pล™รญmo k vaลกemu problรฉmu na GitHubu.\n\n---\n\n## ๐Ÿ”„ Jak to funguje\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ Co ล™eลกรญ OmniRoute โ€” 30 skuteฤnรฝch problรฉmลฏ a pล™รญpadลฏ pouลพitรญ\n\n> **Kaลพdรฝ vรฝvojรกล™ pouลพรญvajรญcรญ nรกstroje umฤ›lรฉ inteligence se s tฤ›mito problรฉmy setkรกvรก dennฤ›.** OmniRoute byl vytvoล™en tak, aby je vลกechny vyล™eลกil โ€“ od pล™ekroฤenรญ nรกkladลฏ po regionรกlnรญ bloky, od nefunkฤnรญch tokลฏ OAuth aลพ po operace s protokoly a sledovatelnost v podniku.\n\n
\n๐Ÿ’ธ 1. โ€žPlatรญm si drahรฉ pล™edplatnรฉ, ale stรกle mฤ› ruลกรญ limityโ€œ\n
\n\nVรฝvojรกล™i platรญ za Claude Pro, Codex Pro nebo GitHub Copilot 20โ€“200 dolarลฏ mฤ›sรญฤnฤ›. I pล™i platbฤ› mรก kvรณta strop โ€“ 5 hodin pouลพรญvรกnรญ, tรฝdennรญ limity nebo limity rychlosti za minutu. Uprostล™ed kรณdovacรญ relace poskytovatel pล™estane reagovat a vรฝvojรกล™ ztrรกcรญ plynulost a produktivitu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Inteligentnรญ ฤtyล™รบrovลˆovรก zรกloลพnรญ sluลพba** โ€“ Pokud dojde kvรณta pล™edplatnรฉho, โ€‹โ€‹automaticky se pล™esmฤ›ruje na API klรญฤ โ†’ Levnรฉ โ†’ Zdarma bez manuรกlnรญho zรกsahu\n- **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** โ€“ Zobrazuje spotล™ebu tokenลฏ v reรกlnรฉm ฤase s odpoฤรญtรกvรกnรญm resetovรกnรญ (5 hodin, dennฤ›, tรฝdnฤ›)\n- **Podpora vรญce รบฤtลฏ** โ€“ Vรญce รบฤtลฏ u jednoho poskytovatele s automatickรฝm pล™epรญnรกnรญm โ€“ kdyลพ jeden dojde, pล™epne se na dalลกรญ\n- **Vlastnรญ kombinace** โ€” Pล™izpลฏsobitelnรฉ zรกloลพnรญ ล™etฤ›zce se 6 strategiemi vyvaลพovรกnรญ (fill-first, round robin, P2C, nรกhodnรฉ, nejmรฉnฤ› pouลพรญvanรฉ, nรกkladovฤ› optimalizovanรฉ)\n- **Codex Business Quotas** โ€” Sledovรกnรญ kvรณt pracovnรญho prostoru firmy/tรฝmu pล™รญmo v dashboardu\n\n
\n๐Ÿ”Œ 2. โ€žPotล™ebuji pouลพรญt vรญce poskytovatelลฏ, ale kaลพdรฝ mรก jinรฉ APIโ€œ\n
\n\nOpenAI pouลพรญvรก jeden formรกt, Claude (Anthropic) jinรฝ a Gemini jeลกtฤ› tล™etรญ. Pokud chce vรฝvojรกล™ testovat modely od rลฏznรฝch poskytovatelลฏ nebo mezi nimi pล™echรกzet, musรญ pล™ekonfigurovat SDK, zmฤ›nit koncovรฉ body a vypoล™รกdat se s nekompatibilnรญmi formรกty. Vlastnรญ poskytovatelรฉ (FriendLI, NIM) majรญ nestandardnรญ koncovรฉ body modelลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sjednocenรฝ koncovรฝ bod** โ€” Jeden `http://localhost:20128/v1` slouลพรญ jako proxy pro vลกech 67+ poskytovatelลฏ.\n- **Pล™eklad formรกtu** โ€” Automatickรฝ a transparentnรญ: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Sanitizace odpovฤ›dรญ** โ€” Odstraลˆuje nestandardnรญ pole ( `x_groq` , `usage_breakdown` , `service_tier` ), kterรก poruลกujรญ OpenAI SDK v1.83+\n- **Normalizace rolรญ** โ€” Pล™evรกdรญ `developer` โ†’ `system` pro poskytovatele bez OpenAI; `system` โ†’ `user` pro GLM/ERNIE\n- **Extrakce tagลฏ Think** โ€” Extrahuje bloky `` z modelลฏ, jako je DeepSeek R1, do standardizovanรฉho `reasoning_content`\n- **Strukturovanรฝ vรฝstup pro Gemini** โ€” `json_schema` โ†’ automatickรก konverze `responseMimeType` / `responseSchema`\n- **Vรฝchozรญ hodnota `stream` je `false`** โ€“ Odpovรญdรก specifikaci OpenAI, ฤรญmลพ se zabrรกnรญ neoฤekรกvanรฉmu SSE v Python/Rust/Go SDK.\n\n
\n๐ŸŒ 3. โ€žMลฏj poskytovatel AI blokuje mลฏj region/zemiโ€œ\n
\n\nPoskytovatelรฉ jako OpenAI/Codex blokujรญ pล™รญstup z urฤitรฝch geografickรฝch oblastรญ. Uลพivatelรฉ se bฤ›hem pล™ipojenรญ OAuth a API dostรกvajรญ k chybรกm jako `unsupported_country_region_territory` . To je obzvlรกลกtฤ› frustrujรญcรญ pro vรฝvojรกล™e z rozvojovรฝch zemรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **3รบrovลˆovรก konfigurace proxy** โ€“ Konfigurovatelnรก proxy na 3 รบrovnรญch: globรกlnรญ (veลกkerรฝ provoz), pro jednotlivรฉ poskytovatele (pouze jeden poskytovatel) a pro jednotlivรฉ pล™ipojenรญ/klรญฤ\n- **Barevnฤ› kรณdovanรฉ odznaky proxy** โ€“ Vizuรกlnรญ indikรกtory: ๐ŸŸข globรกlnรญ proxy, ๐ŸŸก proxy poskytovatele, ๐Ÿ”ต proxy pล™ipojenรญ, vลพdy zobrazujรญcรญ IP adresu\n- **Vรฝmฤ›na tokenลฏ OAuth prostล™ednictvรญm proxy** โ€“ tok OAuth takรฉ prochรกzรญ pล™es proxy, ฤรญmลพ se ล™eลกรญ `unsupported_country_region_territory`\n- **Testy pล™ipojenรญ pล™es proxy** โ€“ Testy pล™ipojenรญ pouลพรญvajรญ nakonfigurovanรฝ proxy (jiลพ ลพรกdnรฉ pล™รญmรฉ obchรกzenรญ)\n- **Podpora SOCKS5** โ€” Plnรก podpora proxy SOCKS5 pro odchozรญ smฤ›rovรกnรญ\n- **TLS Fingerprint Spoofing** โ€” Otisk prstu TLS podobnรฝ prohlรญลพeฤi pomocรญ `wreq-js` pro obchรกzenรญ detekce botลฏ\n- **๐Ÿ” Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** โ€” Zmฤ›nรญ poล™adรญ zรกhlavรญ a polรญ v tฤ›le serveru tak, aby odpovรญdala nativnรญm binรกrnรญm podpisลฏm v CLI, ฤรญmลพ drasticky sniลพuje riziko nahlaลกovรกnรญ รบฤtu. IP adresa proxy je zachovรกna โ€” zรญskรกte souฤasnฤ› stealth **i** maskovรกnรญ IP adresy.\n\n
\n๐Ÿ†“ 4. โ€žChci pouลพรญvat umฤ›lou inteligenci pro kรณdovรกnรญ, ale nemรกm penรญzeโ€œ\n
\n\nNe kaลพdรฝ si mลฏลพe dovolit zaplatit 20โ€“200 dolarลฏ mฤ›sรญฤnฤ› za pล™edplatnรฉ AI. Studenti, vรฝvojรกล™i z rozvรญjejรญcรญch se zemรญ, amatรฉล™i a freelanceล™i potล™ebujรญ pล™รญstup ke kvalitnรญm modelลฏm za nulovou cenu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vestavฤ›nรญ poskytovatelรฉ bezplatnรฉ รบrovnฤ›** โ€” Nativnรญ podpora pro 100% bezplatnรฉ poskytovatele: iFlow (5 neomezenรฝch modelลฏ pล™es OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezenรฉ modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisรญc tokenลฏ/mฤ›sรญc zdarma)\n- **Ollama Cloud** โ€” Cloudovฤ› hostovanรฉ modely Ollama na `api.ollama.com` s bezplatnou รบrovnรญ โ€žLight usageโ€œ; pouลพijte prefix `ollamacloud/`\n- **Kombinace pouze zdarma** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = 0 $/mฤ›sรญc s nulovรฝmi prostoji\n- **NVIDIA NIM Free Access** โ€” ~40 RPM developerskรฝ pล™รญstup k vรญce neลพ 70 modelลฏm na build.nvidia.com (pล™echod z kreditลฏ na ฤistรฉ limity rychlosti)\n- **Strategie optimalizace nรกkladลฏ** โ€“ Strategie smฤ›rovรกnรญ, kterรก automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n
\n๐Ÿ”’ 5. โ€žPotล™ebuji chrรกnit svou brรกnu umฤ›lรฉ inteligence pล™ed neoprรกvnฤ›nรฝm pล™รญstupemโ€œ\n
\n\nPล™i zpล™รญstupnฤ›nรญ brรกny umฤ›lรฉ inteligence sรญti (LAN, VPS, Docker) mลฏลพe kdokoli s adresou spotล™ebovat tokeny/kvรณtu vรฝvojรกล™e. Bez ochrany jsou API zranitelnรก vลฏฤi zneuลพitรญ, prompt injection a dalลกรญmu zneuลพitรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sprรกva klรญฤลฏ API** โ€“ generovรกnรญ, rotace a vymezovรกnรญ rozsahu pro kaลพdรฉho poskytovatele s vyhrazenou strรกnkou `/dashboard/api-manager`\n- **Oprรกvnฤ›nรญ na รบrovni modelu** โ€“ Omezenรญ klรญฤลฏ API na konkrรฉtnรญ modely ( `openai/*` , zรกstupnรฉ znaky) pomocรญ pล™epรญnaฤe Povolit vลกe/Omezit\n- **Ochrana koncovรฝch bodลฏ API** โ€“ Vyลพaduje klรญฤ pro `/v1/models` a blokuje konkrรฉtnรญ poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** โ€” Vลกechny trasy dashboardu chrรกnฤ›nรฉ middlewarem `withAuth` + tokeny CSRF\n- **Omezovaฤ rychlosti** โ€” Omezovรกnรญ rychlosti na IP s konfigurovatelnรฝmi okny\n- **Filtrovรกnรญ IP adres** โ€” Seznam povolenรฝch/blokovanรฝch adres pro ล™รญzenรญ pล™รญstupu\n- **Ochrana proti vklรกdรกnรญ vรฝzev** โ€“ Sanitizace proti ลกkodlivรฝm vzorcลฏm vรฝzev\n- **ล ifrovรกnรญ AES-256-GCM** โ€“ pล™ihlaลกovacรญ รบdaje jsou v klidovรฉm stavu ลกifrovรกny\n\n
\n๐Ÿ›‘ 6. โ€žMลฏj poskytovatel selhal a jรก ztratil/a programovacรญ tokโ€œ\n
\n\nPoskytovatelรฉ umฤ›lรฉ inteligence se mohou stรกt nestabilnรญmi, vracet chyby 5xx nebo dosรกhnout doฤasnรฝch limitลฏ rychlosti. Pokud je vรฝvojรกล™ zรกvislรฝ na jedinรฉm poskytovateli, je jeho prรกce pล™eruลกena. Bez jistiฤลฏ mลฏลพe opakovanรฉ pokusy vรฉst k pรกdu aplikace.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Jistiฤ pro kaลพdรฝ model** โ€“ Automatickรฉ otevรญrรกnรญ/zavรญrรกnรญ s konfigurovatelnรฝmi prahovรฝmi hodnotami a dobou ochlazovรกnรญ (Zavล™eno/Otevล™eno/Poloviฤnรญ otevล™enรญ), rozsah definovanรฝ pro kaลพdรฝ model, aby se zabrรกnilo kaskรกdovรกnรญ blokลฏ\n- **Exponenciรกlnรญ odklad** โ€” Progresivnรญ zpoลพdฤ›nรญ opakovรกnรญ\n- **Anti-Thundering Herd** โ€” ochrana Mutex + semafor proti soubฤ›ลพnรฝm bouล™รญm s opakovanรฝmi pokusy\n- **Kombinovanรฉ zรกloลพnรญ ล™etฤ›zce** โ€“ Pokud primรกrnรญ poskytovatel selลพe, automaticky se propadne ล™etฤ›zcem bez zรกsahu.\n- **Kombinovanรฝ jistiฤ** โ€“ Automaticky deaktivuje selhรกvajรญcรญho poskytovatele v rรกmci kombinovanรฉho ล™etฤ›zce\n- **Dashboard stavu** โ€” Monitorovรกnรญ provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti, latence p50/p95/p99\n\n
\n๐Ÿ”ง 7. โ€žKonfigurace kaลพdรฉho nรกstroje umฤ›lรฉ inteligence je zdlouhavรก a opakujรญcรญ seโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Kaลพdรฝ nรกstroj potล™ebuje jinou konfiguraci (API endpoint, klรญฤ, model). Pล™ekonfigurovรกnรญ pล™i zmฤ›nฤ› poskytovatele nebo modelu je ztrรกta ฤasu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel nรกstrojลฏ CLI** โ€” Vyhrazenรก strรกnka s nastavenรญm jednรญm kliknutรญm pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generรกtor konfigurace GitHub Copilot** โ€“ Generuje `chatLanguageModels.json` pro VS Code s hromadnรฝm vรฝbฤ›rem modelu\n- **Prลฏvodce zavรกdฤ›nรญm** โ€“ 4krokovรฉ nastavenรญ pro zaฤรญnajรญcรญ uลพivatele\n- **Jeden koncovรฝ bod, vลกechny modely** โ€“ jednou nakonfigurujte `http://localhost:20128/v1` a zรญskejte pล™รญstup k vรญce neลพ 44 poskytovatelลฏm\n\n
\n๐Ÿ”‘ 8. โ€žSprรกva OAuth tokenลฏ od vรญce poskytovatelลฏ je pekloโ€œ\n
\n\nClaude Code, Codex, Gemini CLI, Copilot โ€“ vลกechny pouลพรญvajรญ OAuth 2.0 s tokeny s vyprลกenรญm platnosti. Vรฝvojรกล™i se musรญ neustรกle znovu autentizovat, ล™eลกit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdรกlenรฝch serverech. Obzvlรกลกtฤ› problematickรฝ je OAuth v LAN/VPS.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Automatickรก aktualizace tokenลฏ** โ€“ Tokeny OAuth se obnovujรญ na pozadรญ pล™ed vyprลกenรญm platnosti.\n- **Vestavฤ›nรฝ OAuth 2.0 (PKCE)** โ€“ Automatickรฝ tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow\n- **Multi-Account OAuth** โ€” Vรญce รบฤtลฏ na poskytovatele prostล™ednictvรญm extrakce tokenลฏ JWT/ID\n- **OAuth LAN/Remote Fix** โ€” Detekce privรกtnรญ IP adresy pro `redirect_uri` + manuรกlnรญ reลพim URL pro vzdรกlenรฉ servery\n- **OAuth Behind Nginx** โ€” Pouลพรญvรก `window.location.origin` pro kompatibilitu s reverznรญ proxy\n- **Prลฏvodce vzdรกlenรฝm OAuth** โ€“ Podrobnรฝ nรกvod k pล™ihlaลกovacรญm รบdajลฏm Google Cloud na VPS/Dockeru\n\n
\n๐Ÿ“Š 9. โ€žNevรญm, kolik utrรกcรญm ani kdeโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ vรญce placenรฝch poskytovatelลฏ, ale nemajรญ jednotnรฝ pล™ehled o vรฝdajรญch. Kaลพdรฝ poskytovatel mรก svลฏj vlastnรญ fakturaฤnรญ panel, ale neexistuje ลพรกdnรฝ konsolidovanรฝ pล™ehled. Mohou se hromadit neoฤekรกvanรฉ nรกklady.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard pro analรฝzu nรกkladลฏ** โ€“ Sledovรกnรญ nรกkladลฏ na token a sprรกva rozpoฤtu pro kaลพdรฉho poskytovatele\n- **Rozpoฤtovรฉ limity na รบroveลˆ** โ€“ Strop vรฝdajลฏ na รบroveลˆ, kterรฝ spouลกtรญ automatickรฝ zรกloลพnรญ reลพim\n- **Konfigurace cen podle modelu** โ€“ Konfigurovatelnรฉ ceny podle modelu\n- **Statistiky pouลพitรญ pro kaลพdรฝ klรญฤ API** โ€” Poฤet poลพadavkลฏ a ฤasovรฉ razรญtko poslednรญho pouลพitรญ pro kaลพdรฝ klรญฤ\n- **Analytickรฝ panel** โ€“ Statistickรฉ karty, graf vyuลพitรญ modelu, tabulka poskytovatelลฏ s mรญrou รบspฤ›ลกnosti a latencรญ\n\n
\n๐Ÿ› 10. โ€žNedokรกลพu diagnostikovat chyby a problรฉmy ve volรกnรญ umฤ›lรฉ inteligence.โ€œ\n
\n\nKdyลพ volรกnรญ selลพe, vรฝvojรกล™ nevรญ, zda se jednalo o limit rychlosti, vyprลกelรฝ token, ลกpatnรฝ formรกt nebo chybu poskytovatele. Fragmentovanรฉ protokoly napล™รญฤ rลฏznรฝmi terminรกly. Bez sledovatelnosti je ladฤ›nรญ metodou pokus-omyl.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel jednotnรฝch protokolลฏ** โ€“ 4 karty: Protokoly poลพadavkลฏ, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlรญลพeฤ protokolลฏ konzole** โ€” Prohlรญลพeฤ protokolลฏ v reรกlnรฉm ฤase ve stylu terminรกlu s barevnฤ› kรณdovanรฝmi รบrovnฤ›mi, automatickรฝm posouvรกnรญm, vyhledรกvรกnรญm a filtrovรกnรญm\n- **Protokoly proxy SQLite** โ€“ trvalรฉ protokoly, kterรฉ pล™eลพijรญ restart serveru\n- **Pล™ekladaฤskรฉ hล™iลกtฤ›** โ€” 4 reลพimy ladฤ›nรญ: Hล™iลกtฤ› (pล™eklad formรกtu), Tester chatu (okruลพnรญ), Testovacรญ stลฏl (dรกvkovรฝ), ลฝivรฝ monitor (v reรกlnรฉm ฤase)\n- **Telemetrie poลพadavkลฏ** โ€” latence p50/p95/p99 + trasovรกnรญ X-Request-Id\n- **Souborovรฉ protokolovรกnรญ s rotacรญ** โ€“ Konzolovรฝ interceptor zachycuje vลกe do protokolu JSON s rotacรญ na zรกkladฤ› velikosti\n- **Zprรกva o systรฉmovรฝch informacรญch** โ€” pล™รญkaz `npm run system-info` vygeneruje `system-info.txt` s kompletnรญm popisem vaลกeho prostล™edรญ (verze uzlu, verze OmniRoute, operaฤnรญ systรฉm, nรกstroje CLI, stav Dockeru/PM2). Pล™iloลพte jej pล™i hlรกลกenรญ problรฉmลฏ pro okamลพitรฉ tล™รญdฤ›nรญ.\n\n
\n๐Ÿ—๏ธ 11. โ€žNasazenรญ a รบdrลพba brรกny je sloลพitรกโ€œ\n
\n\nInstalace, konfigurace a รบdrลพba AI proxy v rลฏznรฝch prostล™edรญch (lokรกlnรญ, VPS, Docker, cloud) je pracnรก. Problรฉmy, jako jsou pevnฤ› zakรณdovanรฉ cesty, `EACCES` u adresรกล™ลฏ, konflikty portลฏ a multiplatformnรญ sestavenรญ, pล™ispรญvajรญ k obtรญลพรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **npm globรกlnรญ instalace** โ€” `npm install -g omniroute && omniroute` โ€” hotovo\n- **Docker Multi-Platform** โ€” AMD64 + nativnรญ ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** โ€” `base` (bez nรกstrojลฏ CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopovรก aplikace Electron** โ€” Nativnรญ aplikace pro Windows/macOS/Linux se systรฉmovou liลกtou, automatickรฝm spuลกtฤ›nรญm a offline reลพimem\n- **Reลพim rozdฤ›lenรฝch portลฏ** โ€“ API a ล™รญdicรญ panel na samostatnรฝch portech pro pokroฤilรฉ scรฉnรกล™e (reverznรญ proxy, sรญลฅovรกnรญ kontejnerลฏ)\n- **Cloud Sync** โ€“ Konfigurace synchronizace mezi zaล™รญzenรญmi pomocรญ Cloudflare Workers\n- **Zรกlohy databรกzรญ** โ€” Automatickรฉ zรกlohovรกnรญ, obnovenรญ, export a import vลกech nastavenรญ\n\n
\n๐ŸŒ 12. โ€žRozhranรญ je pouze v angliฤtinฤ› a mลฏj tรฝm nemluvรญ anglickyโ€œ\n
\n\nTรฝmy v neanglicky mluvรญcรญch zemรญch, zejmรฉna v Latinskรฉ Americe, Asii a Evropฤ›, se potรฝkajรญ s rozhranรญmi pouze v angliฤtinฤ›. Jazykovรฉ bariรฉry sniลพujรญ mรญru pล™ijetรญ a zvyลกujรญ chyby v konfiguraci.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard i18n โ€” 30 jazykลฏ** โ€” Vลกech 500+ klรกves je pล™eloลพeno vฤetnฤ› arabลกtiny, bulharลกtiny, dรกnลกtiny, nฤ›mฤiny, ลกpanฤ›lลกtiny, finลกtiny, francouzลกtiny, hebrejลกtiny, hindลกtiny, maฤarลกtiny, indonรฉลกtiny, italลกtiny, japonลกtiny, korejลกtiny, malajลกtiny, holandลกtiny, norลกtiny, polลกtiny, portugalลกtiny (PT/BR), rumunลกtiny, ruลกtiny, slovenลกtiny, ลกvรฉdลกtiny, thajลกtiny, ukrajinลกtiny, vietnamลกtiny, ฤรญnลกtiny, filipรญnลกtiny a angliฤtiny\n- **Podpora RTL** โ€“ Podpora psanรญ zprava doleva pro arabลกtinu a hebrejลกtinu\n- **Vรญcejazyฤnรฉ soubory README** โ€” 30 kompletnรญch pล™ekladลฏ dokumentace\n- **Vรฝbฤ›r jazyka** โ€” Ikona glรณbu v zรกhlavรญ pro pล™epรญnรกnรญ v reรกlnรฉm ฤase\n\n
\n๐Ÿ”„ 13. โ€žPotล™ebuji vรญc neลพ jen chat โ€“ potล™ebuji vloลพenรฉ soubory, obrรกzky, zvuk.โ€œ\n
\n\nUmฤ›lรก inteligence nenรญ jen dokonฤovรกnรญ chatu. Vรฝvojรกล™i potล™ebujรญ generovat obrรกzky, pล™episovat zvuk, vytvรกล™et embeddedy pro RAG, mฤ›nit poล™adรญ dokumentลฏ a moderovat obsah. Kaลพdรฉ API mรก jinรฝ koncovรฝ bod a formรกt.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vklรกdรกnรญ** โ€” `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generovรกnรญ obrรกzkลฏ** โ€” `/v1/images/generations` s 10 poskytovateli a vรญce neลพ 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Pล™evod textu na video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Pล™evod textu na hudbu** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Pล™epis zvuku** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Pล™evod textu na ล™eฤ** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a dalลกรญ stรกvajรญcรญ poskytovatelรฉ\n- **Moderovรกnรญ** โ€” `/v1/moderations` โ€” Kontroly bezpeฤnosti obsahu\n- **Zmฤ›na poล™adรญ** โ€” `/v1/rerank` โ€” Zmฤ›na poล™adรญ relevance dokumentu\n- **Responses API** โ€” Plnรก podpora `/v1/responses` pro Codex\n\n
\n๐Ÿงช 14. โ€žNemรกm zpลฏsob, jak testovat a porovnรกvat kvalitu napล™รญฤ modely.โ€œ\n
\n\nVรฝvojรกล™i chtฤ›jรญ vฤ›dฤ›t, kterรฝ model je pro jejich pล™รญpad pouลพitรญ nejlepลกรญ โ€“ kรณd, pล™eklad, uvaลพovรกnรญ โ€“ ale ruฤnรญ porovnรกvรกnรญ je pomalรฉ. Neexistujรญ ลพรกdnรฉ integrovanรฉ nรกstroje pro vyhodnocovรกnรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Hodnocenรญ LLM** โ€” Testovรกnรญ Golden setu s 10 pล™edinstalovanรฝmi pล™รญpady zahrnujรญcรญmi pozdravy, matematiku, geografii, generovรกnรญ kรณdu, dodrลพovรกnรญ JSON, pล™eklad, markdown, odmรญtnutรญ bezpeฤnostnรญch poลพadavkลฏ\n- **4 strategie shody** โ€” `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovacรญ lavice pro pล™ekladatelskรฉ hล™iลกtฤ›** โ€” Dรกvkovรฉ testovรกnรญ s vรญce vstupy a oฤekรกvanรฝmi vรฝstupy, porovnรกnรญ napล™รญฤ poskytovateli\n- **Tester chatu** โ€” Kompletnรญ okruลพnรญ cesta s vizuรกlnรญm vykreslovรกnรญm odpovฤ›dรญ\n- **ลฝivรฝ monitor** โ€” Stream vลกech poลพadavkลฏ prochรกzejรญcรญch proxy serverem v reรกlnรฉm ฤase\n\n
\n๐Ÿ“ˆ 15. โ€žPotล™ebuji ลกkรกlovat bez ztrรกty vรฝkonuโ€œ\n
\n\nS rostoucรญm objemem poลพadavkลฏ generujรญ stejnรฉ otรกzky bez uklรกdรกnรญ do mezipamฤ›ti duplicitnรญ nรกklady. Bez idempotence duplicitnรญ poลพadavky plรฝtvajรญ zpracovรกnรญm. Je nutnรฉ dodrลพovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sรฉmantickรก mezipamฤ›ลฅ** โ€” Dvouvrstvรก mezipamฤ›ลฅ (signatura + sรฉmantika) sniลพuje nรกklady a latenci\n- **Idempotence poลพadavku** โ€” 5s deduplikaฤnรญ okno pro identickรฉ poลพadavky\n- **Detekce limitu rychlosti** โ€“ sledovรกnรญ otรกฤek za minutu (RPM), minimรกlnรญ mezera a maximรกlnรญ soubฤ›ลพnรฉ sledovรกnรญ pro kaลพdรฉho poskytovatele\n- **Upravitelnรฉ limity rychlosti** โ€” Konfigurovatelnรฉ vรฝchozรญ hodnoty v Nastavenรญ โ†’ Odolnost s perzistencรญ\n- **Mezipamฤ›ลฅ pro ovฤ›ล™enรญ klรญฤลฏ API** โ€” tล™รญvrstvรก mezipamฤ›ลฅ pro vรฝkon produkฤnรญho prostล™edรญ\n- **Dashboard s telemetriรญ** โ€“ latence p50/p95/p99, statistiky mezipamฤ›ti, dostupnost\n\n
\n๐Ÿค– 16. โ€žChci mรญt chovรกnรญ modelลฏ globรกlnฤ› pod kontrolouโ€œ\n
\n\nVรฝvojรกล™i, kteล™รญ chtฤ›jรญ vลกechny odpovฤ›di v urฤitรฉm jazyce, se specifickรฝm tรณnem nebo chtฤ›jรญ omezit tokeny pro uvaลพovรกnรญ. Konfigurace tรฉto funkce v kaลพdรฉm nรกstroji/poลพadavku je nepraktickรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vloลพenรญ systรฉmovรฉho prompt** โ€“ Globรกlnรญ prompt aplikovanรฝ na vลกechny poลพadavky\n- **Validace rozpoฤtu Thinking** โ€” ล˜รญzenรญ alokace tokenลฏ na poลพadavek (prลฏchozรญ, automatickรฉ, vlastnรญ, adaptivnรญ)\n- **6 strategiรญ smฤ›rovรกnรญ** โ€“ Globรกlnรญ strategie, kterรฉ urฤujรญ, jak jsou poลพadavky distribuovรกny\n- **Smฤ›rovaฤ se zรกstupnรฝmi znaky** โ€” vzory `provider/*` dynamicky smฤ›rujรญ k libovolnรฉmu poskytovateli\n- **Pล™epรญnรกnรญ povolenรญ/zakรกzรกnรญ kombinacรญ** โ€“ Pล™epรญnรกnรญ kombinacรญ pล™รญmo z ล™รญdicรญho panelu\n- **Pล™epรญnรกnรญ poskytovatele** โ€“ Povolenรญ/zakรกzรกnรญ vลกech pล™ipojenรญ pro poskytovatele jednรญm kliknutรญm\n- **Blokovanรญ poskytovatelรฉ** โ€“ Vylouฤenรญ konkrรฉtnรญch poskytovatelลฏ ze seznamu `/v1/models`\n\n
\n๐Ÿงฐ 17. โ€žPotล™ebuji nรกstroje MCP jako prvotล™รญdnรญ produktovรฉ funkce.โ€œ\n
\n\nMnoho bran umฤ›lรฉ inteligence odhaluje MCP pouze jako skrytรฝ implementaฤnรญ detail. Tรฝmy potล™ebujรญ viditelnou a spravovatelnou operaฤnรญ vrstvu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- MCP se zobrazuje v navigaci na ล™รญdicรญm panelu a na kartฤ› protokolu koncovรฉho bodu.\n- Vyhrazenรก strรกnka pro sprรกvu MCP s procesy, nรกstroji, rozsahy a auditem\n- Vestavฤ›nรฝ rychlรฝ start pro `omniroute --mcp` a onboarding klienta\n\n
\n๐Ÿง  18. โ€žPotล™ebuji orchestraci A2A se synchronizacรญ a cestami รบloh streamu.โ€œ\n
\n\nPracovnรญ postupy agentลฏ vyลพadujรญ jak pล™รญmรฉ odpovฤ›di, tak dlouhodobรฉ streamovanรฉ provรกdฤ›nรญ s kontrolou ลพivotnรญho cyklu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Koncovรฝ bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamovรกnรญ SSE s ลกรญล™enรญm stavu terminรกlu\n- Rozhranรญ API ลพivotnรญho cyklu รบloh pro `tasks/get` a `tasks/cancel`\n\n
\n๐Ÿ›ฐ๏ธ 19. โ€žPotล™ebuji skuteฤnรฝ stav procesu MCP, ne odhadovanรฝ stav.โ€œ\n
\n\nProvoznรญ tรฝmy potล™ebujรญ vฤ›dฤ›t, zda je MCP skuteฤnฤ› aktivnรญ, nejen zda je API dosaลพitelnรฉ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Soubor bฤ›hovรฉho heartbeatu s PID, ฤasovรฝmi razรญtky, transportem, poฤtem nรกstrojลฏ a reลพimem rozsahu\n- API stavu MCP kombinujรญcรญ prezenฤnรญ signรกl a nedรกvnou aktivitu\n- Karty stavu uลพivatelskรฉho rozhranรญ pro zobrazenรญ aktuรกlnosti procesลฏ/provozuschopnosti/prezenฤnรญho signรกlu\n\n
\n๐Ÿ“‹ 20. โ€žPotล™ebuji auditovatelnรฉ provedenรญ nรกstroje MCPโ€œ\n
\n\nKdyลพ nรกstroje mฤ›nรญ konfiguraci nebo spouลกtฤ›jรญ operaฤnรญ akce, tรฝmy potล™ebujรญ forenznรญ sledovatelnost.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Protokolovรกnรญ auditu pro volรกnรญ nรกstrojลฏ MCP s podporou SQLite\n- Filtruje podle nรกstroje, รบspฤ›chu/neรบspฤ›chu, klรญฤe API a strรกnkovรกnรญ\n- Tabulka auditu dashboardu + koncovรฉ body statistik pro automatizaci\n\n
\n๐Ÿ” 21. โ€žPotล™ebuji omezenรก oprรกvnฤ›nรญ MCP pro kaลพdou integraci.โ€œ\n
\n\nRลฏznรญ klienti by mฤ›li mรญt pล™รญstup ke kategoriรญm nรกstrojลฏ s nejniลพลกรญmi oprรกvnฤ›nรญmi.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- 9 detailnรญch MCP sond pro kontrolovanรฝ pล™รญstup k nรกstrojลฏm\n- Vynucenรญ rozsahu a viditelnost v uลพivatelskรฉm rozhranรญ sprรกvy MCP\n- Bezpeฤnรก vรฝchozรญ poloha pro provoznรญ nรกstroje\n\n
\nโš™๏ธ 22. โ€žPotล™ebuji provoznรญ kontroly bez nutnosti pล™esouvรกnรญโ€œ\n
\n\nTรฝmy potล™ebujรญ rychlรฉ zmฤ›ny v bฤ›hovรฉm prostล™edรญ bฤ›hem incidentลฏ nebo nรกkladovรฝch udรกlostรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Pล™epnฤ›te aktivaci komba pล™รญmo z ล™รญdicรญho panelu MCP\n- Pouลพรญvejte profily odolnosti z pล™eddefinovanรฝch balรญฤkลฏ zรกsad\n- Resetujte stav jistiฤe ze stejnรฉho ovlรกdacรญho panelu\n\n
\n๐Ÿ”„ 23. โ€žPotล™ebuji ลพivรฝ pล™ehled o ลพivotnรญm cyklu รบkolลฏ A2A a jejich zruลกenรญ.โ€œ\n
\n\nBez pล™ehledu o ลพivotnรญm cyklu je obtรญลพnรฉ tล™รญdit incidenty รบkolลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Vรฝpis/filtrovรกnรญ รบkolลฏ podle stรกtu/dovednosti s strรกnkovรกnรญm\n- Podrobnรฝ pล™ehled metadat รบloh, udรกlostรญ a artefaktลฏ\n- Koncovรฝ bod zruลกenรญ รบlohy a akce uลพivatelskรฉho rozhranรญ s potvrzenรญm\n\n
\n๐ŸŒŠ 24. โ€žPotล™ebuji metriky aktivnรญho streamu pro A2A zรกtฤ›ลพโ€œ\n
\n\nStreamovacรญ pracovnรญ postupy vyลพadujรญ provoznรญ pล™ehled o soubฤ›ลพnosti a ลพivรฝch pล™ipojenรญch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- ฤŒรญtaฤe aktivnรญch streamลฏ integrovanรฉ do stavu A2A\n- ฤŒasovรฉ razรญtko poslednรญho รบkolu a poฤty pro jednotlivรฉ stavy\n- Karty A2A dashboardu pro monitorovรกnรญ provozu v reรกlnรฉm ฤase\n\n
\n๐Ÿชช 25. โ€žPotล™ebuji standardnรญ vyhledรกvรกnรญ agentลฏ pro klientyโ€œ\n
\n\nExternรญ klienti a orchestratoล™i potล™ebujรญ pro onboarding strojovฤ› ฤitelnรก metadata.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazenรฉ v uลพivatelskรฉm rozhranรญ pro sprรกvu\n- API pro stav A2A zahrnuje metadata pro zjiลกลฅovรกnรญ pro automatizaci\n\n
\n๐Ÿงญ 26. โ€žPotล™ebuji v uลพivatelskรฉm rozhranรญ produktu zjistitelnost protokolu.โ€œ\n
\n\nPokud uลพivatelรฉ nemohou objevit protokolovรฉ povrchy, kvalita pล™ijetรญ a podpory klesรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Strรกnka Konsolidovanรฉ **koncovรฉ body** s kartami pro koncovรฉ body Proxy, MCP, A2A a API\n- Pล™epรญnรกnรญ stavu inline sluลพby (Online/Offline) pro MCP a A2A\n- Odkazy z pล™ehledu na vyhrazenรฉ karty pro sprรกvu\n\n
\n๐Ÿงช 27. โ€žPotล™ebuji komplexnรญ ovฤ›ล™enรญ protokolu se skuteฤnรฝmi klienty.โ€œ\n
\n\nSimulovanรฉ testy nestaฤรญ k ovฤ›ล™enรญ kompatibility protokolu pล™ed vydรกnรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sada E2E, kterรก spouลกtรญ aplikaci a pouลพรญvรก skuteฤnรฝ transport klienta MCP SDK.\n- Klientskรฉ testy A2A pro toky zjiลกลฅovรกnรญ, odesรญlรกnรญ, streamovรกnรญ, naฤรญtรกnรญ a zruลกenรญ\n- Kล™รญลพovรก kontrola tvrzenรญ oproti API pro audit MCP a รบkoly A2A\n\n
\n๐Ÿ“ก 28. โ€žPotล™ebuji jednotnou pozorovatelnost napล™รญฤ vลกemi rozhranรญmiโ€œ\n
\n\nRozdฤ›lenรญ pozorovatelnosti podle protokolu vytvรกล™รญ slepรก mรญsta a delลกรญ MTTR.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรฉ dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie poลพadavkลฏ napล™รญฤ vrstvami OpenAI, MCP a A2A\n- Provoznรญ API pro stav a automatizaci\n\n
\n๐Ÿ’ผ 29. โ€žPotล™ebuji jeden runtime pro proxy + nรกstroje + orchestraci agentลฏโ€œ\n
\n\nSpouลกtฤ›nรญ mnoha samostatnรฝch sluลพeb zvyลกuje provoznรญ nรกklady a poฤet poruch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Proxy, MCP server a A2A server kompatibilnรญ s OpenAI v jednom balรญฤku\n- Sdรญlenรฉ ovฤ›ล™ovรกnรญ, odolnost, รบloลพiลกtฤ› dat a pozorovatelnost\n- Konzistentnรญ model politik napล™รญฤ vลกemi interakฤnรญmi plochami\n\n
\n๐Ÿš€ 30. โ€žPotล™ebuji agentskรฉ pracovnรญ postupy bez slepenรญ kรณdu.โ€œ\n
\n\nTรฝmy ztrรกcejรญ rychlost pล™i spojovรกnรญ vรญce ad-hoc sluลพeb a skriptลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรก strategie koncovรฝch bodลฏ pro klienty a agenty\n- Vestavฤ›nรก uลพivatelskรก rozhranรญ pro sprรกvu protokolลฏ a cesty pro ovฤ›ล™ovรกnรญ kouล™e\n- Zรกklady pล™ipravenรฉ pro produkฤnรญ prostล™edรญ (zabezpeฤenรญ, protokolovรกnรญ, odolnost, zรกlohovรกnรญ)\n\n### Pล™รญklady hernรญch plรกnลฏ (integrovanรฉ pล™รญpady uลพitรญ)\n\n**Pล™รญruฤka A: Maximalizace placenรฉho pล™edplatnรฉho + levnรฉ zรกlohovรกnรญ**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Pล™รญruฤka B: Kรณdovacรญ stack s nulovรฝmi nรกklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Pล™รญruฤka C: Nonstop zรกloลพnรญ ล™etฤ›zec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Pล™รญruฤka D: Operace agentลฏ s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Zaฤnฤ›te zdarma โ€” Nulovรฉ nรกklady na konfiguraci\n\n> Nastavte si kรณdovรกnรญ s umฤ›lou inteligencรญ bฤ›hem nฤ›kolika minut za **0 $/mฤ›sรญc** . Propojte tyto bezplatnรฉ รบฤty a vyuลพijte vestavฤ›nou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelรฉ odemฤeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Pล™ipojenรญ **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€“ **neomezenฤ›** |\n| 2 | Pล™ipojenรญ k **iFlow** (Google OAuth) | kimi-k2-myลกlenรญ, qwen3-coder-plus, deepseek-r1... โ€” **neomezenฤ›** |\n| 3 | Pล™ipojenรญ **Qwen** (kรณd zaล™รญzenรญ) | qwen3-coder-plus, qwen3-coder-flash... โ€” **neomezenฤ›** |\n| 4 | Pล™ipojenรญ **rozhranรญ pล™รญkazovรฉho ล™รกdku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180 000 GBP/mฤ›sรญc zdarma** |\n| 5 | `/dashboard/combos` โ†’ ล ablona **Free Stack (0 $)** | Automatickรฉ zaล™azenรญ vลกech bezplatnรฝch poskytovatelลฏ do routingu |\n\n**V libovolnรฉm IDE/CLI naveฤte:** `http://localhost:20128/v1` ยท Klรญฤ API: `any-string` ยท Hotovo.\n\n> **Volitelnรฉ doplลˆkovรฉ krytรญ (takรฉ zdarma):** Groq API klรญฤ (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelลฏ), Cerebras (1 milion tok/den).\n\n## โšก Rychlรฝ start\n\n### 1) Nainstalujte a spusลฅte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uลพivatelรฉ pnpm:** Po instalaci spusลฅte `pnpm approve-builds -g` , abyste povolili nativnรญ skripty pro sestavenรญ vyลพadovanรฉ programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard se otevรญrรก na `http://localhost:20128` a zรกkladnรญ URL API je `http://localhost:20128/v1` .\n\n| Pล™รญkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuลกtฤ›nรญ serveru ( `PORT=20128` , API a dashboard na stejnรฉm portu) |\n| `omniroute --port 3000` | Nastavte kanonickรฝ/API port na 3000 |\n| `omniroute --mcp` | Spuลกtฤ›nรญ MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevรญrat prohlรญลพeฤ automaticky |\n| `omniroute --help` | Zobrazit nรกpovฤ›du |\n\nVolitelnรฝ reลพim s rozdฤ›lenรฝm portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Pล™ipojte poskytovatele a vytvoล™te si klรญฤ API\n\n1. Otevล™ete Dashboard โ†’ `Providers` a pล™ipojte alespoลˆ jednoho poskytovatele (klรญฤ OAuth nebo API).\n2. Otevล™ete Dashboard โ†’ `Endpoints` a vytvoล™te API klรญฤ.\n3. (Volitelnรฉ) Otevล™ete Dashboard โ†’ `Combos` a nastavte zรกloลพnรญ ล™etฤ›zec.\n\n### 3) Nasmฤ›rujte svลฏj kรณdovacรญ nรกstroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilnรญmi s OpenAI.\n\n### 4) Povolenรญ a ovฤ›ล™enรญ protokolลฏ (v2.0)\n\n**MCP (pro operace ล™รญzenรฉ nรกstroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak pล™ipojte svรฉho MCP klienta pล™es `stdio` a otestujte nรกstroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovnรญ postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ovฤ›ล™te vลกe od zaฤรกtku do konce (doporuฤeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ovฤ›ล™uje skuteฤnรฉ toky klientลฏ MCP a A2A v porovnรกnรญ se spuลกtฤ›nou aplikacรญ.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute je k dispozici jako veล™ejnรฝ obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlรฝ bฤ›h:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostล™edรญ:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Pouลพรญvรกnรญ Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | ล tรญtek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovฤ›jลกรญ stabilnรญ verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuรกlnรญ verze |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktopovรก aplikace โ€“ offline a vลพdy zapnutรก\n\n> ๐Ÿ†• **NOVINKA!** OmniRoute je nynรญ k dispozici jako **nativnรญ desktopovรก aplikace** pro Windows, macOS a Linux.\n\nSpusลฅte OmniRoute jako samostatnou desktopovou aplikaci โ€“ pro lokรกlnรญ modely nenรญ potล™eba ลพรกdnรฝ terminรกl, prohlรญลพeฤ ani internet. Aplikace zaloลพenรก na platformฤ› Electron obsahuje:\n\n- ๐Ÿ–ฅ๏ธ **Nativnรญ okno** โ€” Vyhrazenรฉ okno aplikace s integracรญ do systรฉmovรฉ liลกty\n- ๐Ÿ”„ **Automatickรฉ spuลกtฤ›nรญ** โ€” Spuลกtฤ›nรญ OmniRoute po pล™ihlรกลกenรญ do systรฉmu\n- ๐Ÿ”” **Nativnรญ oznรกmenรญ** โ€“ Zรญskejte upozornฤ›nรญ na vyฤerpรกnรญ kvรณty nebo problรฉmy s poskytovateli\n- โšก **Instalace jednรญm kliknutรญm** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline reลพim** โ€” Funguje plnฤ› offline s pล™iloลพenรฝm serverem\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systรฉmovรฝ zรกsobnรญk\n\nPo minimalizaci se OmniRoute nachรกzรญ v systรฉmovรฉ liลกtฤ› a nabรญzรญ rychlรฉ akce:\n\n- Otevล™รญt ล™รญdicรญ panel\n- Zmฤ›nit port serveru\n- Ukonฤit aplikaci\n\n๐Ÿ“– รšplnรก dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pล™ehled cen\n\n| รšroveลˆ | Poskytovatel | Nรกklady | Obnovenรญ kvรณty | Nejlepลกรญ pro |\n| --------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **๐Ÿ’ณ Pล˜EDPLATNร‰** | Claude Code (profesionรกl) | 20 dolarลฏ mฤ›sรญฤnฤ› | 5 hodin + tรฝdnฤ› | Jiลพ pล™ihlรกลกen/a k odbฤ›ru |\n| Kodex (Plus/Pro) | 20โ€“200 USD/mฤ›sรญc | 5 hodin + tรฝdnฤ› | Uลพivatelรฉ OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisรญc mฤ›sรญฤnฤ› + 1 tisรญc dennฤ› | Kaลพdรฝ! |\n| GitHub Copilot | 10โ€“19 USD/mฤ›sรญc | Mฤ›sรญฤnรญ | Uลพivatelรฉ GitHubu |\n| **๐Ÿ”‘ KLรฤŒ API** | NVIDIA NIM | **ZDARMA** (vรฝvoj navลพdy) | ~40 ot./min | 70+ otevล™enรฝch modelลฏ |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ na svฤ›tฤ› |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisรญc otรกฤek za minutu | Ultrarychlรก lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | ลฝรกdnรฝ | Nejlepลกรญ zdลฏvodnฤ›nรญ ceny a kvality |\n| xAI Grok-4 Rychlรฝ | **0,20/0,50 USD za 1 milion** ๐Ÿ†• | ลฝรกdnรฝ | Nejrychlejลกรญ + volรกnรญ nรกstroje, ultranรญzkรฉ |\n| xAI Grok-4 (standardnรญ) | 0,20/1,50 USD za 1 milion ๐Ÿ†• | ลฝรกdnรฝ | Vlajkovรก loฤ Reasoning od xAI |\n| Mistral | Zkuลกebnรญ verze zdarma + placenรฉ | Omezenรก sazba | Evropskรก umฤ›lรก inteligence |\n| OpenRouter | Platba za pouลพitรญ | ลฝรกdnรฝ | Vรญce neลพ 100 modelลฏ agregovรกno. |\n| **๐Ÿ’ฐ LEVNร‰** | GLM-5 (pล™es Z.AI) ๐Ÿ†• | 0,5 USD/1 milion | Dennฤ› v 10:00 | Vรฝstup 128 tisรญc obrazovรฝch bodลฏ, nejnovฤ›jลกรญ vlajkovรก loฤ |\n| GLM-4.7 | 0,6 USD/1 milion | Dennฤ› v 10:00 | Zรกloha rozpoฤtu |\n| MiniMax M2.5 ๐Ÿ†• | Vstup 0,3 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | รšvaha + agentnรญ รบkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | Nejlevnฤ›jลกรญ varianta |\n| Kimi K2.5 (Moonshot API) ๐Ÿ†• | Platba za pouลพitรญ | ลฝรกdnรฝ | Pล™รญmรฝ pล™รญstup k Moonshot API |\n| Kimi K2 | 9 dolarลฏ mฤ›sรญฤnฤ› bez zรกvazkลฏ | 10 milionลฏ tokenลฏ/mฤ›sรญc | Pล™edvรญdatelnรฉ nรกklady |\n| **๐Ÿ†“ ZDARMA** | iFlow | **0 dolarลฏ** | Neomezenรฝ | 5 modelลฏ neomezenฤ› |\n| Qwen | **0 dolarลฏ** | Neomezenรฝ | 4 modely neomezenฤ› |\n| Kiro | **0 dolarลฏ** | Neomezenรฝ | Claude Sonnet/Haiku (tvorce AWS) |\n\n> ๐Ÿ†• **Pล™idรกny novรฉ modely (bล™ezen 2026):** ล™ada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkovรกno na 1143 ms โ€“ o 30 % rychlejลกรญ neลพ Gemini 2.5 Flash), GLM-5 pล™es Z.AI s vรฝstupem 128K, uvaลพovรกnรญ MiniMax M2.5, aktualizovanรฉ ceny DeepSeek V3.2, Kimi K2.5 pล™es Moonshot Direct API.\n\n**๐Ÿ’ก Kombinovanรฝ balรญk za 0 $ โ€” Kompletnรญ bezplatnรก instalace:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\niFlow (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Nulovรฉ nรกklady. Nikdy nepล™estรกvejte s kรณdovรกnรญm.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a vลกechny zรกloลพnรญ reลพimy se provede automaticky โ€“ ลพรกdnรฉ ruฤnรญ pล™epรญnรกnรญ.\n\n---\n\n---\n\n## ๐Ÿ†“ Bezplatnรฉ modely โ€“ Co skuteฤnฤ› zรญskรกte\n\n> Vลกechny nรญลพe uvedenรฉ modely jsou **100% zdarma a nevyลพadujรญ ลพรกdnou kreditnรญ kartu** . OmniRoute mezi nimi automaticky propojรญ trasy, kdyลพ dojde jedna kvรณta โ€“ zkombinujte je vลกechny a zรญskejte tak nerozluฤnou kombinaci za 0 dolarลฏ.\n\n### ๐Ÿ”ต CLAUDE MODELS (pล™es Kiro โ€” AWS Builder ID)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-opus-4.6` | `kr/` | **Neomezenรฝ** | Nejnovฤ›jลกรญ opus od Kira |\n\n### ๐ŸŸข MODELY IFLOW (Bezplatnรฉ OAuth โ€” bez nutnosti platit kreditnรญ kartou)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-plus` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `deepseek-r1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `minimax-m2.1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `kimi-k2` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n\n### ๐ŸŸก MODELY QWEN (Ovฤ›ล™enรญ kรณdu zaล™รญzenรญ)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-next` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `vision-model` | `qw/` | **Neomezenรฝ** | Multimodรกlnรญ (obrรกzky) |\n\n### ๐ŸŸฃ Rozhranรญ GEMINI CLI (Google OAuth)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisรญc tok/mฤ›sรญc** + 1 tisรญc/den | Mฤ›sรญฤnรญ reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisรญc mฤ›sรญฤnฤ› (sdรญlenรฝ bazรฉn) | Vysokรก kvalita |\n\n### โšซ NVIDIA NIM (Bezplatnรฝ klรญฤ API โ€” build.nvidia.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vรฝvojรกล™) | ลฝรกdnรฝ limit tokenลฏ | **~40 ot./min** | Vรญce neลพ 70 modelลฏ; pล™echod na ฤistรฉ limity sazeb v polovinฤ› roku 2025 |\n\nOblรญbenรฉ bezplatnรฉ modely: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct` , `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Bezplatnรฝ klรญฤ API โ€” inference.cerebras.ai)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenลฏ/den** | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ inference LLM na svฤ›tฤ›; dennฤ› se resetuje |\n\nDostupnรฉ zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Bezplatnรฝ API klรญฤ โ€” console.groq.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisรญc otรกฤek za minutu** | 30 ot./min na model | ลฝรกdnรก kreditnรญ karta; limit 429, neรบฤtovรกno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **๐Ÿ’ก Ultimรกtnรญ bezplatnรฝ zรกsobnรญk:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> โ†’ iFlow (5 models, unlimited)\n> โ†’ Qwen (4 models, unlimited)\n> โ†’ Gemini CLI (180K/mo)\n> โ†’ Cerebras (1M tok/day)\n> โ†’ Groq (14.4K req/day)\n> โ†’ NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a uลพ nikdy nebudete platit za umฤ›lou inteligenci.\n\n## ๐ŸŽ™๏ธ Kombinovanรก transkripce zdarma\n\n> Pล™episujte libovolnรฉ audio/video za **0 $** โ€“ Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako zรกloลพnรญ nรกstroj, Groq Whisper jako neomezenรก nouzovรก zรกloha.\n\n| Poskytovatel | Bezplatnรฉ kredity | Nejlepลกรญ model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| ๐ŸŸข **Deepgram** | **200 dolarลฏ zdarma** (registrace) | `nova-3` โ€” nejvyลกลกรญ pล™esnost, vรญce neลพ 30 jazykลฏ | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ต **AssemblyAI** | **50 dolarลฏ zdarma** (registrace) | `universal-3-pro` โ€” kapitoly, sentiment, osobnรญ รบdaje | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ด **Groq** | **Navลพdy zdarma** | `whisper-large-v3` โ€” OpenAI ล epot | 30 ot./min (omezenรก rychlost) |\n\n**Navrhovanรก kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nPak v `/dashboard/media` โ†’ zรกloลพka **Pล™epis** : nahrajte libovolnรฝ zvukovรฝ nebo video soubor โ†’ vyberte kombinovanรฝ koncovรฝ bod โ†’ zรญskejte pล™epis v podporovanรฝch formรกtech.\n\n## ๐Ÿ’ก Klรญฤovรฉ vlastnosti\n\nOmniRoute v2.0 je navrลพen jako operaฤnรญ platforma, nikoli pouze jako proxy pro relรฉ.\n\n### ๐Ÿค– Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dฤ›lรก |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (16 nรกstrojลฏ)** | Nรกstroje IDE/agent prostล™ednictvรญm 3 transportลฏ: stdio, SSE ( `/api/mcp/sse` ), Streamovatelnรฝ HTTP ( `/api/mcp/stream` ) |\n| ๐Ÿค **A2A server (JSON-RPC + SSE)** | Spouลกtฤ›nรญ รบloh mezi agenty se synchronizacรญ a streamovรกnรญm |\n| ๐Ÿงญ **Konsolidovanรก strรกnka koncovรฝch bodลฏ** | Strรกnka pro sprรกvu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| ๐ŸŽš๏ธ **Pล™epรญnaฤe pro povolenรญ/zakรกzรกnรญ sluลพby** | Pล™epรญnaฤe ZAP/VYP pro MCP a A2A s trvalรฝm nastavenรญm (vรฝchozรญ: VYP) |\n| ๐Ÿ›ฐ๏ธ **Srdeฤnรญ tep za bฤ›hu MCP** | Skuteฤnรฝ stav procesu (pid, doba provozuschopnosti, stรกล™รญ heartbeatu, transport, reลพim rozsahu) |\n| ๐Ÿ“‹ **Auditnรญ zรกznam MCP** | Filtrovatelnรฉ protokoly auditu s hodnocenรญm รบspฤ›chu/neรบspฤ›chu a klรญฤovรฝm pล™iล™azenรญm |\n| ๐Ÿ” **Vynucovรกnรญ rozsahu MCP** | 9 podrobnรฝch oprรกvnฤ›nรญ pro ล™รญzenรฝ pล™รญstup k nรกstrojลฏm |\n| ๐Ÿ“ก **Sprรกva ลพivotnรญho cyklu รบkolลฏ A2A** | Seznam/filtrovรกnรญ รบloh, kontrola udรกlostรญ/artefaktลฏ, zruลกenรญ spuลกtฤ›nรฝch รบloh |\n| ๐Ÿ“‹ **Objevenรญ karty agenta** | `/.well-known/agent.json` pro automatickรฉ vyhledรกvรกnรญ klientลฏ |\n| ๐Ÿงช **Testovacรญ postroj Protocol E2E** | Skuteฤnรฉ MCP SDK + toky klientลฏ A2A v `test:protocols:e2e` |\n| โš™๏ธ **Provoznรญ kontroly** | Kombinace pล™epรญnaฤลฏ, pouลพitรญ profilลฏ odolnosti, resetovรกnรญ jistiฤลฏ z jednoho ovlรกdacรญho panelu |\n\n### ๐Ÿง  Smฤ›rovรกnรญ a inteligence\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| ๐ŸŽฏ **Inteligentnรญ ฤtyล™รบrovลˆovรฝ zรกloลพnรญ systรฉm** | Automatickรก trasa: Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma |\n| ๐Ÿ“Š **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** | Poฤet tokenลฏ v reรกlnรฉm ฤase + odpoฤet resetovรกnรญ pro kaลพdรฉho poskytovatele |\n| ๐Ÿ”„ **Pล™eklad formรกtu** | OpenAI โ†” Claude โ†” Gemini โ†” Odpovฤ›di s konverzemi bezpeฤnรฝmi pro schรฉma |\n| ๐Ÿ‘ฅ **Podpora vรญce รบฤtลฏ** | Vรญce รบฤtลฏ na poskytovatele s inteligentnรญm vรฝbฤ›rem |\n| ๐Ÿ”„ **Automatickรก aktualizace tokenลฏ** | Tokeny OAuth se automaticky obnovujรญ pล™i opakovanรฉm pokusu. |\n| ๐ŸŽจ **Vlastnรญ kombinace** | 6 vyvaลพovacรญch strategiรญ + ล™รญzenรญ zรกloลพnรญho ล™etฤ›zce |\n| ๐ŸŒ **Smฤ›rovaฤ se zรกstupnรฝmi znaky** | dynamickรฉ smฤ›rovรกnรญ `provider/*` |\n| ๐Ÿง  **Pล™emรฝลกlenรญ o rozpoฤtovรฝch kontrolรกch** | Limity pro prลฏchozรญ, automatickรฉ, vlastnรญ a adaptivnรญ uvaลพovรกnรญ |\n| ๐Ÿ”€ **Aliasy modelลฏ** | Vestavฤ›nรฉ + vlastnรญ aliasovรกnรญ modelลฏ a bezpeฤnost migrace |\n| โšก **Degradace pozadรญ** | Smฤ›rujte รบlohy na pozadรญ s nรญzkou prioritou na levnฤ›jลกรญ modely |\n| ๐Ÿงช **Chytrรฉ smฤ›rovรกnรญ s ohledem na รบkoly** | Automatickรฝ vรฝbฤ›r modelu podle typu obsahu (kรณdovรกnรญ/vize/analรฝza/sumarizace) |\n| ๐Ÿ’ฌ **Vstล™ikovรกnรญ do systรฉmu** | Globรกlnรญ kontroly chovรกnรญ uplatลˆovanรฉ konzistentnฤ› |\n| ๐Ÿ“„ **Kompatibilita API pro odpovฤ›di** | Plnรก podpora `/v1/responses` pro Codex a pokroฤilรฉ agentickรฉ pracovnรญ postupy |\n\n### ๐ŸŽต Multimodรกlnรญ API\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Generovรกnรญ obrรกzkลฏ** | `/v1/images/generations` s cloudovรฝm a lokรกlnรญm backendem |\n| ๐Ÿ“ **Vloลพenรญ** | `/v1/embeddings` pro vyhledรกvรกnรญ a RAG pipelines |\n| ๐ŸŽค **Pล™epis zvuku** | `/v1/audio/transcriptions` (Whisper a dalลกรญ poskytovatelรฉ) |\n| ๐Ÿ”Š **Pล™evod textu na ล™eฤ** | `/v1/audio/speech` (vรญce enginลฏ/poskytovatelลฏ) |\n| ๐ŸŽฌ **Generovรกnรญ videa** | `/v1/videos/generations` (pracovnรญ postupy ComfyUI + SD WebUI) |\n| ๐ŸŽต **Hudebnรญ generace** | `/v1/music/generations` (pracovnรญ postupy ComfyUI) |\n| ๐Ÿ›ก๏ธ **Moderovรกnรญ** | Bezpeฤnostnรญ kontroly `/v1/moderations` |\n| ๐Ÿ”€ **Zmฤ›na poล™adรญ** | `/v1/rerank` pro hodnocenรญ relevance |\n| ๐Ÿ” **Vyhledรกvรกnรญ na webu** ๐Ÿ†• | `/v1/search` โ€” 5 poskytovatelลฏ (Serper, Brave, Perplexity, Exa, Tavily), vรญce neลพ 6 500 zdarma/mฤ›sรญc, automatickรฉ pล™epnutรญ na zรกloลพnรญ systรฉm, mezipamฤ›ลฅ |\n\n### ๐Ÿ›ก๏ธ Odolnost, bezpeฤnost a sprรกva vฤ›cรญ veล™ejnรฝch\n\n| Funkce | Co to dฤ›lรก |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Jistiฤe** | Vypnutรญ/obnovenรญ pro kaลพdรฝ model s ovlรกdรกnรญm prahovรฝch hodnot |\n| ๐ŸŽฏ **Modely s ohledem na koncovรฉ body** | Vlastnรญ modely deklarujรญ podporovanรฉ koncovรฉ body + formรกt API |\n| ๐Ÿ›ก๏ธ **Stรกdo proti hromลฏm** | Ochrana mutexu a semaforu pล™i udรกlostech opakovรกnรญ/rychlosti |\n| ๐Ÿง  **Sรฉmantickรก + podpisovรก mezipamฤ›ลฅ** | Snรญลพenรญ nรกkladลฏ/latence dรญky dvฤ›ma vrstvรกm mezipamฤ›ti |\n| โšก **ลฝรกdost o idempotenci** | Okno ochrany proti duplikacรญm |\n| ๐Ÿ”’ **Falลกovรกnรญ otiskลฏ prstลฏ pomocรญ TLS** | Otisk TLS podobnรฝ prohlรญลพeฤi โ€“ **sniลพuje detekci botลฏ a nahlaลกovรกnรญ รบฤtลฏ** |\n| ๐Ÿ” **Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** | Shoduje se s nativnรญmi podpisy poลพadavkลฏ CLI โ€“ **sniลพuje riziko zablokovรกnรญ a zรกroveลˆ zachovรกvรก IP adresu proxy** |\n| ๐ŸŒ **Filtrovรกnรญ IP adres** | Ovlรกdรกnรญ seznamu povolenรฝch/blokovanรฝch poloลพek pro odhalenรก nasazenรญ |\n| ๐Ÿ“Š **Upravitelnรฉ limity rychlosti** | Konfigurovatelnรฉ globรกlnรญ/na รบrovni poskytovatele limity s perzistencรญ |\n| ๐Ÿ”‘ **Sprรกva klรญฤลฏ API a stanovenรญ rozsahu** | Bezpeฤnรฉ vydรกvรกnรญ/rotace klรญฤลฏ a kontroly modelu/poskytovatele |\n| ๐Ÿ›ก๏ธ **Chrรกnฤ›nรฉ `/models`** | Volitelnรฉ ovฤ›ล™ovรกnรญ a skrytรญ poskytovatele pro katalog modelลฏ |\n\n### ๐Ÿ“Š Pozorovatelnost a analytika\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| ๐Ÿ“ **ลฝรกdost + protokolovรกnรญ proxy** | รšplnรฉ protokolovรกnรญ poลพadavkลฏ/odpovฤ›dรญ a proxy |\n| ๐Ÿ“‰ **Streamed Detailed Logs** ๐Ÿ†• | Reconstructs SSE payload streams cleanly into the UI |\n| ๐Ÿ“‹ **Sjednocenรฝ panel protokolลฏ** | Zobrazenรญ poลพadavkลฏ, proxy, auditu a konzole na jednรฉ strรกnce |\n| ๐Ÿ” **Vyลพรกdat si telemetrii** | Latence p50/p95/p99 a trasovรกnรญ poลพadavkลฏ |\n| ๐Ÿฅ **Panel zdravรญ** | Doba provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti |\n| ๐Ÿ’ฐ **Sledovรกnรญ nรกkladลฏ** | Kontrola rozpoฤtu a pล™ehled o cenรกch pro jednotlivรฉ modely |\n| ๐Ÿ“ˆ **Analytickรฉ vizualizace** | Pล™ehledy vyuลพitรญ modelลฏ/poskytovatelลฏ a zobrazenรญ trendลฏ |\n| ๐Ÿงช **Rรกmec hodnocenรญ** | Testovรกnรญ zlatรฉ sady s konfigurovatelnรฝmi strategiemi shody |\n\n### โ˜๏ธ Nasazenรญ a platforma\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| ๐ŸŒ **Nasazenรญ kdekoli** | Localhost, VPS, Docker, cloudovรก prostล™edรญ |\n| ๐Ÿ’พ **Synchronizace s cloudem** | Synchronizace konfigurace pล™es cloud worker |\n| ๐Ÿ”„ **Zรกlohovรกnรญ/Obnovenรญ** | Toky exportu/importu a obnovy po havรกrii |\n| ๐Ÿง™ **Prลฏvodce nรกstupem** | Prลฏvodce prvnรญm spuลกtฤ›nรญm |\n| ๐Ÿ”ง **Panel nรกstrojลฏ CLI** | Nastavenรญ oblรญbenรฝch kรณdovacรญch nรกstrojลฏ jednรญm kliknutรญm |\n| ๐ŸŽฎ **Modelovรฉ hล™iลกtฤ›** | Otestujte libovolnรฉho poskytovatele/model/koncovรฝ bod z ล™รญdicรญho panelu |\n| ๐Ÿ” **Pล™epรญnaฤ otiskลฏ prstลฏ v pล™รญkazovรฉm ล™รกdku** | Porovnรกvรกnรญ otiskลฏ prstลฏ podle poskytovatele v Nastavenรญ > Zabezpeฤenรญ |\n| ๐ŸŒ **i18n (30 jazykลฏ)** | Plnรก jazykovรก podpora dashboardu a dokumentace s psanรญm zprava doleva |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Adresรกล™ vlastnรญch dat** | Pล™epsรกnรญ `DATA_DIR` pro umรญstฤ›nรญ รบloลพiลกtฤ› |\n\n### Hlubokรฝ pohled na funkce\n\n#### Chytrรก zรกloลพnรญ funkce s praktickou kontrolou nรกkladลฏ\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyลพ selลพe kvรณta, rychlost nebo stav, OmniRoute automaticky pล™ejde k dalลกรญmu kandidรกtovi bez nutnosti ruฤnรญho pล™epรญnรกnรญ.\n\n#### Sprรกva protokolลฏ, kterรก je viditelnรก a ovladatelnรก\n\n- MCP + A2A jsou viditelnรฉ v uลพivatelskรฉm rozhranรญ a dokumentaci (nejsou skrytรฉ)\n- API pro stav protokolu zpล™รญstupลˆujรญ ลพivรก provoznรญ data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnujรญ akce pro operace 2. dne (pล™epรญnรกnรญ kombinacรญ, resetovรกnรญ jistiฤลฏ, zruลกenรญ รบkolลฏ)\n\n#### Pracovnรญ postup pล™ekladatele + validace\n\nOblast pล™ekladatele zahrnuje:\n\n- **Hล™iลกtฤ›** : kontroly transformace poลพadavkลฏ\n- **Tester chatu** : kompletnรญ okruลพnรญ cesta poลพadavku/odpovฤ›di\n- **Testovacรญ stolice** : vรญce pล™รญpadลฏ v jednom bฤ›hu\n- **ลฝivรฝ monitor** : zobrazenรญ provozu v reรกlnรฉm ฤase\n\nPlus validace protokolu se skuteฤnรฝmi klienty pomocรญ `npm run test:protocols:e2e` .\n\n> ๐Ÿ“– **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** โ€” Referenฤnรญ informace o nรกstrojรญch, konfigurace IDE a pล™รญklady klientลฏ\n>\n> ๐Ÿ“– **[Soubor README pro A2A Server](src/lib/a2a/README.md)** โ€” Dovednosti, metody JSON-RPC, streamovรกnรญ a ลพivotnรญ cyklus รบloh\n\n## ๐Ÿงช Hodnocenรญ (Evals)\n\nOmniRoute obsahuje vestavฤ›nรฝ hodnotรญcรญ rรกmec pro testovรกnรญ kvality odpovฤ›dรญ LLM v porovnรกnรญ se zlatou sadou. Pล™รญstup k nฤ›mu je moลพnรฝ pล™es **Analรฝzy โ†’ Hodnocenรญ** v dashboardu.\n\n### Vestavฤ›nรก zlatรก sada\n\nPล™edinstalovanรก sada โ€žOmniRoute Golden Setโ€œ obsahuje testovacรญ pล™รญpady pro:\n\n- Zdravรญm, matematika, zemฤ›pis, generovรกnรญ kรณdu\n- Shoda s formรกtem JSON, pล™eklad, generovรกnรญ markdownลฏ\n- Bezpeฤnostnรญ odmรญtnutรญ (ลกkodlivรฝ obsah), poฤรญtรกnรญ, booleovskรก logika\n\n### Strategie hodnocenรญ\n\n| Strategie | Popis | Pล™รญklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Vรฝstup se musรญ pล™esnฤ› shodovat | `\"4\"` |\n| `contains` | Vรฝstup musรญ obsahovat podล™etฤ›zec (bez rozliลกenรญ velkรฝch a malรฝch pรญsmen) | `\"Paris\"` |\n| `regex` | Vรฝstup musรญ odpovรญdat vzoru regulรกrnรญch vรฝrazลฏ | `\"1.*2.*3\"` |\n| `custom` | Vlastnรญ JS funkce vracรญ true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Prลฏvodce nastavenรญm\n\n### Nastavenรญ protokolu (MCP + A2A)\n\n
\n๐Ÿงฉ Nastavenรญ MCP (Model Context Protocol)\n
\n\nSpuลกtฤ›nรญ MCP transportu v reลพimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporuฤenรฝ postup ovฤ›ล™enรญ:\n\n1. Pล™ipojte svรฉho MCP klienta pล™es stdio.\n2. Spusลฅte `omniroute_get_health` .\n3. Spusลฅte `omniroute_list_combos` .\n4. Otevล™ete `/dashboard/mcp` pro ovฤ›ล™enรญ prezenฤnรญho signรกlu, aktivity a auditu.\n\nUลพiteฤnรก API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n๐Ÿค Nastavenรญ A2A (Agent2Agent)\n
\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat รบkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSprรกva ลพivotnรญho cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvoznรญ uลพivatelskรฉ rozhranรญ:\n\n- `/dashboard/a2a` pro pozorovatelnost รบloh/stavลฏ/streamลฏ a akce kouล™enรญ\n\n
\n๐Ÿงช Komplexnรญ validace protokolu\n
\n\nOvฤ›ล™te oba protokoly se skuteฤnรฝmi klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTรญm se ovฤ›ล™uje:\n\n- Pล™ipojenรญ/seznam/volรกnรญ klienta MCP SDK\n- A2A objevovรกnรญ/odesรญlรกnรญ/streamovรกnรญ/zรญskรกvรกnรญ/zruลกenรญ\n- Kล™รญลพovรก kontrola dat v auditu MCP a API pro sprรกvu รบloh A2A\n\n
\n๐Ÿ’ณ Poskytovatelรฉ pล™edplatnรฉho\n
\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionรกly:** Pro sloลพitรฉ รบkoly pouลพรญvejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvรณtu pro kaลพdรฝ model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Sprรกva limitลฏ รบฤtu Codex (5h + tรฝdnฤ›)\n\nKaลพdรฝ รบฤet Codex mรก nynรญ pล™epรญnaฤe zรกsad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinovรฉho prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zรกsadu tรฝdennรญho prahu okna.\n- Prahovรฉ chovรกnรญ: kdyลพ povolenรฉ okno dosรกhne vyuลพitรญ >=90 %, je danรฝ รบฤet pล™eskoฤen.\n- Chovรกnรญ rotace: OmniRoute automaticky pล™esmฤ›ruje na dalลกรญ zpลฏsobilรฝ รบฤet Codex.\n- Chovรกnรญ pล™i resetovรกnรญ: Po `resetAt` urฤitรฉ doby se รบฤet automaticky opฤ›t stane zpลฏsobilรฝm.\n\nScรฉnรกล™e:\n\n- `5h ON` + `Weekly ON` : รบฤet je pล™eskoฤen, kdyลพ kterรฉkoli z oken dosรกhne prahovรฉ hodnoty.\n- `5h OFF` + `Weekly ON` : รบฤet mลฏลพe bรฝt zablokovรกn pouze tรฝdennรญm pouลพรญvรกnรญm.\n- `5h ON` + `Weekly OFF` : รบฤet mลฏลพe bรฝt zablokovรกn pouze pล™i 5hodinovรฉm pouลพรญvรกnรญ.\n- `resetAt` passed: รบฤet se automaticky znovu zapne (bez ruฤnรญho opฤ›tovnรฉho povolenรญ).\n\n### Gemini CLI (ZDARMA 180 000/mฤ›sรญc!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepลกรญ hodnota:** Obrovskรก bezplatnรก รบroveลˆ! Pouลพijte ji pล™ed placenรฝmi รบrovnฤ›mi.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n
\n๐Ÿ”‘ Poskytovatelรฉ klรญฤลฏ API\n
\n\n### NVIDIA NIM (BEZPLATNร pล™รญstup pro vรฝvojรกล™e โ€” vรญce neลพ 70 modelลฏ)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Zรญskejte zdarma klรญฤ API (vฤetnฤ› 1000 inferenฤnรญch kreditลฏ)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ NVIDIA NIM:\n - Klรญฤ API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a vรญce neลพ 50 dalลกรญch\n\n**Tip pro profesionรกly:** API kompatibilnรญ s OpenAI โ€“ funguje bez problรฉmลฏ s pล™ekladem formรกtลฏ OmniRoute!\n\n### Hlubokรฉ vyhledรกvรกnรญ\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatnรก รบroveลˆ!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Zรญskejte klรญฤ API (vฤetnฤ› bezplatnรฉ รบrovnฤ›)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionรกly:** Ultrarychlรก inference โ€“ nejlepลกรญ pro kรณdovรกnรญ v reรกlnรฉm ฤase!\n\n### OpenRouter (100+ modelลฏ)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ OpenRouter\n\n**Modely:** Zรญskejte pล™รญstup k vรญce neลพ 100 modelลฏm od vลกech hlavnรญch poskytovatelลฏ prostล™ednictvรญm jedinรฉho klรญฤe API.\n\n
\n๐Ÿ’ฐ Levnรญ poskytovatelรฉ (zรกloลพnรญ)\n
\n\n### GLM-4.7 (Dennรญ reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Zรญskejte klรญฤ API z kรณdovacรญho plรกnu\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API:\n - Poskytovatel: `glm`\n - Klรญฤ API: `your-key`\n\n**Pouลพitรญ:** `glm/glm-4.7`\n\n**Tip pro profesionรกly:** Programovacรญ plรกn nabรญzรญ 3ร— kvรณtu za cenu 1/7! Obnovuje se dennฤ› v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionรกly:** Nejlevnฤ›jลกรญ varianta pro dlouhรฝ kontext (1 milion tokenลฏ)!\n\n### Kimi K2 (pauลกรกlnรญ poplatek 9 dolarลฏ mฤ›sรญฤnฤ›)\n\n1. Odebรญrat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `kimi/kimi-latest`\n\n**Tip pro profesionรกly:** Fixnรญch 9 $/mฤ›sรญc za 10 milionลฏ tokenลฏ = efektivnรญ nรกklady 0,90 $/1 milion!\n\n
\n๐Ÿ†“ BEZPLATNร poskytovatelรฉ (nouzovรฉ zรกlohovรกnรญ)\n
\n\n### iFlow (5 BEZPLATNรCH modelลฏ pล™es OAuth)\n\n```bash\nDashboard โ†’ Connect iFlow\nโ†’ iFlow OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kรณdem zaล™รญzenรญ)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n๐ŸŽจ Vytvoล™te kombinace\n
\n\n### Pล™รญklad 1: Maximalizace pล™edplatnรฉho โ†’ Levnรฉ zรกlohovรกnรญ\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Pล™รญklad 2: Pouze zdarma (nulovรฉ nรกklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n๐Ÿ”ง Integrace s rozhranรญm pล™รญkazovรฉho ล™รกdku\n
\n\n### IDE kurzoru\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jednรญm kliknutรญm pouลพijte strรกnku **Nรกstroje CLI** na ล™รญdicรญm panelu nebo ruฤnฤ› upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Moลพnost 1 โ€“ Dashboard (doporuฤeno):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Moลพnost 2 โ€“ Manuรกlnรญ รบprava:** รšprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznรกmka:** OpenClaw funguje pouze s lokรกlnรญm OmniRoute. Mรญsto `localhost` pouลพijte `127.0.0.1` , abyste se vyhnuli problรฉmลฏm s rozliลกenรญm IPv6.\n\n### Cline / Pokraฤovat / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Pล™idรกnรญ OmniRoute jako vlastnรญho poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvoล™te/upravte `opencode.json` v koล™enovรฉm adresรกล™i projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` pล™idejte jakรฝkoli model dostupnรฝ ve vaลกem koncovรฉm bodu OmniRoute `/v1/models` . Pouลพijte formรกt `provider/model-id` z vaลกeho dashboardu OmniRoute.\n\n---\n\n## ๐Ÿ› ล˜eลกenรญ problรฉmลฏ\n\n
\nKliknutรญm rozbalรญte prลฏvodce ล™eลกenรญm problรฉmลฏ\n
\n\n**\"Jazykovรฝ model neposkytoval zprรกvy\"**\n\n- Kvรณta poskytovatele vyฤerpรกna โ†’ Zkontrolujte sledovรกnรญ kvรณt na ล™รญdicรญm panelu\n- ล˜eลกenรญ: Pouลพijte zรกloลพnรญ kombinovanou variantu nebo pล™ejdฤ›te na levnฤ›jลกรญ รบroveลˆ\n\n**Omezenรญ rychlosti**\n\n- Kvรณta pล™edplatnรฉho vyฤerpรกna โ†’ Pล™echod na GLM/MiniMax\n- Pล™idat kombo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vyprลกela**\n\n- Automaticky aktualizovรกno sluลพbou OmniRoute\n- Pokud problรฉmy pล™etrvรกvajรญ: Ovlรกdacรญ panel โ†’ Poskytovatel โ†’ Znovu pล™ipojit\n\n**Vysokรฉ nรกklady**\n\n- Zkontrolujte statistiky vyuลพitรญ v sekci Nรกstฤ›nka โ†’ Nรกklady\n- Pล™epnout primรกrnรญ model na GLM/MiniMax\n- Pro nekritickรฉ รบlohy pouลพijte bezplatnou รบroveลˆ (Gemini CLI, iFlow).\n\n**Porty ล™รญdicรญho panelu/API jsou nesprรกvnรฉ**\n\n- `PORT` je kanonickรฝ zรกkladnรญ port (a standardnฤ› port API)\n- `API_PORT` pล™episuje pouze posluchaฤ API kompatibilnรญ s OpenAI.\n- `DASHBOARD_PORT` pล™episuje pouze posluchaฤ dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaลกi veล™ejnou URL adresu ล™รญdicรญho panelu (pro zpฤ›tnรก volรกnรญ OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ovฤ›ล™te, zda `BASE_URL` odkazuje na vaลกi spuลกtฤ›nou instanci.\n- Ovฤ›ล™te, zda `CLOUD_URL` odkazuje na vรกลก oฤekรกvanรฝ cloudovรฝ koncovรฝ bod.\n- Udrลพujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na stranฤ› serveru.\n\n**Prvnรญ pล™ihlรกลกenรญ nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud nenรญ nastaveno, zรกloลพnรญ heslo je `123456`\n\n**ลฝรกdnรฉ protokoly poลพadavkลฏ**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test pล™ipojenรญ ukazuje โ€žNeplatnรฉโ€œ pro poskytovatele kompatibilnรญ s OpenAI**\n\n- Mnoho poskytovatelลฏ nezpล™รญstupลˆuje koncovรฝ bod `/models`\n- OmniRoute v1.0.6+ zahrnuje zรกloลพnรญ ovฤ›ล™enรญ pomocรญ dokonฤenรญ chatu\n- Zajistฤ›te, aby zรกkladnรญ URL adresa obsahovala pล™รญponu `/v1`\n\n### ๐Ÿ” OAuth na vzdรกlenรฉm serveru\n\n\n\n> **โš ๏ธ Dลฏleลพitรฉ pro uลพivatele, kteล™รญ provozujรญ OmniRoute na VPS, Dockeru nebo jakรฉmkoli vzdรกlenรฉm serveru**\n\n#### Proฤ selhรกvรก OAuth v rozhranรญ CLI Antigravity / Gemini na vzdรกlenรฝch serverech?\n\nPoskytovatelรฉ rozhranรญ CLI **Antigravity** a **Gemini** pouลพรญvajรญ **Google OAuth 2.0** . Google vyลพaduje, aby se `redirect_uri` v toku OAuth pล™esnฤ› shodoval s jednรญm z pล™edregistrovanรฝch URI v konzoli Google Cloud Console aplikace.\n\nPล™ihlaลกovacรญ รบdaje OAuth, kterรฉ jsou souฤรกstรญ OmniRoute, jsou registrovรกny **pouze pro `localhost`** . Kdyลพ pล™istupujete k OmniRoute na vzdรกlenรฉm serveru (napล™. `https://omniroute.myserver.com` ), Google odmรญtne ovฤ›ล™enรญ pomocรญ:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### ล˜eลกenรญ: Nakonfigurujte si vlastnรญ pล™ihlaลกovacรญ รบdaje OAuth\n\nV Google Cloud Console je potล™eba vytvoล™it **ID klienta OAuth 2.0** s URI vaลกeho serveru.\n\n#### Krok za krokem\n\n**1. Otevล™ete konzoli Google Cloud**\n\nPล™ejdฤ›te na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvoล™te novรฉ ID klienta OAuth 2.0**\n\n- Kliknฤ›te na **โ€ž+ Vytvoล™it pล™ihlaลกovacรญ รบdajeโ€œ** โ†’ **โ€žID klienta OAuthโ€œ**\n- Typ aplikace: **โ€žWebovรก aplikaceโ€œ**\n- Nรกzev: cokoli chcete (napล™. `OmniRoute Remote` )\n\n**3. Pล™idejte autorizovanรฉ URI pro pล™esmฤ›rovรกnรญ**\n\nDo pole **โ€žAutorizovanรฉ identifikรกtory URI pro pล™esmฤ›rovรกnรญโ€œ** pล™idejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraฤte `your-server.com` domรฉnou nebo IP adresou vaลกeho serveru (v pล™รญpadฤ› potล™eby uveฤte i port, napล™. `http://45.33.32.156:20128/callback` ).\n\n**4. Uloลพte a zkopรญrujte pล™ihlaลกovacรญ รบdaje**\n\nPo vytvoล™enรญ Google zobrazรญ **ID klienta** a **tajnรฝ kรณd klienta** .\n\n**5. Nastavenรญ promฤ›nnรฝch prostล™edรญ**\n\nVe vaลกem souboru `.env` (nebo promฤ›nnรฝch prostล™edรญ Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu pล™ipojit**\n\nล˜รญdicรญ panel โ†’ Poskytovatelรฉ โ†’ Antigravity (nebo Gemini CLI) โ†’ OAuth\n\nGoogle nynรญ bude sprรกvnฤ› pล™esmฤ›rovรกvat na `https://your-server.com/callback` .\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nPokud si teฤ nechcete nastavovat vlastnรญ pล™ihlaลกovacรญ รบdaje, mลฏลพete stรกle pouลพรญt **ruฤnรญ postup pro URL** :\n\n1. OmniRoute otevรญrรก autorizaฤnรญ URL od Googlu\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru).\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe (i kdyลพ se strรกnka nenaฤte)\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute.\n5. Kliknฤ›te na **โ€žPล™ipojitโ€œ**\n\n> To funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na to, zda se naฤetla pล™esmฤ›rovacรญ strรกnka.\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nChcete-li zรญskat pล™รญstup k pล™ihlaลกovacรญm รบdajลฏm bez vlastnรญ konfigurace, mลฏลพete pouลพรญt nรกsledujรญcรญ postup:\n\n1. OmniRoute otevล™e URL autorizace Google\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru)\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute\n5. Kliknฤ›te na **โ€žPล™ipojit\"**\n\n> Toto ล™eลกenรญ funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na naฤtenรญ pล™esmฤ›rovacรญ strรกnky.\n\n---\n\n## ๐Ÿ› ๏ธ Technologickรฝ stack\n\n
\nKliknutรญm rozbalรญte podrobnosti o technologickรฉm stacku\n
\n\n- **Runtime** : Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ **nenรญ podporovรกn** โ€” nativnรญ binรกrnรญ soubory `better-sqlite3` jsou nekompatibilnรญ)\n- **Jazyk** : TypeScript 5.9 โ€” **100% TypeScript** napล™รญฤ `src/` a `open-sse/` ( `any` v zรกkladnรญch modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databรกze** : LowDB (JSON) + SQLite (stav domรฉny + protokoly proxy + audit MCP + rozhodnutรญ o smฤ›rovรกnรญ)\n- **Schรฉmata** : Zod (validace I/O nรกstrojลฏ MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamovรกnรญ** : Udรกlosti odeslanรฉ serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klรญฤe + autorizace s rozsahem MCP\n- **Testovรกnรญ** : Node.js test runner + Vitest (900+ testลฏ vฤetnฤ› unit, integraฤnรญch, E2E)\n- **CI/CD** : Akce GitHubu (automatickรฉ publikovรกnรญ v npm + Docker Hub pล™i vydรกnรญ)\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **Balรญฤek** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistiฤ, exponenciรกlnรญ odstavenรญ, ochrana proti hromลฏm, faleลกnรฉ TLS, automatickรฉ kombinovanรฉ samoopravovรกnรญ\n\n---\n\n## ๐Ÿ“– Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uลพivatelskรก pล™รญruฤka](docs/USER_GUIDE.md) | Poskytovatelรฉ, kombinace, integrace CLI, nasazenรญ |\n| [Referenฤnรญ informace k API](docs/API_REFERENCE.md) | Vลกechny koncovรฉ body s pล™รญklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nรกstrojลฏ MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamovรกnรญ, sprรกva รบloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorovรฉ bodovรกnรญ, balรญฤky reลพimลฏ, samolรฉฤba |\n| [Odstraลˆovรกnรญ problรฉmลฏ](docs/TROUBLESHOOTING.md) | Bฤ›ลพnรฉ problรฉmy a jejich ล™eลกenรญ |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a internรญ prvky systรฉmu |\n| [Pล™ispรญvรกnรญ](CONTRIBUTING.md) | Nastavenรญ a pokyny pro vรฝvoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpeฤnostnรญ zรกsady](SECURITY.md) | Hlรกลกenรญ zranitelnostรญ a bezpeฤnostnรญ postupy |\n| [Nasazenรญ virtuรกlnรญho poฤรญtaฤe](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletnรญ prลฏvodce: Nastavenรญ virtuรกlnรญho poฤรญtaฤe + nginx + Cloudflare |\n| [Galerie funkcรญ](docs/FEATURES.md) | Vizuรกlnรญ prohlรญdka ล™รญdicรญho panelu se snรญmky obrazovky |\n| [Kontrolnรญ seznam vydรกnรญ](docs/RELEASE_CHECKLIST.md) | Kroky ovฤ›ล™enรญ pล™ed vydรกnรญm |\n\n---\n\n## ๐Ÿ—บ๏ธ Plรกn\n\nOmniRoute mรก **v plรกnu vรญce neลพ 210 funkcรญ** v nฤ›kolika fรกzรญch vรฝvoje. Zde jsou klรญฤovรฉ oblasti:\n\n| Kategorie | Plรกnovanรฉ funkce | Hlavnรญ body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| ๐Ÿง  **Smฤ›rovรกnรญ a inteligence** | 25+ | Smฤ›rovรกnรญ s nejniลพลกรญ latencรญ, smฤ›rovรกnรญ zaloลพenรฉ na tagech, kontrola kvรณt pล™ed vรฝstupem, vรฝbฤ›r รบฤtu P2C |\n| ๐Ÿ”’ **Zabezpeฤenรญ a dodrลพovรกnรญ pล™edpisลฏ** | 20+ | Zpevnฤ›nรญ SSRF, maskovรกnรญ pล™ihlaลกovacรญch รบdajลฏ, limit rychlosti pro kaลพdรฝ koncovรฝ bod, stanovenรญ rozsahu klรญฤลฏ pro sprรกvu |\n| ๐Ÿ“Š **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledovรกnรญ kvรณt v reรกlnรฉm ฤase, sledovรกnรญ nรกkladลฏ podle modelu |\n| ๐Ÿ”„ **Integrace poskytovatelลฏ** | 20+ | Dynamickรฝ registr modelลฏ, doba zchlazenรญ poskytovatelลฏ, Codex pro vรญce รบฤtลฏ, analรฝza kvรณt Copilota |\n| โšก **Vรฝkon** | 15+ | Dvojitรก vrstva mezipamฤ›ti, mezipamฤ›ลฅ vรฝzev, mezipamฤ›ลฅ odpovฤ›dรญ, udrลพovรกnรญ streamovรกnรญ, dรกvkovรฉ API |\n| ๐ŸŒ **Ekosystรฉm** | 10+ | WebSocket API, horkรฉ opฤ›tovnรฉ naฤรญtรกnรญ konfigurace, distribuovanรฉ รบloลพiลกtฤ› konfigurace, komerฤnรญ reลพim |\n\n### ๐Ÿ”œ Jiลพ brzy\n\n- ๐Ÿ”— **Integrace OpenCode** โ€” Nativnรญ podpora poskytovatelลฏ pro IDE kรณdovรกnรญ s AI v OpenCode\n- ๐Ÿ”— **Integrace TRAE** โ€” Plnรก podpora vรฝvojovรฉho rรกmce TRAE pro umฤ›lou inteligenci\n- ๐Ÿ“ฆ **Dรกvkovรฉ API** โ€” Asynchronnรญ dรกvkovรฉ zpracovรกnรญ hromadnรฝch poลพadavkลฏ\n- ๐ŸŽฏ **Smฤ›rovรกnรญ na zรกkladฤ› tagลฏ** โ€” Smฤ›rovรกnรญ poลพadavkลฏ na zรกkladฤ› vlastnรญch tagลฏ a metadat\n- ๐Ÿ’ฐ **Strategie nejniลพลกรญch nรกkladลฏ** โ€“ Automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n> ๐Ÿ“ รšplnรฉ specifikace funkcรญ jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobnรฝch specifikacรญ)\n\n---\n\n## ๐Ÿ‘ฅ Pล™ispฤ›vatelรฉ\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Pล™ispฤ›vatelรฉ](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak pล™ispฤ›t\n\n1. Vytvoล™enรญ forku repozitรกล™e\n2. Vytvoล™te si vlastnรญ vฤ›tev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrฤte zmฤ›ny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do vฤ›tve ( `git push origin feature/amazing-feature` )\n5. Otevล™รญt ลพรกdost o zmฤ›ny (pull request)\n\nPodrobnรฉ pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydรกnรญ novรฉ verze\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Hvฤ›zdnรก historie\n\n## Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## ๐Ÿ™ Podฤ›kovรกnรญ\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** โ€“ pลฏvodnรญmu projektu, kterรฝ inspiroval tento fork. OmniRoute stavรญ na tomto neuvฤ›ล™itelnรฉm zรกkladu s dalลกรญmi funkcemi, multimodรกlnรญmi API a kompletnรญm pล™epsรกnรญm TypeScriptu.\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€“ pลฏvodnรญ implementaci Go, kterรก inspirovala tento JavaScriptovรฝ port.\n\n---\n\n## ๐Ÿ“„ Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n
\n Vytvoล™eno s โค๏ธ pro vรฝvojรกล™e, kteล™รญ programujรญ 24 hodin dennฤ›, 7 dnรญ v tรฝdnu\n
\n

omniroute.online

\n
\n\n"}, "a5393a3ec4e717f2ef97fe4f66f3bc836c996ba2": {"t": 1785764460.8202274, "n": 92285, "h": "62d8b22a2a894095", "c": "# ๐Ÿš€ OmniRoute โ€” Bezplatnรก brรกna umฤ›lรฉ inteligence\n\n### Nikdy nepล™estรกvejte s kรณdovรกnรญm. Chytrรฉ smฤ›rovรกnรญ k **BEZPLATNรM a levnรฝm modelลฏm AI** s automatickรฝm pล™epรญnรกnรญm mezi zรกloลพnรญmi systรฉmy.\n\n_Vรกลก univerzรกlnรญ API proxy โ€“ jeden endpoint, vรญce neลพ 44 poskytovatelลฏ, nulovรฉ vรฝpadky. Nynรญ s orchestracรญ agentลฏ **MCP a A2A** ._\n\n**Dokonฤenรญ chatu โ€ข Vklรกdรกnรญ โ€ข Generovรกnรญ obrรกzkลฏ โ€ข Video โ€ข Hudba โ€ข Audio โ€ข Zmฤ›na poล™adรญ โ€ข **Vyhledรกvรกnรญ na webu** โ€ข MCP server โ€ข A2A protokol โ€ข 100% TypeScript**\n\n---\n\n
\n
\n

\"verze\"Docker\"Licence\"\"Webovรฉ\"WhatsApp\"

\n

๐ŸŒ Webovรฉ strรกnky โ€ข ๐Ÿš€ Rychlรฝ start โ€ข ๐Ÿ’ก Funkce โ€ข ๐Ÿ“– Dokumentace โ€ข ๐Ÿ’ฐ Cenรญk โ€ข ๐Ÿ’ฌ WhatsApp

\n
\n\n๐ŸŒ **Dostupnรฉ v:** ๐Ÿ‡บ๐Ÿ‡ธ [Angliฤtina](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n### ๐Ÿ†• What's New in v3.0.0\n\n| Area | Change |\n| -------------------------- | --------------------------------------------------------------------------------- |\n| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| โœ… **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |\n| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| ๐ŸŒ **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| ๐Ÿ”ง **926 Tests** | Full test suite passes with 0 failures |\n\n### ๐Ÿ†• What's New in v3.0.0\n\n| Area | Change |\n| -------------------------- | --------------------------------------------------------------------------------- |\n| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| โœ… **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |\n| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| ๐ŸŒ **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| ๐Ÿ”ง **926 Tests** | Full test suite passes with 0 failures |\n\n---\n\n## ๐Ÿ–ผ๏ธ Hlavnรญ ovlรกdacรญ panel\n\n
\"ล˜รญdicรญ
\n\n---\n\n## ๐Ÿ“ธ Nรกhled ล™รญdicรญho panelu\n\n
\nKliknutรญm zobrazรญte snรญmky obrazovky z ล™รญdicรญho panelu\n
\n\n| Strana | Snรญmek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelรฉ** | ![Poskytovatelรฉ](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdravรญ** | ![Zdravรญ](docs/screenshots/04-health.png) |\n| **Pล™ekladatel** | ![Pล™ekladatel](docs/screenshots/05-translator.png) |\n| **Nastavenรญ** | ![Nastavenรญ](docs/screenshots/06-settings.png) |\n| **Nรกstroje CLI** | ![Nรกstroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly pouลพรญvรกnรญ** | ![Pouลพรญvรกnรญ](docs/screenshots/08-usage.png) |\n| **Koncovรฉ body** | ![Koncovรฉ body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### ๐Ÿค– Bezplatnรฝ poskytovatel umฤ›lรฉ inteligence pro vaลกe oblรญbenรฉ programรกtory\n\n_Pล™ipojte libovolnรฝ nรกstroj IDE nebo CLI s umฤ›lou inteligencรญ pล™es OmniRoute โ€” bezplatnou API brรกnu pro neomezenรฉ kรณdovรกnรญ._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\"OpenClaw\"
OpenClaw
โญ 205 tisรญc 		\"NanoBot\"
NanoBot
โญ 20,9 tisรญc 		\"PicoClaw\"
PicoClaw
โญ 14,6 tisรญc 		\"ZeroClaw\"
ZeroClaw
โญ 9,9 tisรญc 		\"ลฝeleznรฝ
ลฝeleznรฝ drรกp
โญ 2,1 tisรญce
\"OpenCode\"
OpenCode
โญ 106 tisรญc 		\"Codex
Codex CLI
โญ 60,8 tisรญc 		\"Claude
Claude Code
โญ 67,3 tisรญc 		\"Gemini
Gemini CLI
โญ 94,7 tisรญc 		\"Kilo
Kilo kรณd
โญ 15,5 tisรญc
\n\n๐Ÿ“ก Vลกichni agenti se pล™ipojujรญ pล™es http://localhost:20128/v1 nebo http://cloud.omniroute.online/v1 โ€” jedna konfigurace, neomezenรฉ modely a kvรณty\n\n---\n\n## ๐Ÿค” Proฤ OmniRoute?\n\n**Pล™estaลˆte plรฝtvat penฤ›zi a narรกลพet na limity:**\n\n- Kvรณta pล™edplatnรฉho vyprลกรญ kaลพdรฝ mฤ›sรญc\n- Limity rychlosti vรกm zabrรกnรญ v kรณdovรกnรญ\n- Drahรก API (20โ€“50 USD/mฤ›sรญc na poskytovatele)\n- Ruฤnรญ pล™epรญnรกnรญ mezi poskytovateli\n\n**OmniRoute to ล™eลกรญ:**\n\n- โœ… **Maximalizujte pล™edplatnรฉ** โ€“ Sledujte kvรณtu, vyuลพijte kaลพdou ฤรกstku pล™ed resetovรกnรญm\n- โœ… **Automatickรฉ zรกloลพnรญ** โ€“ Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma, ลพรกdnรฉ vรฝpadky\n- โœ… **Vรญce รบฤtลฏ** โ€“ Round-robin mezi รบฤty u jednotlivรฝch poskytovatelลฏ\n- โœ… **Univerzรกlnรญ** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakรฝmkoli nรกstrojem CLI\n\n---\n\n## ๐Ÿ“ง Podpora\n\n> ๐Ÿ’ฌ **Pล™idejte se k naลกรญ komunitฤ›!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Zรญskejte pomoc, sdรญlejte tipy a buฤte v obraze.\n\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problรฉmy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitnรญ skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Pล™ispรญvรกnรญ** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevล™ete ลพรกdost o pล™รญspฤ›vek nebo si vyberte `good first issue`\n- **Pลฏvodnรญ projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Hlรกsรญte chybu?\n\nPล™i otevรญrรกnรญ problรฉmu spusลฅte pล™รญkaz system-info a pล™iloลพte vygenerovanรฝ soubor:\n\n```bash\nnpm run system-info\n```\n\nTรญm se vygeneruje soubor `system-info.txt` s verzรญ Node.js, verzรญ OmniRoute, podrobnostmi o operaฤnรญm systรฉmu, nainstalovanรฝmi nรกstroji CLI (qoder, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systรฉmovรฝmi balรญฤky โ€“ vลกe, co potล™ebujeme k rychlรฉ reprodukci vaลกeho problรฉmu. Soubor pล™iloลพte pล™รญmo k vaลกemu problรฉmu na GitHubu.\n\n---\n\n## ๐Ÿ”„ Jak to funguje\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ Co ล™eลกรญ OmniRoute โ€” 30 skuteฤnรฝch problรฉmลฏ a pล™รญpadลฏ pouลพitรญ\n\n> **Kaลพdรฝ vรฝvojรกล™ pouลพรญvajรญcรญ nรกstroje umฤ›lรฉ inteligence se s tฤ›mito problรฉmy setkรกvรก dennฤ›.** OmniRoute byl vytvoล™en tak, aby je vลกechny vyล™eลกil โ€“ od pล™ekroฤenรญ nรกkladลฏ po regionรกlnรญ bloky, od nefunkฤnรญch tokลฏ OAuth aลพ po operace s protokoly a sledovatelnost v podniku.\n\n
\n๐Ÿ’ธ 1. โ€žPlatรญm si drahรฉ pล™edplatnรฉ, ale stรกle mฤ› ruลกรญ limityโ€œ\n
\n\nVรฝvojรกล™i platรญ za Claude Pro, Codex Pro nebo GitHub Copilot 20โ€“200 dolarลฏ mฤ›sรญฤnฤ›. I pล™i platbฤ› mรก kvรณta strop โ€“ 5 hodin pouลพรญvรกnรญ, tรฝdennรญ limity nebo limity rychlosti za minutu. Uprostล™ed kรณdovacรญ relace poskytovatel pล™estane reagovat a vรฝvojรกล™ ztrรกcรญ plynulost a produktivitu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Inteligentnรญ ฤtyล™รบrovลˆovรก zรกloลพnรญ sluลพba** โ€“ Pokud dojde kvรณta pล™edplatnรฉho, โ€‹โ€‹automaticky se pล™esmฤ›ruje na API klรญฤ โ†’ Levnรฉ โ†’ Zdarma bez manuรกlnรญho zรกsahu\n- **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** โ€“ Zobrazuje spotล™ebu tokenลฏ v reรกlnรฉm ฤase s odpoฤรญtรกvรกnรญm resetovรกnรญ (5 hodin, dennฤ›, tรฝdnฤ›)\n- **Podpora vรญce รบฤtลฏ** โ€“ Vรญce รบฤtลฏ u jednoho poskytovatele s automatickรฝm pล™epรญnรกnรญm โ€“ kdyลพ jeden dojde, pล™epne se na dalลกรญ\n- **Vlastnรญ kombinace** โ€” Pล™izpลฏsobitelnรฉ zรกloลพnรญ ล™etฤ›zce se 6 strategiemi vyvaลพovรกnรญ (fill-first, round robin, P2C, nรกhodnรฉ, nejmรฉnฤ› pouลพรญvanรฉ, nรกkladovฤ› optimalizovanรฉ)\n- **Codex Business Quotas** โ€” Sledovรกnรญ kvรณt pracovnรญho prostoru firmy/tรฝmu pล™รญmo v dashboardu\n\n
\n๐Ÿ”Œ 2. โ€žPotล™ebuji pouลพรญt vรญce poskytovatelลฏ, ale kaลพdรฝ mรก jinรฉ APIโ€œ\n
\n\nOpenAI pouลพรญvรก jeden formรกt, Claude (Anthropic) jinรฝ a Gemini jeลกtฤ› tล™etรญ. Pokud chce vรฝvojรกล™ testovat modely od rลฏznรฝch poskytovatelลฏ nebo mezi nimi pล™echรกzet, musรญ pล™ekonfigurovat SDK, zmฤ›nit koncovรฉ body a vypoล™รกdat se s nekompatibilnรญmi formรกty. Vlastnรญ poskytovatelรฉ (FriendLI, NIM) majรญ nestandardnรญ koncovรฉ body modelลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sjednocenรฝ koncovรฝ bod** โ€” Jeden `http://localhost:20128/v1` slouลพรญ jako proxy pro vลกech 67+ poskytovatelลฏ.\n- **Pล™eklad formรกtu** โ€” Automatickรฝ a transparentnรญ: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Sanitizace odpovฤ›dรญ** โ€” Odstraลˆuje nestandardnรญ pole ( `x_groq` , `usage_breakdown` , `service_tier` ), kterรก poruลกujรญ OpenAI SDK v1.83+\n- **Normalizace rolรญ** โ€” Pล™evรกdรญ `developer` โ†’ `system` pro poskytovatele bez OpenAI; `system` โ†’ `user` pro GLM/ERNIE\n- **Extrakce tagลฏ Think** โ€” Extrahuje bloky `` z modelลฏ, jako je DeepSeek R1, do standardizovanรฉho `reasoning_content`\n- **Strukturovanรฝ vรฝstup pro Gemini** โ€” `json_schema` โ†’ automatickรก konverze `responseMimeType` / `responseSchema`\n- **Vรฝchozรญ hodnota `stream` je `false`** โ€“ Odpovรญdรก specifikaci OpenAI, ฤรญmลพ se zabrรกnรญ neoฤekรกvanรฉmu SSE v Python/Rust/Go SDK.\n\n
\n๐ŸŒ 3. โ€žMลฏj poskytovatel AI blokuje mลฏj region/zemiโ€œ\n
\n\nPoskytovatelรฉ jako OpenAI/Codex blokujรญ pล™รญstup z urฤitรฝch geografickรฝch oblastรญ. Uลพivatelรฉ se bฤ›hem pล™ipojenรญ OAuth a API dostรกvajรญ k chybรกm jako `unsupported_country_region_territory` . To je obzvlรกลกtฤ› frustrujรญcรญ pro vรฝvojรกล™e z rozvojovรฝch zemรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **3รบrovลˆovรก konfigurace proxy** โ€“ Konfigurovatelnรก proxy na 3 รบrovnรญch: globรกlnรญ (veลกkerรฝ provoz), pro jednotlivรฉ poskytovatele (pouze jeden poskytovatel) a pro jednotlivรฉ pล™ipojenรญ/klรญฤ\n- **Barevnฤ› kรณdovanรฉ odznaky proxy** โ€“ Vizuรกlnรญ indikรกtory: ๐ŸŸข globรกlnรญ proxy, ๐ŸŸก proxy poskytovatele, ๐Ÿ”ต proxy pล™ipojenรญ, vลพdy zobrazujรญcรญ IP adresu\n- **Vรฝmฤ›na tokenลฏ OAuth prostล™ednictvรญm proxy** โ€“ tok OAuth takรฉ prochรกzรญ pล™es proxy, ฤรญmลพ se ล™eลกรญ `unsupported_country_region_territory`\n- **Testy pล™ipojenรญ pล™es proxy** โ€“ Testy pล™ipojenรญ pouลพรญvajรญ nakonfigurovanรฝ proxy (jiลพ ลพรกdnรฉ pล™รญmรฉ obchรกzenรญ)\n- **Podpora SOCKS5** โ€” Plnรก podpora proxy SOCKS5 pro odchozรญ smฤ›rovรกnรญ\n- **TLS Fingerprint Spoofing** โ€” Otisk prstu TLS podobnรฝ prohlรญลพeฤi pomocรญ `wreq-js` pro obchรกzenรญ detekce botลฏ\n- **๐Ÿ” Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** โ€” Zmฤ›nรญ poล™adรญ zรกhlavรญ a polรญ v tฤ›le serveru tak, aby odpovรญdala nativnรญm binรกrnรญm podpisลฏm v CLI, ฤรญmลพ drasticky sniลพuje riziko nahlaลกovรกnรญ รบฤtu. IP adresa proxy je zachovรกna โ€” zรญskรกte souฤasnฤ› stealth **i** maskovรกnรญ IP adresy.\n\n
\n๐Ÿ†“ 4. โ€žChci pouลพรญvat umฤ›lou inteligenci pro kรณdovรกnรญ, ale nemรกm penรญzeโ€œ\n
\n\nNe kaลพdรฝ si mลฏลพe dovolit zaplatit 20โ€“200 dolarลฏ mฤ›sรญฤnฤ› za pล™edplatnรฉ AI. Studenti, vรฝvojรกล™i z rozvรญjejรญcรญch se zemรญ, amatรฉล™i a freelanceล™i potล™ebujรญ pล™รญstup ke kvalitnรญm modelลฏm za nulovou cenu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vestavฤ›nรญ poskytovatelรฉ bezplatnรฉ รบrovnฤ›** โ€” Nativnรญ podpora pro 100% bezplatnรฉ poskytovatele: Qoder (5 neomezenรฝch modelลฏ pล™es OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezenรฉ modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisรญc tokenลฏ/mฤ›sรญc zdarma)\n- **Ollama Cloud** โ€” Cloudovฤ› hostovanรฉ modely Ollama na `api.ollama.com` s bezplatnou รบrovnรญ โ€žLight usageโ€œ; pouลพijte prefix `ollamacloud/`\n- **Kombinace pouze zdarma** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = 0 $/mฤ›sรญc s nulovรฝmi prostoji\n- **NVIDIA NIM Free Access** โ€” ~40 RPM developerskรฝ pล™รญstup k vรญce neลพ 70 modelลฏm na build.nvidia.com (pล™echod z kreditลฏ na ฤistรฉ limity rychlosti)\n- **Strategie optimalizace nรกkladลฏ** โ€“ Strategie smฤ›rovรกnรญ, kterรก automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n
\n๐Ÿ”’ 5. โ€žPotล™ebuji chrรกnit svou brรกnu umฤ›lรฉ inteligence pล™ed neoprรกvnฤ›nรฝm pล™รญstupemโ€œ\n
\n\nPล™i zpล™รญstupnฤ›nรญ brรกny umฤ›lรฉ inteligence sรญti (LAN, VPS, Docker) mลฏลพe kdokoli s adresou spotล™ebovat tokeny/kvรณtu vรฝvojรกล™e. Bez ochrany jsou API zranitelnรก vลฏฤi zneuลพitรญ, prompt injection a dalลกรญmu zneuลพitรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sprรกva klรญฤลฏ API** โ€“ generovรกnรญ, rotace a vymezovรกnรญ rozsahu pro kaลพdรฉho poskytovatele s vyhrazenou strรกnkou `/dashboard/api-manager`\n- **Oprรกvnฤ›nรญ na รบrovni modelu** โ€“ Omezenรญ klรญฤลฏ API na konkrรฉtnรญ modely ( `openai/*` , zรกstupnรฉ znaky) pomocรญ pล™epรญnaฤe Povolit vลกe/Omezit\n- **Ochrana koncovรฝch bodลฏ API** โ€“ Vyลพaduje klรญฤ pro `/v1/models` a blokuje konkrรฉtnรญ poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** โ€” Vลกechny trasy dashboardu chrรกnฤ›nรฉ middlewarem `withAuth` + tokeny CSRF\n- **Omezovaฤ rychlosti** โ€” Omezovรกnรญ rychlosti na IP s konfigurovatelnรฝmi okny\n- **Filtrovรกnรญ IP adres** โ€” Seznam povolenรฝch/blokovanรฝch adres pro ล™รญzenรญ pล™รญstupu\n- **Ochrana proti vklรกdรกnรญ vรฝzev** โ€“ Sanitizace proti ลกkodlivรฝm vzorcลฏm vรฝzev\n- **ล ifrovรกnรญ AES-256-GCM** โ€“ pล™ihlaลกovacรญ รบdaje jsou v klidovรฉm stavu ลกifrovรกny\n\n
\n๐Ÿ›‘ 6. โ€žMลฏj poskytovatel selhal a jรก ztratil/a programovacรญ tokโ€œ\n
\n\nPoskytovatelรฉ umฤ›lรฉ inteligence se mohou stรกt nestabilnรญmi, vracet chyby 5xx nebo dosรกhnout doฤasnรฝch limitลฏ rychlosti. Pokud je vรฝvojรกล™ zรกvislรฝ na jedinรฉm poskytovateli, je jeho prรกce pล™eruลกena. Bez jistiฤลฏ mลฏลพe opakovanรฉ pokusy vรฉst k pรกdu aplikace.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Jistiฤ pro kaลพdรฝ model** โ€“ Automatickรฉ otevรญrรกnรญ/zavรญrรกnรญ s konfigurovatelnรฝmi prahovรฝmi hodnotami a dobou ochlazovรกnรญ (Zavล™eno/Otevล™eno/Poloviฤnรญ otevล™enรญ), rozsah definovanรฝ pro kaลพdรฝ model, aby se zabrรกnilo kaskรกdovรกnรญ blokลฏ\n- **Exponenciรกlnรญ odklad** โ€” Progresivnรญ zpoลพdฤ›nรญ opakovรกnรญ\n- **Anti-Thundering Herd** โ€” ochrana Mutex + semafor proti soubฤ›ลพnรฝm bouล™รญm s opakovanรฝmi pokusy\n- **Kombinovanรฉ zรกloลพnรญ ล™etฤ›zce** โ€“ Pokud primรกrnรญ poskytovatel selลพe, automaticky se propadne ล™etฤ›zcem bez zรกsahu.\n- **Kombinovanรฝ jistiฤ** โ€“ Automaticky deaktivuje selhรกvajรญcรญho poskytovatele v rรกmci kombinovanรฉho ล™etฤ›zce\n- **Dashboard stavu** โ€” Monitorovรกnรญ provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti, latence p50/p95/p99\n\n
\n๐Ÿ”ง 7. โ€žKonfigurace kaลพdรฉho nรกstroje umฤ›lรฉ inteligence je zdlouhavรก a opakujรญcรญ seโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Kaลพdรฝ nรกstroj potล™ebuje jinou konfiguraci (API endpoint, klรญฤ, model). Pล™ekonfigurovรกnรญ pล™i zmฤ›nฤ› poskytovatele nebo modelu je ztrรกta ฤasu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel nรกstrojลฏ CLI** โ€” Vyhrazenรก strรกnka s nastavenรญm jednรญm kliknutรญm pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generรกtor konfigurace GitHub Copilot** โ€“ Generuje `chatLanguageModels.json` pro VS Code s hromadnรฝm vรฝbฤ›rem modelu\n- **Prลฏvodce zavรกdฤ›nรญm** โ€“ 4krokovรฉ nastavenรญ pro zaฤรญnajรญcรญ uลพivatele\n- **Jeden koncovรฝ bod, vลกechny modely** โ€“ jednou nakonfigurujte `http://localhost:20128/v1` a zรญskejte pล™รญstup k vรญce neลพ 44 poskytovatelลฏm\n\n
\n๐Ÿ”‘ 8. โ€žSprรกva OAuth tokenลฏ od vรญce poskytovatelลฏ je pekloโ€œ\n
\n\nClaude Code, Codex, Gemini CLI, Copilot โ€“ vลกechny pouลพรญvajรญ OAuth 2.0 s tokeny s vyprลกenรญm platnosti. Vรฝvojรกล™i se musรญ neustรกle znovu autentizovat, ล™eลกit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdรกlenรฝch serverech. Obzvlรกลกtฤ› problematickรฝ je OAuth v LAN/VPS.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Automatickรก aktualizace tokenลฏ** โ€“ Tokeny OAuth se obnovujรญ na pozadรญ pล™ed vyprลกenรญm platnosti.\n- **Vestavฤ›nรฝ OAuth 2.0 (PKCE)** โ€“ Automatickรฝ tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder\n- **Multi-Account OAuth** โ€” Vรญce รบฤtลฏ na poskytovatele prostล™ednictvรญm extrakce tokenลฏ JWT/ID\n- **OAuth LAN/Remote Fix** โ€” Detekce privรกtnรญ IP adresy pro `redirect_uri` + manuรกlnรญ reลพim URL pro vzdรกlenรฉ servery\n- **OAuth Behind Nginx** โ€” Pouลพรญvรก `window.location.origin` pro kompatibilitu s reverznรญ proxy\n- **Prลฏvodce vzdรกlenรฝm OAuth** โ€“ Podrobnรฝ nรกvod k pล™ihlaลกovacรญm รบdajลฏm Google Cloud na VPS/Dockeru\n\n
\n๐Ÿ“Š 9. โ€žNevรญm, kolik utrรกcรญm ani kdeโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ vรญce placenรฝch poskytovatelลฏ, ale nemajรญ jednotnรฝ pล™ehled o vรฝdajรญch. Kaลพdรฝ poskytovatel mรก svลฏj vlastnรญ fakturaฤnรญ panel, ale neexistuje ลพรกdnรฝ konsolidovanรฝ pล™ehled. Mohou se hromadit neoฤekรกvanรฉ nรกklady.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard pro analรฝzu nรกkladลฏ** โ€“ Sledovรกnรญ nรกkladลฏ na token a sprรกva rozpoฤtu pro kaลพdรฉho poskytovatele\n- **Rozpoฤtovรฉ limity na รบroveลˆ** โ€“ Strop vรฝdajลฏ na รบroveลˆ, kterรฝ spouลกtรญ automatickรฝ zรกloลพnรญ reลพim\n- **Konfigurace cen podle modelu** โ€“ Konfigurovatelnรฉ ceny podle modelu\n- **Statistiky pouลพitรญ pro kaลพdรฝ klรญฤ API** โ€” Poฤet poลพadavkลฏ a ฤasovรฉ razรญtko poslednรญho pouลพitรญ pro kaลพdรฝ klรญฤ\n- **Analytickรฝ panel** โ€“ Statistickรฉ karty, graf vyuลพitรญ modelu, tabulka poskytovatelลฏ s mรญrou รบspฤ›ลกnosti a latencรญ\n\n
\n๐Ÿ› 10. โ€žNedokรกลพu diagnostikovat chyby a problรฉmy ve volรกnรญ umฤ›lรฉ inteligence.โ€œ\n
\n\nKdyลพ volรกnรญ selลพe, vรฝvojรกล™ nevรญ, zda se jednalo o limit rychlosti, vyprลกelรฝ token, ลกpatnรฝ formรกt nebo chybu poskytovatele. Fragmentovanรฉ protokoly napล™รญฤ rลฏznรฝmi terminรกly. Bez sledovatelnosti je ladฤ›nรญ metodou pokus-omyl.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel jednotnรฝch protokolลฏ** โ€“ 4 karty: Protokoly poลพadavkลฏ, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlรญลพeฤ protokolลฏ konzole** โ€” Prohlรญลพeฤ protokolลฏ v reรกlnรฉm ฤase ve stylu terminรกlu s barevnฤ› kรณdovanรฝmi รบrovnฤ›mi, automatickรฝm posouvรกnรญm, vyhledรกvรกnรญm a filtrovรกnรญm\n- **Protokoly proxy SQLite** โ€“ trvalรฉ protokoly, kterรฉ pล™eลพijรญ restart serveru\n- **Pล™ekladaฤskรฉ hล™iลกtฤ›** โ€” 4 reลพimy ladฤ›nรญ: Hล™iลกtฤ› (pล™eklad formรกtu), Tester chatu (okruลพnรญ), Testovacรญ stลฏl (dรกvkovรฝ), ลฝivรฝ monitor (v reรกlnรฉm ฤase)\n- **Telemetrie poลพadavkลฏ** โ€” latence p50/p95/p99 + trasovรกnรญ X-Request-Id\n- **Souborovรฉ protokolovรกnรญ s rotacรญ** โ€“ Konzolovรฝ interceptor zachycuje vลกe do protokolu JSON s rotacรญ na zรกkladฤ› velikosti\n- **Zprรกva o systรฉmovรฝch informacรญch** โ€” pล™รญkaz `npm run system-info` vygeneruje `system-info.txt` s kompletnรญm popisem vaลกeho prostล™edรญ (verze uzlu, verze OmniRoute, operaฤnรญ systรฉm, nรกstroje CLI, stav Dockeru/PM2). Pล™iloลพte jej pล™i hlรกลกenรญ problรฉmลฏ pro okamลพitรฉ tล™รญdฤ›nรญ.\n\n
\n๐Ÿ—๏ธ 11. โ€žNasazenรญ a รบdrลพba brรกny je sloลพitรกโ€œ\n
\n\nInstalace, konfigurace a รบdrลพba AI proxy v rลฏznรฝch prostล™edรญch (lokรกlnรญ, VPS, Docker, cloud) je pracnรก. Problรฉmy, jako jsou pevnฤ› zakรณdovanรฉ cesty, `EACCES` u adresรกล™ลฏ, konflikty portลฏ a multiplatformnรญ sestavenรญ, pล™ispรญvajรญ k obtรญลพรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **npm globรกlnรญ instalace** โ€” `npm install -g omniroute && omniroute` โ€” hotovo\n- **Docker Multi-Platform** โ€” AMD64 + nativnรญ ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** โ€” `base` (bez nรกstrojลฏ CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopovรก aplikace Electron** โ€” Nativnรญ aplikace pro Windows/macOS/Linux se systรฉmovou liลกtou, automatickรฝm spuลกtฤ›nรญm a offline reลพimem\n- **Reลพim rozdฤ›lenรฝch portลฏ** โ€“ API a ล™รญdicรญ panel na samostatnรฝch portech pro pokroฤilรฉ scรฉnรกล™e (reverznรญ proxy, sรญลฅovรกnรญ kontejnerลฏ)\n- **Cloud Sync** โ€“ Konfigurace synchronizace mezi zaล™รญzenรญmi pomocรญ Cloudflare Workers\n- **Zรกlohy databรกzรญ** โ€” Automatickรฉ zรกlohovรกnรญ, obnovenรญ, export a import vลกech nastavenรญ\n\n
\n๐ŸŒ 12. โ€žRozhranรญ je pouze v angliฤtinฤ› a mลฏj tรฝm nemluvรญ anglickyโ€œ\n
\n\nTรฝmy v neanglicky mluvรญcรญch zemรญch, zejmรฉna v Latinskรฉ Americe, Asii a Evropฤ›, se potรฝkajรญ s rozhranรญmi pouze v angliฤtinฤ›. Jazykovรฉ bariรฉry sniลพujรญ mรญru pล™ijetรญ a zvyลกujรญ chyby v konfiguraci.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard i18n โ€” 30 jazykลฏ** โ€” Vลกech 500+ klรกves je pล™eloลพeno vฤetnฤ› arabลกtiny, bulharลกtiny, dรกnลกtiny, nฤ›mฤiny, ลกpanฤ›lลกtiny, finลกtiny, francouzลกtiny, hebrejลกtiny, hindลกtiny, maฤarลกtiny, indonรฉลกtiny, italลกtiny, japonลกtiny, korejลกtiny, malajลกtiny, holandลกtiny, norลกtiny, polลกtiny, portugalลกtiny (PT/BR), rumunลกtiny, ruลกtiny, slovenลกtiny, ลกvรฉdลกtiny, thajลกtiny, ukrajinลกtiny, vietnamลกtiny, ฤรญnลกtiny, filipรญnลกtiny a angliฤtiny\n- **Podpora RTL** โ€“ Podpora psanรญ zprava doleva pro arabลกtinu a hebrejลกtinu\n- **Vรญcejazyฤnรฉ soubory README** โ€” 30 kompletnรญch pล™ekladลฏ dokumentace\n- **Vรฝbฤ›r jazyka** โ€” Ikona glรณbu v zรกhlavรญ pro pล™epรญnรกnรญ v reรกlnรฉm ฤase\n\n
\n๐Ÿ”„ 13. โ€žPotล™ebuji vรญc neลพ jen chat โ€“ potล™ebuji vloลพenรฉ soubory, obrรกzky, zvuk.โ€œ\n
\n\nUmฤ›lรก inteligence nenรญ jen dokonฤovรกnรญ chatu. Vรฝvojรกล™i potล™ebujรญ generovat obrรกzky, pล™episovat zvuk, vytvรกล™et embeddedy pro RAG, mฤ›nit poล™adรญ dokumentลฏ a moderovat obsah. Kaลพdรฉ API mรก jinรฝ koncovรฝ bod a formรกt.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vklรกdรกnรญ** โ€” `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generovรกnรญ obrรกzkลฏ** โ€” `/v1/images/generations` s 10 poskytovateli a vรญce neลพ 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Pล™evod textu na video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Pล™evod textu na hudbu** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Pล™epis zvuku** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Pล™evod textu na ล™eฤ** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a dalลกรญ stรกvajรญcรญ poskytovatelรฉ\n- **Moderovรกnรญ** โ€” `/v1/moderations` โ€” Kontroly bezpeฤnosti obsahu\n- **Zmฤ›na poล™adรญ** โ€” `/v1/rerank` โ€” Zmฤ›na poล™adรญ relevance dokumentu\n- **Responses API** โ€” Plnรก podpora `/v1/responses` pro Codex\n\n
\n๐Ÿงช 14. โ€žNemรกm zpลฏsob, jak testovat a porovnรกvat kvalitu napล™รญฤ modely.โ€œ\n
\n\nVรฝvojรกล™i chtฤ›jรญ vฤ›dฤ›t, kterรฝ model je pro jejich pล™รญpad pouลพitรญ nejlepลกรญ โ€“ kรณd, pล™eklad, uvaลพovรกnรญ โ€“ ale ruฤnรญ porovnรกvรกnรญ je pomalรฉ. Neexistujรญ ลพรกdnรฉ integrovanรฉ nรกstroje pro vyhodnocovรกnรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Hodnocenรญ LLM** โ€” Testovรกnรญ Golden setu s 10 pล™edinstalovanรฝmi pล™รญpady zahrnujรญcรญmi pozdravy, matematiku, geografii, generovรกnรญ kรณdu, dodrลพovรกnรญ JSON, pล™eklad, markdown, odmรญtnutรญ bezpeฤnostnรญch poลพadavkลฏ\n- **4 strategie shody** โ€” `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovacรญ lavice pro pล™ekladatelskรฉ hล™iลกtฤ›** โ€” Dรกvkovรฉ testovรกnรญ s vรญce vstupy a oฤekรกvanรฝmi vรฝstupy, porovnรกnรญ napล™รญฤ poskytovateli\n- **Tester chatu** โ€” Kompletnรญ okruลพnรญ cesta s vizuรกlnรญm vykreslovรกnรญm odpovฤ›dรญ\n- **ลฝivรฝ monitor** โ€” Stream vลกech poลพadavkลฏ prochรกzejรญcรญch proxy serverem v reรกlnรฉm ฤase\n\n
\n๐Ÿ“ˆ 15. โ€žPotล™ebuji ลกkรกlovat bez ztrรกty vรฝkonuโ€œ\n
\n\nS rostoucรญm objemem poลพadavkลฏ generujรญ stejnรฉ otรกzky bez uklรกdรกnรญ do mezipamฤ›ti duplicitnรญ nรกklady. Bez idempotence duplicitnรญ poลพadavky plรฝtvajรญ zpracovรกnรญm. Je nutnรฉ dodrลพovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sรฉmantickรก mezipamฤ›ลฅ** โ€” Dvouvrstvรก mezipamฤ›ลฅ (signatura + sรฉmantika) sniลพuje nรกklady a latenci\n- **Idempotence poลพadavku** โ€” 5s deduplikaฤnรญ okno pro identickรฉ poลพadavky\n- **Detekce limitu rychlosti** โ€“ sledovรกnรญ otรกฤek za minutu (RPM), minimรกlnรญ mezera a maximรกlnรญ soubฤ›ลพnรฉ sledovรกnรญ pro kaลพdรฉho poskytovatele\n- **Upravitelnรฉ limity rychlosti** โ€” Konfigurovatelnรฉ vรฝchozรญ hodnoty v Nastavenรญ โ†’ Odolnost s perzistencรญ\n- **Mezipamฤ›ลฅ pro ovฤ›ล™enรญ klรญฤลฏ API** โ€” tล™รญvrstvรก mezipamฤ›ลฅ pro vรฝkon produkฤnรญho prostล™edรญ\n- **Dashboard s telemetriรญ** โ€“ latence p50/p95/p99, statistiky mezipamฤ›ti, dostupnost\n\n
\n๐Ÿค– 16. โ€žChci mรญt chovรกnรญ modelลฏ globรกlnฤ› pod kontrolouโ€œ\n
\n\nVรฝvojรกล™i, kteล™รญ chtฤ›jรญ vลกechny odpovฤ›di v urฤitรฉm jazyce, se specifickรฝm tรณnem nebo chtฤ›jรญ omezit tokeny pro uvaลพovรกnรญ. Konfigurace tรฉto funkce v kaลพdรฉm nรกstroji/poลพadavku je nepraktickรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vloลพenรญ systรฉmovรฉho prompt** โ€“ Globรกlnรญ prompt aplikovanรฝ na vลกechny poลพadavky\n- **Validace rozpoฤtu Thinking** โ€” ล˜รญzenรญ alokace tokenลฏ na poลพadavek (prลฏchozรญ, automatickรฉ, vlastnรญ, adaptivnรญ)\n- **6 strategiรญ smฤ›rovรกnรญ** โ€“ Globรกlnรญ strategie, kterรฉ urฤujรญ, jak jsou poลพadavky distribuovรกny\n- **Smฤ›rovaฤ se zรกstupnรฝmi znaky** โ€” vzory `provider/*` dynamicky smฤ›rujรญ k libovolnรฉmu poskytovateli\n- **Pล™epรญnรกnรญ povolenรญ/zakรกzรกnรญ kombinacรญ** โ€“ Pล™epรญnรกnรญ kombinacรญ pล™รญmo z ล™รญdicรญho panelu\n- **Pล™epรญnรกnรญ poskytovatele** โ€“ Povolenรญ/zakรกzรกnรญ vลกech pล™ipojenรญ pro poskytovatele jednรญm kliknutรญm\n- **Blokovanรญ poskytovatelรฉ** โ€“ Vylouฤenรญ konkrรฉtnรญch poskytovatelลฏ ze seznamu `/v1/models`\n\n
\n๐Ÿงฐ 17. โ€žPotล™ebuji nรกstroje MCP jako prvotล™รญdnรญ produktovรฉ funkce.โ€œ\n
\n\nMnoho bran umฤ›lรฉ inteligence odhaluje MCP pouze jako skrytรฝ implementaฤnรญ detail. Tรฝmy potล™ebujรญ viditelnou a spravovatelnou operaฤnรญ vrstvu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- MCP se zobrazuje v navigaci na ล™รญdicรญm panelu a na kartฤ› protokolu koncovรฉho bodu.\n- Vyhrazenรก strรกnka pro sprรกvu MCP s procesy, nรกstroji, rozsahy a auditem\n- Vestavฤ›nรฝ rychlรฝ start pro `omniroute --mcp` a onboarding klienta\n\n
\n๐Ÿง  18. โ€žPotล™ebuji orchestraci A2A se synchronizacรญ a cestami รบloh streamu.โ€œ\n
\n\nPracovnรญ postupy agentลฏ vyลพadujรญ jak pล™รญmรฉ odpovฤ›di, tak dlouhodobรฉ streamovanรฉ provรกdฤ›nรญ s kontrolou ลพivotnรญho cyklu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Koncovรฝ bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamovรกnรญ SSE s ลกรญล™enรญm stavu terminรกlu\n- Rozhranรญ API ลพivotnรญho cyklu รบloh pro `tasks/get` a `tasks/cancel`\n\n
\n๐Ÿ›ฐ๏ธ 19. โ€žPotล™ebuji skuteฤnรฝ stav procesu MCP, ne odhadovanรฝ stav.โ€œ\n
\n\nProvoznรญ tรฝmy potล™ebujรญ vฤ›dฤ›t, zda je MCP skuteฤnฤ› aktivnรญ, nejen zda je API dosaลพitelnรฉ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Soubor bฤ›hovรฉho heartbeatu s PID, ฤasovรฝmi razรญtky, transportem, poฤtem nรกstrojลฏ a reลพimem rozsahu\n- API stavu MCP kombinujรญcรญ prezenฤnรญ signรกl a nedรกvnou aktivitu\n- Karty stavu uลพivatelskรฉho rozhranรญ pro zobrazenรญ aktuรกlnosti procesลฏ/provozuschopnosti/prezenฤnรญho signรกlu\n\n
\n๐Ÿ“‹ 20. โ€žPotล™ebuji auditovatelnรฉ provedenรญ nรกstroje MCPโ€œ\n
\n\nKdyลพ nรกstroje mฤ›nรญ konfiguraci nebo spouลกtฤ›jรญ operaฤnรญ akce, tรฝmy potล™ebujรญ forenznรญ sledovatelnost.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Protokolovรกnรญ auditu pro volรกnรญ nรกstrojลฏ MCP s podporou SQLite\n- Filtruje podle nรกstroje, รบspฤ›chu/neรบspฤ›chu, klรญฤe API a strรกnkovรกnรญ\n- Tabulka auditu dashboardu + koncovรฉ body statistik pro automatizaci\n\n
\n๐Ÿ” 21. โ€žPotล™ebuji omezenรก oprรกvnฤ›nรญ MCP pro kaลพdou integraci.โ€œ\n
\n\nRลฏznรญ klienti by mฤ›li mรญt pล™รญstup ke kategoriรญm nรกstrojลฏ s nejniลพลกรญmi oprรกvnฤ›nรญmi.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- 9 detailnรญch MCP sond pro kontrolovanรฝ pล™รญstup k nรกstrojลฏm\n- Vynucenรญ rozsahu a viditelnost v uลพivatelskรฉm rozhranรญ sprรกvy MCP\n- Bezpeฤnรก vรฝchozรญ poloha pro provoznรญ nรกstroje\n\n
\nโš™๏ธ 22. โ€žPotล™ebuji provoznรญ kontroly bez nutnosti pล™esouvรกnรญโ€œ\n
\n\nTรฝmy potล™ebujรญ rychlรฉ zmฤ›ny v bฤ›hovรฉm prostล™edรญ bฤ›hem incidentลฏ nebo nรกkladovรฝch udรกlostรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Pล™epnฤ›te aktivaci komba pล™รญmo z ล™รญdicรญho panelu MCP\n- Pouลพรญvejte profily odolnosti z pล™eddefinovanรฝch balรญฤkลฏ zรกsad\n- Resetujte stav jistiฤe ze stejnรฉho ovlรกdacรญho panelu\n\n
\n๐Ÿ”„ 23. โ€žPotล™ebuji ลพivรฝ pล™ehled o ลพivotnรญm cyklu รบkolลฏ A2A a jejich zruลกenรญ.โ€œ\n
\n\nBez pล™ehledu o ลพivotnรญm cyklu je obtรญลพnรฉ tล™รญdit incidenty รบkolลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Vรฝpis/filtrovรกnรญ รบkolลฏ podle stรกtu/dovednosti s strรกnkovรกnรญm\n- Podrobnรฝ pล™ehled metadat รบloh, udรกlostรญ a artefaktลฏ\n- Koncovรฝ bod zruลกenรญ รบlohy a akce uลพivatelskรฉho rozhranรญ s potvrzenรญm\n\n
\n๐ŸŒŠ 24. โ€žPotล™ebuji metriky aktivnรญho streamu pro A2A zรกtฤ›ลพโ€œ\n
\n\nStreamovacรญ pracovnรญ postupy vyลพadujรญ provoznรญ pล™ehled o soubฤ›ลพnosti a ลพivรฝch pล™ipojenรญch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- ฤŒรญtaฤe aktivnรญch streamลฏ integrovanรฉ do stavu A2A\n- ฤŒasovรฉ razรญtko poslednรญho รบkolu a poฤty pro jednotlivรฉ stavy\n- Karty A2A dashboardu pro monitorovรกnรญ provozu v reรกlnรฉm ฤase\n\n
\n๐Ÿชช 25. โ€žPotล™ebuji standardnรญ vyhledรกvรกnรญ agentลฏ pro klientyโ€œ\n
\n\nExternรญ klienti a orchestratoล™i potล™ebujรญ pro onboarding strojovฤ› ฤitelnรก metadata.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazenรฉ v uลพivatelskรฉm rozhranรญ pro sprรกvu\n- API pro stav A2A zahrnuje metadata pro zjiลกลฅovรกnรญ pro automatizaci\n\n
\n๐Ÿงญ 26. โ€žPotล™ebuji v uลพivatelskรฉm rozhranรญ produktu zjistitelnost protokolu.โ€œ\n
\n\nPokud uลพivatelรฉ nemohou objevit protokolovรฉ povrchy, kvalita pล™ijetรญ a podpory klesรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Strรกnka Konsolidovanรฉ **koncovรฉ body** s kartami pro koncovรฉ body Proxy, MCP, A2A a API\n- Pล™epรญnรกnรญ stavu inline sluลพby (Online/Offline) pro MCP a A2A\n- Odkazy z pล™ehledu na vyhrazenรฉ karty pro sprรกvu\n\n
\n๐Ÿงช 27. โ€žPotล™ebuji komplexnรญ ovฤ›ล™enรญ protokolu se skuteฤnรฝmi klienty.โ€œ\n
\n\nSimulovanรฉ testy nestaฤรญ k ovฤ›ล™enรญ kompatibility protokolu pล™ed vydรกnรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sada E2E, kterรก spouลกtรญ aplikaci a pouลพรญvรก skuteฤnรฝ transport klienta MCP SDK.\n- Klientskรฉ testy A2A pro toky zjiลกลฅovรกnรญ, odesรญlรกnรญ, streamovรกnรญ, naฤรญtรกnรญ a zruลกenรญ\n- Kล™รญลพovรก kontrola tvrzenรญ oproti API pro audit MCP a รบkoly A2A\n\n
\n๐Ÿ“ก 28. โ€žPotล™ebuji jednotnou pozorovatelnost napล™รญฤ vลกemi rozhranรญmiโ€œ\n
\n\nRozdฤ›lenรญ pozorovatelnosti podle protokolu vytvรกล™รญ slepรก mรญsta a delลกรญ MTTR.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรฉ dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie poลพadavkลฏ napล™รญฤ vrstvami OpenAI, MCP a A2A\n- Provoznรญ API pro stav a automatizaci\n\n
\n๐Ÿ’ผ 29. โ€žPotล™ebuji jeden runtime pro proxy + nรกstroje + orchestraci agentลฏโ€œ\n
\n\nSpouลกtฤ›nรญ mnoha samostatnรฝch sluลพeb zvyลกuje provoznรญ nรกklady a poฤet poruch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Proxy, MCP server a A2A server kompatibilnรญ s OpenAI v jednom balรญฤku\n- Sdรญlenรฉ ovฤ›ล™ovรกnรญ, odolnost, รบloลพiลกtฤ› dat a pozorovatelnost\n- Konzistentnรญ model politik napล™รญฤ vลกemi interakฤnรญmi plochami\n\n
\n๐Ÿš€ 30. โ€žPotล™ebuji agentskรฉ pracovnรญ postupy bez slepenรญ kรณdu.โ€œ\n
\n\nTรฝmy ztrรกcejรญ rychlost pล™i spojovรกnรญ vรญce ad-hoc sluลพeb a skriptลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรก strategie koncovรฝch bodลฏ pro klienty a agenty\n- Vestavฤ›nรก uลพivatelskรก rozhranรญ pro sprรกvu protokolลฏ a cesty pro ovฤ›ล™ovรกnรญ kouล™e\n- Zรกklady pล™ipravenรฉ pro produkฤnรญ prostล™edรญ (zabezpeฤenรญ, protokolovรกnรญ, odolnost, zรกlohovรกnรญ)\n\n### Pล™รญklady hernรญch plรกnลฏ (integrovanรฉ pล™รญpady uลพitรญ)\n\n**Pล™รญruฤka A: Maximalizace placenรฉho pล™edplatnรฉho + levnรฉ zรกlohovรกnรญ**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Pล™รญruฤka B: Kรณdovacรญ stack s nulovรฝmi nรกklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Pล™รญruฤka C: Nonstop zรกloลพnรญ ล™etฤ›zec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Pล™รญruฤka D: Operace agentลฏ s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Zaฤnฤ›te zdarma โ€” Nulovรฉ nรกklady na konfiguraci\n\n> Nastavte si kรณdovรกnรญ s umฤ›lou inteligencรญ bฤ›hem nฤ›kolika minut za **0 $/mฤ›sรญc** . Propojte tyto bezplatnรฉ รบฤty a vyuลพijte vestavฤ›nou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelรฉ odemฤeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Pล™ipojenรญ **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€“ **neomezenฤ›** |\n| 2 | Pล™ipojenรญ k **Qoder** (Google OAuth) | kimi-k2-myลกlenรญ, qwen3-coder-plus, deepseek-r1... โ€” **neomezenฤ›** |\n| 3 | Pล™ipojenรญ **Qwen** (kรณd zaล™รญzenรญ) | qwen3-coder-plus, qwen3-coder-flash... โ€” **neomezenฤ›** |\n| 4 | Pล™ipojenรญ **rozhranรญ pล™รญkazovรฉho ล™รกdku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180 000 GBP/mฤ›sรญc zdarma** |\n| 5 | `/dashboard/combos` โ†’ ล ablona **Free Stack (0 $)** | Automatickรฉ zaล™azenรญ vลกech bezplatnรฝch poskytovatelลฏ do routingu |\n\n**V libovolnรฉm IDE/CLI naveฤte:** `http://localhost:20128/v1` ยท Klรญฤ API: `any-string` ยท Hotovo.\n\n> **Volitelnรฉ doplลˆkovรฉ krytรญ (takรฉ zdarma):** Groq API klรญฤ (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelลฏ), Cerebras (1 milion tok/den).\n\n## โšก Rychlรฝ start\n\n### 1) Nainstalujte a spusลฅte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uลพivatelรฉ pnpm:** Po instalaci spusลฅte `pnpm approve-builds -g` , abyste povolili nativnรญ skripty pro sestavenรญ vyลพadovanรฉ programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard se otevรญrรก na `http://localhost:20128` a zรกkladnรญ URL API je `http://localhost:20128/v1` .\n\n| Pล™รญkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuลกtฤ›nรญ serveru ( `PORT=20128` , API a dashboard na stejnรฉm portu) |\n| `omniroute --port 3000` | Nastavte kanonickรฝ/API port na 3000 |\n| `omniroute --mcp` | Spuลกtฤ›nรญ MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevรญrat prohlรญลพeฤ automaticky |\n| `omniroute --help` | Zobrazit nรกpovฤ›du |\n\nVolitelnรฝ reลพim s rozdฤ›lenรฝm portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Pล™ipojte poskytovatele a vytvoล™te si klรญฤ API\n\n1. Otevล™ete Dashboard โ†’ `Providers` a pล™ipojte alespoลˆ jednoho poskytovatele (klรญฤ OAuth nebo API).\n2. Otevล™ete Dashboard โ†’ `Endpoints` a vytvoล™te API klรญฤ.\n3. (Volitelnรฉ) Otevล™ete Dashboard โ†’ `Combos` a nastavte zรกloลพnรญ ล™etฤ›zec.\n\n### 3) Nasmฤ›rujte svลฏj kรณdovacรญ nรกstroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilnรญmi s OpenAI.\n\n### 4) Povolenรญ a ovฤ›ล™enรญ protokolลฏ (v2.0)\n\n**MCP (pro operace ล™รญzenรฉ nรกstroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak pล™ipojte svรฉho MCP klienta pล™es `stdio` a otestujte nรกstroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovnรญ postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ovฤ›ล™te vลกe od zaฤรกtku do konce (doporuฤeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ovฤ›ล™uje skuteฤnรฉ toky klientลฏ MCP a A2A v porovnรกnรญ se spuลกtฤ›nou aplikacรญ.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute je k dispozici jako veล™ejnรฝ obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlรฝ bฤ›h:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostล™edรญ:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Pouลพรญvรกnรญ Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | ล tรญtek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovฤ›jลกรญ stabilnรญ verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuรกlnรญ verze |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktopovรก aplikace โ€“ offline a vลพdy zapnutรก\n\n> ๐Ÿ†• **NOVINKA!** OmniRoute je nynรญ k dispozici jako **nativnรญ desktopovรก aplikace** pro Windows, macOS a Linux.\n\nSpusลฅte OmniRoute jako samostatnou desktopovou aplikaci โ€“ pro lokรกlnรญ modely nenรญ potล™eba ลพรกdnรฝ terminรกl, prohlรญลพeฤ ani internet. Aplikace zaloลพenรก na platformฤ› Electron obsahuje:\n\n- ๐Ÿ–ฅ๏ธ **Nativnรญ okno** โ€” Vyhrazenรฉ okno aplikace s integracรญ do systรฉmovรฉ liลกty\n- ๐Ÿ”„ **Automatickรฉ spuลกtฤ›nรญ** โ€” Spuลกtฤ›nรญ OmniRoute po pล™ihlรกลกenรญ do systรฉmu\n- ๐Ÿ”” **Nativnรญ oznรกmenรญ** โ€“ Zรญskejte upozornฤ›nรญ na vyฤerpรกnรญ kvรณty nebo problรฉmy s poskytovateli\n- โšก **Instalace jednรญm kliknutรญm** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline reลพim** โ€” Funguje plnฤ› offline s pล™iloลพenรฝm serverem\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systรฉmovรฝ zรกsobnรญk\n\nPo minimalizaci se OmniRoute nachรกzรญ v systรฉmovรฉ liลกtฤ› a nabรญzรญ rychlรฉ akce:\n\n- Otevล™รญt ล™รญdicรญ panel\n- Zmฤ›nit port serveru\n- Ukonฤit aplikaci\n\n๐Ÿ“– รšplnรก dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pล™ehled cen\n\n| รšroveลˆ | Poskytovatel | Nรกklady | Obnovenรญ kvรณty | Nejlepลกรญ pro |\n| --------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **๐Ÿ’ณ Pล˜EDPLATNร‰** | Claude Code (profesionรกl) | 20 dolarลฏ mฤ›sรญฤnฤ› | 5 hodin + tรฝdnฤ› | Jiลพ pล™ihlรกลกen/a k odbฤ›ru |\n| Kodex (Plus/Pro) | 20โ€“200 USD/mฤ›sรญc | 5 hodin + tรฝdnฤ› | Uลพivatelรฉ OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisรญc mฤ›sรญฤnฤ› + 1 tisรญc dennฤ› | Kaลพdรฝ! |\n| GitHub Copilot | 10โ€“19 USD/mฤ›sรญc | Mฤ›sรญฤnรญ | Uลพivatelรฉ GitHubu |\n| **๐Ÿ”‘ KLรฤŒ API** | NVIDIA NIM | **ZDARMA** (vรฝvoj navลพdy) | ~40 ot./min | 70+ otevล™enรฝch modelลฏ |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ na svฤ›tฤ› |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisรญc otรกฤek za minutu | Ultrarychlรก lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | ลฝรกdnรฝ | Nejlepลกรญ zdลฏvodnฤ›nรญ ceny a kvality |\n| xAI Grok-4 Rychlรฝ | **0,20/0,50 USD za 1 milion** ๐Ÿ†• | ลฝรกdnรฝ | Nejrychlejลกรญ + volรกnรญ nรกstroje, ultranรญzkรฉ |\n| xAI Grok-4 (standardnรญ) | 0,20/1,50 USD za 1 milion ๐Ÿ†• | ลฝรกdnรฝ | Vlajkovรก loฤ Reasoning od xAI |\n| Mistral | Zkuลกebnรญ verze zdarma + placenรฉ | Omezenรก sazba | Evropskรก umฤ›lรก inteligence |\n| OpenRouter | Platba za pouลพitรญ | ลฝรกdnรฝ | Vรญce neลพ 100 modelลฏ agregovรกno. |\n| **๐Ÿ’ฐ LEVNร‰** | GLM-5 (pล™es Z.AI) ๐Ÿ†• | 0,5 USD/1 milion | Dennฤ› v 10:00 | Vรฝstup 128 tisรญc obrazovรฝch bodลฏ, nejnovฤ›jลกรญ vlajkovรก loฤ |\n| GLM-4.7 | 0,6 USD/1 milion | Dennฤ› v 10:00 | Zรกloha rozpoฤtu |\n| MiniMax M2.5 ๐Ÿ†• | Vstup 0,3 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | รšvaha + agentnรญ รบkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | Nejlevnฤ›jลกรญ varianta |\n| Kimi K2.5 (Moonshot API) ๐Ÿ†• | Platba za pouลพitรญ | ลฝรกdnรฝ | Pล™รญmรฝ pล™รญstup k Moonshot API |\n| Kimi K2 | 9 dolarลฏ mฤ›sรญฤnฤ› bez zรกvazkลฏ | 10 milionลฏ tokenลฏ/mฤ›sรญc | Pล™edvรญdatelnรฉ nรกklady |\n| **๐Ÿ†“ ZDARMA** | Qoder | **0 dolarลฏ** | Neomezenรฝ | 5 modelลฏ neomezenฤ› |\n| Qwen | **0 dolarลฏ** | Neomezenรฝ | 4 modely neomezenฤ› |\n| Kiro | **0 dolarลฏ** | Neomezenรฝ | Claude Sonnet/Haiku (tvorce AWS) |\n\n> ๐Ÿ†• **Pล™idรกny novรฉ modely (bล™ezen 2026):** ล™ada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkovรกno na 1143 ms โ€“ o 30 % rychlejลกรญ neลพ Gemini 2.5 Flash), GLM-5 pล™es Z.AI s vรฝstupem 128K, uvaลพovรกnรญ MiniMax M2.5, aktualizovanรฉ ceny DeepSeek V3.2, Kimi K2.5 pล™es Moonshot Direct API.\n\n**๐Ÿ’ก Kombinovanรฝ balรญk za 0 $ โ€” Kompletnรญ bezplatnรก instalace:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\nQoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Nulovรฉ nรกklady. Nikdy nepล™estรกvejte s kรณdovรกnรญm.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a vลกechny zรกloลพnรญ reลพimy se provede automaticky โ€“ ลพรกdnรฉ ruฤnรญ pล™epรญnรกnรญ.\n\n---\n\n---\n\n## ๐Ÿ†“ Bezplatnรฉ modely โ€“ Co skuteฤnฤ› zรญskรกte\n\n> Vลกechny nรญลพe uvedenรฉ modely jsou **100% zdarma a nevyลพadujรญ ลพรกdnou kreditnรญ kartu** . OmniRoute mezi nimi automaticky propojรญ trasy, kdyลพ dojde jedna kvรณta โ€“ zkombinujte je vลกechny a zรญskejte tak nerozluฤnou kombinaci za 0 dolarลฏ.\n\n### ๐Ÿ”ต CLAUDE MODELS (pล™es Kiro โ€” AWS Builder ID)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-opus-4.6` | `kr/` | **Neomezenรฝ** | Nejnovฤ›jลกรญ opus od Kira |\n\n### ๐ŸŸข MODELY QODER (Bezplatnรฉ OAuth โ€” bez nutnosti platit kreditnรญ kartou)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-plus` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `deepseek-r1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `minimax-m2.1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `kimi-k2` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n\n### ๐ŸŸก MODELY QWEN (Ovฤ›ล™enรญ kรณdu zaล™รญzenรญ)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-next` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `vision-model` | `qw/` | **Neomezenรฝ** | Multimodรกlnรญ (obrรกzky) |\n\n### ๐ŸŸฃ Rozhranรญ GEMINI CLI (Google OAuth)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisรญc tok/mฤ›sรญc** + 1 tisรญc/den | Mฤ›sรญฤnรญ reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisรญc mฤ›sรญฤnฤ› (sdรญlenรฝ bazรฉn) | Vysokรก kvalita |\n\n### โšซ NVIDIA NIM (Bezplatnรฝ klรญฤ API โ€” build.nvidia.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vรฝvojรกล™) | ลฝรกdnรฝ limit tokenลฏ | **~40 ot./min** | Vรญce neลพ 70 modelลฏ; pล™echod na ฤistรฉ limity sazeb v polovinฤ› roku 2025 |\n\nOblรญbenรฉ bezplatnรฉ modely: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct` , `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Bezplatnรฝ klรญฤ API โ€” inference.cerebras.ai)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenลฏ/den** | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ inference LLM na svฤ›tฤ›; dennฤ› se resetuje |\n\nDostupnรฉ zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Bezplatnรฝ API klรญฤ โ€” console.groq.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisรญc otรกฤek za minutu** | 30 ot./min na model | ลฝรกdnรก kreditnรญ karta; limit 429, neรบฤtovรกno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **๐Ÿ’ก Ultimรกtnรญ bezplatnรฝ zรกsobnรญk:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> โ†’ Qoder (5 models, unlimited)\n> โ†’ Qwen (4 models, unlimited)\n> โ†’ Gemini CLI (180K/mo)\n> โ†’ Cerebras (1M tok/day)\n> โ†’ Groq (14.4K req/day)\n> โ†’ NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a uลพ nikdy nebudete platit za umฤ›lou inteligenci.\n\n## ๐ŸŽ™๏ธ Kombinovanรก transkripce zdarma\n\n> Pล™episujte libovolnรฉ audio/video za **0 $** โ€“ Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako zรกloลพnรญ nรกstroj, Groq Whisper jako neomezenรก nouzovรก zรกloha.\n\n| Poskytovatel | Bezplatnรฉ kredity | Nejlepลกรญ model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| ๐ŸŸข **Deepgram** | **200 dolarลฏ zdarma** (registrace) | `nova-3` โ€” nejvyลกลกรญ pล™esnost, vรญce neลพ 30 jazykลฏ | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ต **AssemblyAI** | **50 dolarลฏ zdarma** (registrace) | `universal-3-pro` โ€” kapitoly, sentiment, osobnรญ รบdaje | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ด **Groq** | **Navลพdy zdarma** | `whisper-large-v3` โ€” OpenAI ล epot | 30 ot./min (omezenรก rychlost) |\n\n**Navrhovanรก kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nPak v `/dashboard/media` โ†’ zรกloลพka **Pล™epis** : nahrajte libovolnรฝ zvukovรฝ nebo video soubor โ†’ vyberte kombinovanรฝ koncovรฝ bod โ†’ zรญskejte pล™epis v podporovanรฝch formรกtech.\n\n## ๐Ÿ’ก Klรญฤovรฉ vlastnosti\n\nOmniRoute v2.0 je navrลพen jako operaฤnรญ platforma, nikoli pouze jako proxy pro relรฉ.\n\n### ๐Ÿค– Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dฤ›lรก |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (16 nรกstrojลฏ)** | Nรกstroje IDE/agent prostล™ednictvรญm 3 transportลฏ: stdio, SSE ( `/api/mcp/sse` ), Streamovatelnรฝ HTTP ( `/api/mcp/stream` ) |\n| ๐Ÿค **A2A server (JSON-RPC + SSE)** | Spouลกtฤ›nรญ รบloh mezi agenty se synchronizacรญ a streamovรกnรญm |\n| ๐Ÿงญ **Konsolidovanรก strรกnka koncovรฝch bodลฏ** | Strรกnka pro sprรกvu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| ๐ŸŽš๏ธ **Pล™epรญnaฤe pro povolenรญ/zakรกzรกnรญ sluลพby** | Pล™epรญnaฤe ZAP/VYP pro MCP a A2A s trvalรฝm nastavenรญm (vรฝchozรญ: VYP) |\n| ๐Ÿ›ฐ๏ธ **Srdeฤnรญ tep za bฤ›hu MCP** | Skuteฤnรฝ stav procesu (pid, doba provozuschopnosti, stรกล™รญ heartbeatu, transport, reลพim rozsahu) |\n| ๐Ÿ“‹ **Auditnรญ zรกznam MCP** | Filtrovatelnรฉ protokoly auditu s hodnocenรญm รบspฤ›chu/neรบspฤ›chu a klรญฤovรฝm pล™iล™azenรญm |\n| ๐Ÿ” **Vynucovรกnรญ rozsahu MCP** | 9 podrobnรฝch oprรกvnฤ›nรญ pro ล™รญzenรฝ pล™รญstup k nรกstrojลฏm |\n| ๐Ÿ“ก **Sprรกva ลพivotnรญho cyklu รบkolลฏ A2A** | Seznam/filtrovรกnรญ รบloh, kontrola udรกlostรญ/artefaktลฏ, zruลกenรญ spuลกtฤ›nรฝch รบloh |\n| ๐Ÿ“‹ **Objevenรญ karty agenta** | `/.well-known/agent.json` pro automatickรฉ vyhledรกvรกnรญ klientลฏ |\n| ๐Ÿงช **Testovacรญ postroj Protocol E2E** | Skuteฤnรฉ MCP SDK + toky klientลฏ A2A v `test:protocols:e2e` |\n| โš™๏ธ **Provoznรญ kontroly** | Kombinace pล™epรญnaฤลฏ, pouลพitรญ profilลฏ odolnosti, resetovรกnรญ jistiฤลฏ z jednoho ovlรกdacรญho panelu |\n\n### ๐Ÿง  Smฤ›rovรกnรญ a inteligence\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| ๐ŸŽฏ **Inteligentnรญ ฤtyล™รบrovลˆovรฝ zรกloลพnรญ systรฉm** | Automatickรก trasa: Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma |\n| ๐Ÿ“Š **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** | Poฤet tokenลฏ v reรกlnรฉm ฤase + odpoฤet resetovรกnรญ pro kaลพdรฉho poskytovatele |\n| ๐Ÿ”„ **Pล™eklad formรกtu** | OpenAI โ†” Claude โ†” Gemini โ†” Odpovฤ›di s konverzemi bezpeฤnรฝmi pro schรฉma |\n| ๐Ÿ‘ฅ **Podpora vรญce รบฤtลฏ** | Vรญce รบฤtลฏ na poskytovatele s inteligentnรญm vรฝbฤ›rem |\n| ๐Ÿ”„ **Automatickรก aktualizace tokenลฏ** | Tokeny OAuth se automaticky obnovujรญ pล™i opakovanรฉm pokusu. |\n| ๐ŸŽจ **Vlastnรญ kombinace** | 6 vyvaลพovacรญch strategiรญ + ล™รญzenรญ zรกloลพnรญho ล™etฤ›zce |\n| ๐ŸŒ **Smฤ›rovaฤ se zรกstupnรฝmi znaky** | dynamickรฉ smฤ›rovรกnรญ `provider/*` |\n| ๐Ÿง  **Pล™emรฝลกlenรญ o rozpoฤtovรฝch kontrolรกch** | Limity pro prลฏchozรญ, automatickรฉ, vlastnรญ a adaptivnรญ uvaลพovรกnรญ |\n| ๐Ÿ”€ **Aliasy modelลฏ** | Vestavฤ›nรฉ + vlastnรญ aliasovรกnรญ modelลฏ a bezpeฤnost migrace |\n| โšก **Degradace pozadรญ** | Smฤ›rujte รบlohy na pozadรญ s nรญzkou prioritou na levnฤ›jลกรญ modely |\n| ๐Ÿงช **Chytrรฉ smฤ›rovรกnรญ s ohledem na รบkoly** | Automatickรฝ vรฝbฤ›r modelu podle typu obsahu (kรณdovรกnรญ/vize/analรฝza/sumarizace) |\n| ๐Ÿ’ฌ **Vstล™ikovรกnรญ do systรฉmu** | Globรกlnรญ kontroly chovรกnรญ uplatลˆovanรฉ konzistentnฤ› |\n| ๐Ÿ“„ **Kompatibilita API pro odpovฤ›di** | Plnรก podpora `/v1/responses` pro Codex a pokroฤilรฉ agentickรฉ pracovnรญ postupy |\n\n### ๐ŸŽต Multimodรกlnรญ API\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Generovรกnรญ obrรกzkลฏ** | `/v1/images/generations` s cloudovรฝm a lokรกlnรญm backendem |\n| ๐Ÿ“ **Vloลพenรญ** | `/v1/embeddings` pro vyhledรกvรกnรญ a RAG pipelines |\n| ๐ŸŽค **Pล™epis zvuku** | `/v1/audio/transcriptions` (Whisper a dalลกรญ poskytovatelรฉ) |\n| ๐Ÿ”Š **Pล™evod textu na ล™eฤ** | `/v1/audio/speech` (vรญce enginลฏ/poskytovatelลฏ) |\n| ๐ŸŽฌ **Generovรกnรญ videa** | `/v1/videos/generations` (pracovnรญ postupy ComfyUI + SD WebUI) |\n| ๐ŸŽต **Hudebnรญ generace** | `/v1/music/generations` (pracovnรญ postupy ComfyUI) |\n| ๐Ÿ›ก๏ธ **Moderovรกnรญ** | Bezpeฤnostnรญ kontroly `/v1/moderations` |\n| ๐Ÿ”€ **Zmฤ›na poล™adรญ** | `/v1/rerank` pro hodnocenรญ relevance |\n| ๐Ÿ” **Vyhledรกvรกnรญ na webu** ๐Ÿ†• | `/v1/search` โ€” 5 poskytovatelลฏ (Serper, Brave, Perplexity, Exa, Tavily), vรญce neลพ 6 500 zdarma/mฤ›sรญc, automatickรฉ pล™epnutรญ na zรกloลพnรญ systรฉm, mezipamฤ›ลฅ |\n\n### ๐Ÿ›ก๏ธ Odolnost, bezpeฤnost a sprรกva vฤ›cรญ veล™ejnรฝch\n\n| Funkce | Co to dฤ›lรก |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Jistiฤe** | Vypnutรญ/obnovenรญ pro kaลพdรฝ model s ovlรกdรกnรญm prahovรฝch hodnot |\n| ๐ŸŽฏ **Modely s ohledem na koncovรฉ body** | Vlastnรญ modely deklarujรญ podporovanรฉ koncovรฉ body + formรกt API |\n| ๐Ÿ›ก๏ธ **Stรกdo proti hromลฏm** | Ochrana mutexu a semaforu pล™i udรกlostech opakovรกnรญ/rychlosti |\n| ๐Ÿง  **Sรฉmantickรก + podpisovรก mezipamฤ›ลฅ** | Snรญลพenรญ nรกkladลฏ/latence dรญky dvฤ›ma vrstvรกm mezipamฤ›ti |\n| โšก **ลฝรกdost o idempotenci** | Okno ochrany proti duplikacรญm |\n| ๐Ÿ”’ **Falลกovรกnรญ otiskลฏ prstลฏ pomocรญ TLS** | Otisk TLS podobnรฝ prohlรญลพeฤi โ€“ **sniลพuje detekci botลฏ a nahlaลกovรกnรญ รบฤtลฏ** |\n| ๐Ÿ” **Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** | Shoduje se s nativnรญmi podpisy poลพadavkลฏ CLI โ€“ **sniลพuje riziko zablokovรกnรญ a zรกroveลˆ zachovรกvรก IP adresu proxy** |\n| ๐ŸŒ **Filtrovรกnรญ IP adres** | Ovlรกdรกnรญ seznamu povolenรฝch/blokovanรฝch poloลพek pro odhalenรก nasazenรญ |\n| ๐Ÿ“Š **Upravitelnรฉ limity rychlosti** | Konfigurovatelnรฉ globรกlnรญ/na รบrovni poskytovatele limity s perzistencรญ |\n| ๐Ÿ”‘ **Sprรกva klรญฤลฏ API a stanovenรญ rozsahu** | Bezpeฤnรฉ vydรกvรกnรญ/rotace klรญฤลฏ a kontroly modelu/poskytovatele |\n| ๐Ÿ›ก๏ธ **Chrรกnฤ›nรฉ `/models`** | Volitelnรฉ ovฤ›ล™ovรกnรญ a skrytรญ poskytovatele pro katalog modelลฏ |\n\n### ๐Ÿ“Š Pozorovatelnost a analytika\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| ๐Ÿ“ **ลฝรกdost + protokolovรกnรญ proxy** | รšplnรฉ protokolovรกnรญ poลพadavkลฏ/odpovฤ›dรญ a proxy |\n| ๐Ÿ“‹ **Sjednocenรฝ panel protokolลฏ** | Zobrazenรญ poลพadavkลฏ, proxy, auditu a konzole na jednรฉ strรกnce |\n| ๐Ÿ” **Vyลพรกdat si telemetrii** | Latence p50/p95/p99 a trasovรกnรญ poลพadavkลฏ |\n| ๐Ÿฅ **Panel zdravรญ** | Doba provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti |\n| ๐Ÿ’ฐ **Sledovรกnรญ nรกkladลฏ** | Kontrola rozpoฤtu a pล™ehled o cenรกch pro jednotlivรฉ modely |\n| ๐Ÿ“ˆ **Analytickรฉ vizualizace** | Pล™ehledy vyuลพitรญ modelลฏ/poskytovatelลฏ a zobrazenรญ trendลฏ |\n| ๐Ÿงช **Rรกmec hodnocenรญ** | Testovรกnรญ zlatรฉ sady s konfigurovatelnรฝmi strategiemi shody |\n\n### โ˜๏ธ Nasazenรญ a platforma\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| ๐ŸŒ **Nasazenรญ kdekoli** | Localhost, VPS, Docker, cloudovรก prostล™edรญ |\n| ๐Ÿ’พ **Synchronizace s cloudem** | Synchronizace konfigurace pล™es cloud worker |\n| ๐Ÿ”„ **Zรกlohovรกnรญ/Obnovenรญ** | Toky exportu/importu a obnovy po havรกrii |\n| ๐Ÿง™ **Prลฏvodce nรกstupem** | Prลฏvodce prvnรญm spuลกtฤ›nรญm |\n| ๐Ÿ”ง **Panel nรกstrojลฏ CLI** | Nastavenรญ oblรญbenรฝch kรณdovacรญch nรกstrojลฏ jednรญm kliknutรญm |\n| ๐ŸŽฎ **Modelovรฉ hล™iลกtฤ›** | Otestujte libovolnรฉho poskytovatele/model/koncovรฝ bod z ล™รญdicรญho panelu |\n| ๐Ÿ” **Pล™epรญnaฤ otiskลฏ prstลฏ v pล™รญkazovรฉm ล™รกdku** | Porovnรกvรกnรญ otiskลฏ prstลฏ podle poskytovatele v Nastavenรญ > Zabezpeฤenรญ |\n| ๐ŸŒ **i18n (30 jazykลฏ)** | Plnรก jazykovรก podpora dashboardu a dokumentace s psanรญm zprava doleva |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Adresรกล™ vlastnรญch dat** | Pล™epsรกnรญ `DATA_DIR` pro umรญstฤ›nรญ รบloลพiลกtฤ› |\n\n### Hlubokรฝ pohled na funkce\n\n#### Chytrรก zรกloลพnรญ funkce s praktickou kontrolou nรกkladลฏ\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyลพ selลพe kvรณta, rychlost nebo stav, OmniRoute automaticky pล™ejde k dalลกรญmu kandidรกtovi bez nutnosti ruฤnรญho pล™epรญnรกnรญ.\n\n#### Sprรกva protokolลฏ, kterรก je viditelnรก a ovladatelnรก\n\n- MCP + A2A jsou viditelnรฉ v uลพivatelskรฉm rozhranรญ a dokumentaci (nejsou skrytรฉ)\n- API pro stav protokolu zpล™รญstupลˆujรญ ลพivรก provoznรญ data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnujรญ akce pro operace 2. dne (pล™epรญnรกnรญ kombinacรญ, resetovรกnรญ jistiฤลฏ, zruลกenรญ รบkolลฏ)\n\n#### Pracovnรญ postup pล™ekladatele + validace\n\nOblast pล™ekladatele zahrnuje:\n\n- **Hล™iลกtฤ›** : kontroly transformace poลพadavkลฏ\n- **Tester chatu** : kompletnรญ okruลพnรญ cesta poลพadavku/odpovฤ›di\n- **Testovacรญ stolice** : vรญce pล™รญpadลฏ v jednom bฤ›hu\n- **ลฝivรฝ monitor** : zobrazenรญ provozu v reรกlnรฉm ฤase\n\nPlus validace protokolu se skuteฤnรฝmi klienty pomocรญ `npm run test:protocols:e2e` .\n\n> ๐Ÿ“– **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** โ€” Referenฤnรญ informace o nรกstrojรญch, konfigurace IDE a pล™รญklady klientลฏ\n>\n> ๐Ÿ“– **[Soubor README pro A2A Server](src/lib/a2a/README.md)** โ€” Dovednosti, metody JSON-RPC, streamovรกnรญ a ลพivotnรญ cyklus รบloh\n\n## ๐Ÿงช Hodnocenรญ (Evals)\n\nOmniRoute obsahuje vestavฤ›nรฝ hodnotรญcรญ rรกmec pro testovรกnรญ kvality odpovฤ›dรญ LLM v porovnรกnรญ se zlatou sadou. Pล™รญstup k nฤ›mu je moลพnรฝ pล™es **Analรฝzy โ†’ Hodnocenรญ** v dashboardu.\n\n### Vestavฤ›nรก zlatรก sada\n\nPล™edinstalovanรก sada โ€žOmniRoute Golden Setโ€œ obsahuje testovacรญ pล™รญpady pro:\n\n- Zdravรญm, matematika, zemฤ›pis, generovรกnรญ kรณdu\n- Shoda s formรกtem JSON, pล™eklad, generovรกnรญ markdownลฏ\n- Bezpeฤnostnรญ odmรญtnutรญ (ลกkodlivรฝ obsah), poฤรญtรกnรญ, booleovskรก logika\n\n### Strategie hodnocenรญ\n\n| Strategie | Popis | Pล™รญklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Vรฝstup se musรญ pล™esnฤ› shodovat | `\"4\"` |\n| `contains` | Vรฝstup musรญ obsahovat podล™etฤ›zec (bez rozliลกenรญ velkรฝch a malรฝch pรญsmen) | `\"Paris\"` |\n| `regex` | Vรฝstup musรญ odpovรญdat vzoru regulรกrnรญch vรฝrazลฏ | `\"1.*2.*3\"` |\n| `custom` | Vlastnรญ JS funkce vracรญ true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Prลฏvodce nastavenรญm\n\n### Nastavenรญ protokolu (MCP + A2A)\n\n
\n๐Ÿงฉ Nastavenรญ MCP (Model Context Protocol)\n
\n\nSpuลกtฤ›nรญ MCP transportu v reลพimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporuฤenรฝ postup ovฤ›ล™enรญ:\n\n1. Pล™ipojte svรฉho MCP klienta pล™es stdio.\n2. Spusลฅte `omniroute_get_health` .\n3. Spusลฅte `omniroute_list_combos` .\n4. Otevล™ete `/dashboard/mcp` pro ovฤ›ล™enรญ prezenฤnรญho signรกlu, aktivity a auditu.\n\nUลพiteฤnรก API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n๐Ÿค Nastavenรญ A2A (Agent2Agent)\n
\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat รบkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSprรกva ลพivotnรญho cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvoznรญ uลพivatelskรฉ rozhranรญ:\n\n- `/dashboard/a2a` pro pozorovatelnost รบloh/stavลฏ/streamลฏ a akce kouล™enรญ\n\n
\n๐Ÿงช Komplexnรญ validace protokolu\n
\n\nOvฤ›ล™te oba protokoly se skuteฤnรฝmi klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTรญm se ovฤ›ล™uje:\n\n- Pล™ipojenรญ/seznam/volรกnรญ klienta MCP SDK\n- A2A objevovรกnรญ/odesรญlรกnรญ/streamovรกnรญ/zรญskรกvรกnรญ/zruลกenรญ\n- Kล™รญลพovรก kontrola dat v auditu MCP a API pro sprรกvu รบloh A2A\n\n
\n๐Ÿ’ณ Poskytovatelรฉ pล™edplatnรฉho\n
\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionรกly:** Pro sloลพitรฉ รบkoly pouลพรญvejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvรณtu pro kaลพdรฝ model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Sprรกva limitลฏ รบฤtu Codex (5h + tรฝdnฤ›)\n\nKaลพdรฝ รบฤet Codex mรก nynรญ pล™epรญnaฤe zรกsad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinovรฉho prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zรกsadu tรฝdennรญho prahu okna.\n- Prahovรฉ chovรกnรญ: kdyลพ povolenรฉ okno dosรกhne vyuลพitรญ >=90 %, je danรฝ รบฤet pล™eskoฤen.\n- Chovรกnรญ rotace: OmniRoute automaticky pล™esmฤ›ruje na dalลกรญ zpลฏsobilรฝ รบฤet Codex.\n- Chovรกnรญ pล™i resetovรกnรญ: Po `resetAt` urฤitรฉ doby se รบฤet automaticky opฤ›t stane zpลฏsobilรฝm.\n\nScรฉnรกล™e:\n\n- `5h ON` + `Weekly ON` : รบฤet je pล™eskoฤen, kdyลพ kterรฉkoli z oken dosรกhne prahovรฉ hodnoty.\n- `5h OFF` + `Weekly ON` : รบฤet mลฏลพe bรฝt zablokovรกn pouze tรฝdennรญm pouลพรญvรกnรญm.\n- `5h ON` + `Weekly OFF` : รบฤet mลฏลพe bรฝt zablokovรกn pouze pล™i 5hodinovรฉm pouลพรญvรกnรญ.\n- `resetAt` passed: รบฤet se automaticky znovu zapne (bez ruฤnรญho opฤ›tovnรฉho povolenรญ).\n\n### Gemini CLI (ZDARMA 180 000/mฤ›sรญc!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepลกรญ hodnota:** Obrovskรก bezplatnรก รบroveลˆ! Pouลพijte ji pล™ed placenรฝmi รบrovnฤ›mi.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n
\n๐Ÿ”‘ Poskytovatelรฉ klรญฤลฏ API\n
\n\n### NVIDIA NIM (BEZPLATNร pล™รญstup pro vรฝvojรกล™e โ€” vรญce neลพ 70 modelลฏ)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Zรญskejte zdarma klรญฤ API (vฤetnฤ› 1000 inferenฤnรญch kreditลฏ)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ NVIDIA NIM:\n - Klรญฤ API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a vรญce neลพ 50 dalลกรญch\n\n**Tip pro profesionรกly:** API kompatibilnรญ s OpenAI โ€“ funguje bez problรฉmลฏ s pล™ekladem formรกtลฏ OmniRoute!\n\n### Hlubokรฉ vyhledรกvรกnรญ\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatnรก รบroveลˆ!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Zรญskejte klรญฤ API (vฤetnฤ› bezplatnรฉ รบrovnฤ›)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionรกly:** Ultrarychlรก inference โ€“ nejlepลกรญ pro kรณdovรกnรญ v reรกlnรฉm ฤase!\n\n### OpenRouter (100+ modelลฏ)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ OpenRouter\n\n**Modely:** Zรญskejte pล™รญstup k vรญce neลพ 100 modelลฏm od vลกech hlavnรญch poskytovatelลฏ prostล™ednictvรญm jedinรฉho klรญฤe API.\n\n
\n๐Ÿ’ฐ Levnรญ poskytovatelรฉ (zรกloลพnรญ)\n
\n\n### GLM-4.7 (Dennรญ reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Zรญskejte klรญฤ API z kรณdovacรญho plรกnu\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API:\n - Poskytovatel: `glm`\n - Klรญฤ API: `your-key`\n\n**Pouลพitรญ:** `glm/glm-4.7`\n\n**Tip pro profesionรกly:** Programovacรญ plรกn nabรญzรญ 3ร— kvรณtu za cenu 1/7! Obnovuje se dennฤ› v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionรกly:** Nejlevnฤ›jลกรญ varianta pro dlouhรฝ kontext (1 milion tokenลฏ)!\n\n### Kimi K2 (pauลกรกlnรญ poplatek 9 dolarลฏ mฤ›sรญฤnฤ›)\n\n1. Odebรญrat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `kimi/kimi-latest`\n\n**Tip pro profesionรกly:** Fixnรญch 9 $/mฤ›sรญc za 10 milionลฏ tokenลฏ = efektivnรญ nรกklady 0,90 $/1 milion!\n\n
\n๐Ÿ†“ BEZPLATNร poskytovatelรฉ (nouzovรฉ zรกlohovรกnรญ)\n
\n\n### Qoder (5 BEZPLATNรCH modelลฏ pล™es OAuth)\n\n```bash\nDashboard โ†’ Connect Qoder\nโ†’ Qoder OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kรณdem zaล™รญzenรญ)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n๐ŸŽจ Vytvoล™te kombinace\n
\n\n### Pล™รญklad 1: Maximalizace pล™edplatnรฉho โ†’ Levnรฉ zรกlohovรกnรญ\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Pล™รญklad 2: Pouze zdarma (nulovรฉ nรกklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n๐Ÿ”ง Integrace s rozhranรญm pล™รญkazovรฉho ล™รกdku\n
\n\n### IDE kurzoru\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jednรญm kliknutรญm pouลพijte strรกnku **Nรกstroje CLI** na ล™รญdicรญm panelu nebo ruฤnฤ› upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Moลพnost 1 โ€“ Dashboard (doporuฤeno):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Moลพnost 2 โ€“ Manuรกlnรญ รบprava:** รšprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznรกmka:** OpenClaw funguje pouze s lokรกlnรญm OmniRoute. Mรญsto `localhost` pouลพijte `127.0.0.1` , abyste se vyhnuli problรฉmลฏm s rozliลกenรญm IPv6.\n\n### Cline / Pokraฤovat / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Pล™idรกnรญ OmniRoute jako vlastnรญho poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvoล™te/upravte `opencode.json` v koล™enovรฉm adresรกล™i projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` pล™idejte jakรฝkoli model dostupnรฝ ve vaลกem koncovรฉm bodu OmniRoute `/v1/models` . Pouลพijte formรกt `provider/model-id` z vaลกeho dashboardu OmniRoute.\n\n---\n\n## ๐Ÿ› ล˜eลกenรญ problรฉmลฏ\n\n
\nKliknutรญm rozbalรญte prลฏvodce ล™eลกenรญm problรฉmลฏ\n
\n\n**\"Jazykovรฝ model neposkytoval zprรกvy\"**\n\n- Kvรณta poskytovatele vyฤerpรกna โ†’ Zkontrolujte sledovรกnรญ kvรณt na ล™รญdicรญm panelu\n- ล˜eลกenรญ: Pouลพijte zรกloลพnรญ kombinovanou variantu nebo pล™ejdฤ›te na levnฤ›jลกรญ รบroveลˆ\n\n**Omezenรญ rychlosti**\n\n- Kvรณta pล™edplatnรฉho vyฤerpรกna โ†’ Pล™echod na GLM/MiniMax\n- Pล™idat kombo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vyprลกela**\n\n- Automaticky aktualizovรกno sluลพbou OmniRoute\n- Pokud problรฉmy pล™etrvรกvajรญ: Ovlรกdacรญ panel โ†’ Poskytovatel โ†’ Znovu pล™ipojit\n\n**Vysokรฉ nรกklady**\n\n- Zkontrolujte statistiky vyuลพitรญ v sekci Nรกstฤ›nka โ†’ Nรกklady\n- Pล™epnout primรกrnรญ model na GLM/MiniMax\n- Pro nekritickรฉ รบlohy pouลพijte bezplatnou รบroveลˆ (Gemini CLI, Qoder).\n\n**Porty ล™รญdicรญho panelu/API jsou nesprรกvnรฉ**\n\n- `PORT` je kanonickรฝ zรกkladnรญ port (a standardnฤ› port API)\n- `API_PORT` pล™episuje pouze posluchaฤ API kompatibilnรญ s OpenAI.\n- `DASHBOARD_PORT` pล™episuje pouze posluchaฤ dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaลกi veล™ejnou URL adresu ล™รญdicรญho panelu (pro zpฤ›tnรก volรกnรญ OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ovฤ›ล™te, zda `BASE_URL` odkazuje na vaลกi spuลกtฤ›nou instanci.\n- Ovฤ›ล™te, zda `CLOUD_URL` odkazuje na vรกลก oฤekรกvanรฝ cloudovรฝ koncovรฝ bod.\n- Udrลพujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na stranฤ› serveru.\n\n**Prvnรญ pล™ihlรกลกenรญ nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud nenรญ nastaveno, zรกloลพnรญ heslo je `123456`\n\n**ลฝรกdnรฉ protokoly poลพadavkลฏ**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test pล™ipojenรญ ukazuje โ€žNeplatnรฉโ€œ pro poskytovatele kompatibilnรญ s OpenAI**\n\n- Mnoho poskytovatelลฏ nezpล™รญstupลˆuje koncovรฝ bod `/models`\n- OmniRoute v1.0.6+ zahrnuje zรกloลพnรญ ovฤ›ล™enรญ pomocรญ dokonฤenรญ chatu\n- Zajistฤ›te, aby zรกkladnรญ URL adresa obsahovala pล™รญponu `/v1`\n\n### ๐Ÿ” OAuth na vzdรกlenรฉm serveru\n\n\n\n> **โš ๏ธ Dลฏleลพitรฉ pro uลพivatele, kteล™รญ provozujรญ OmniRoute na VPS, Dockeru nebo jakรฉmkoli vzdรกlenรฉm serveru**\n\n#### Proฤ selhรกvรก OAuth v rozhranรญ CLI Antigravity / Gemini na vzdรกlenรฝch serverech?\n\nPoskytovatelรฉ rozhranรญ CLI **Antigravity** a **Gemini** pouลพรญvajรญ **Google OAuth 2.0** . Google vyลพaduje, aby se `redirect_uri` v toku OAuth pล™esnฤ› shodoval s jednรญm z pล™edregistrovanรฝch URI v konzoli Google Cloud Console aplikace.\n\nPล™ihlaลกovacรญ รบdaje OAuth, kterรฉ jsou souฤรกstรญ OmniRoute, jsou registrovรกny **pouze pro `localhost`** . Kdyลพ pล™istupujete k OmniRoute na vzdรกlenรฉm serveru (napล™. `https://omniroute.myserver.com` ), Google odmรญtne ovฤ›ล™enรญ pomocรญ:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### ล˜eลกenรญ: Nakonfigurujte si vlastnรญ pล™ihlaลกovacรญ รบdaje OAuth\n\nV Google Cloud Console je potล™eba vytvoล™it **ID klienta OAuth 2.0** s URI vaลกeho serveru.\n\n#### Krok za krokem\n\n**1. Otevล™ete konzoli Google Cloud**\n\nPล™ejdฤ›te na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvoล™te novรฉ ID klienta OAuth 2.0**\n\n- Kliknฤ›te na **โ€ž+ Vytvoล™it pล™ihlaลกovacรญ รบdajeโ€œ** โ†’ **โ€žID klienta OAuthโ€œ**\n- Typ aplikace: **โ€žWebovรก aplikaceโ€œ**\n- Nรกzev: cokoli chcete (napล™. `OmniRoute Remote` )\n\n**3. Pล™idejte autorizovanรฉ URI pro pล™esmฤ›rovรกnรญ**\n\nDo pole **โ€žAutorizovanรฉ identifikรกtory URI pro pล™esmฤ›rovรกnรญโ€œ** pล™idejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraฤte `your-server.com` domรฉnou nebo IP adresou vaลกeho serveru (v pล™รญpadฤ› potล™eby uveฤte i port, napล™. `http://45.33.32.156:20128/callback` ).\n\n**4. Uloลพte a zkopรญrujte pล™ihlaลกovacรญ รบdaje**\n\nPo vytvoล™enรญ Google zobrazรญ **ID klienta** a **tajnรฝ kรณd klienta** .\n\n**5. Nastavenรญ promฤ›nnรฝch prostล™edรญ**\n\nVe vaลกem souboru `.env` (nebo promฤ›nnรฝch prostล™edรญ Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu pล™ipojit**\n\nล˜รญdicรญ panel โ†’ Poskytovatelรฉ โ†’ Antigravity (nebo Gemini CLI) โ†’ OAuth\n\nGoogle nynรญ bude sprรกvnฤ› pล™esmฤ›rovรกvat na `https://your-server.com/callback` .\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nPokud si teฤ nechcete nastavovat vlastnรญ pล™ihlaลกovacรญ รบdaje, mลฏลพete stรกle pouลพรญt **ruฤnรญ postup pro URL** :\n\n1. OmniRoute otevรญrรก autorizaฤnรญ URL od Googlu\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru).\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe (i kdyลพ se strรกnka nenaฤte)\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute.\n5. Kliknฤ›te na **โ€žPล™ipojitโ€œ**\n\n> To funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na to, zda se naฤetla pล™esmฤ›rovacรญ strรกnka.\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nChcete-li zรญskat pล™รญstup k pล™ihlaลกovacรญm รบdajลฏm bez vlastnรญ konfigurace, mลฏลพete pouลพรญt nรกsledujรญcรญ postup:\n\n1. OmniRoute otevล™e URL autorizace Google\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru)\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute\n5. Kliknฤ›te na **โ€žPล™ipojit\"**\n\n> Toto ล™eลกenรญ funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na naฤtenรญ pล™esmฤ›rovacรญ strรกnky.\n\n---\n\n## ๐Ÿ› ๏ธ Technologickรฝ stack\n\n
\nKliknutรญm rozbalรญte podrobnosti o technologickรฉm stacku\n
\n\n- **Runtime** : Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ **nenรญ podporovรกn** โ€” nativnรญ binรกrnรญ soubory `better-sqlite3` jsou nekompatibilnรญ)\n- **Jazyk** : TypeScript 5.9 โ€” **100% TypeScript** napล™รญฤ `src/` a `open-sse/` ( `any` v zรกkladnรญch modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databรกze** : LowDB (JSON) + SQLite (stav domรฉny + protokoly proxy + audit MCP + rozhodnutรญ o smฤ›rovรกnรญ)\n- **Schรฉmata** : Zod (validace I/O nรกstrojลฏ MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamovรกnรญ** : Udรกlosti odeslanรฉ serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klรญฤe + autorizace s rozsahem MCP\n- **Testovรกnรญ** : Node.js test runner + Vitest (900+ testลฏ vฤetnฤ› unit, integraฤnรญch, E2E)\n- **CI/CD** : Akce GitHubu (automatickรฉ publikovรกnรญ v npm + Docker Hub pล™i vydรกnรญ)\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **Balรญฤek** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistiฤ, exponenciรกlnรญ odstavenรญ, ochrana proti hromลฏm, faleลกnรฉ TLS, automatickรฉ kombinovanรฉ samoopravovรกnรญ\n\n---\n\n## ๐Ÿ“– Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uลพivatelskรก pล™รญruฤka](docs/USER_GUIDE.md) | Poskytovatelรฉ, kombinace, integrace CLI, nasazenรญ |\n| [Referenฤnรญ informace k API](docs/API_REFERENCE.md) | Vลกechny koncovรฉ body s pล™รญklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nรกstrojลฏ MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamovรกnรญ, sprรกva รบloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorovรฉ bodovรกnรญ, balรญฤky reลพimลฏ, samolรฉฤba |\n| [Odstraลˆovรกnรญ problรฉmลฏ](docs/TROUBLESHOOTING.md) | Bฤ›ลพnรฉ problรฉmy a jejich ล™eลกenรญ |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a internรญ prvky systรฉmu |\n| [Pล™ispรญvรกnรญ](CONTRIBUTING.md) | Nastavenรญ a pokyny pro vรฝvoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpeฤnostnรญ zรกsady](SECURITY.md) | Hlรกลกenรญ zranitelnostรญ a bezpeฤnostnรญ postupy |\n| [Nasazenรญ virtuรกlnรญho poฤรญtaฤe](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletnรญ prลฏvodce: Nastavenรญ virtuรกlnรญho poฤรญtaฤe + nginx + Cloudflare |\n| [Galerie funkcรญ](docs/FEATURES.md) | Vizuรกlnรญ prohlรญdka ล™รญdicรญho panelu se snรญmky obrazovky |\n| [Kontrolnรญ seznam vydรกnรญ](docs/RELEASE_CHECKLIST.md) | Kroky ovฤ›ล™enรญ pล™ed vydรกnรญm |\n\n---\n\n## ๐Ÿ—บ๏ธ Plรกn\n\nOmniRoute mรก **v plรกnu vรญce neลพ 210 funkcรญ** v nฤ›kolika fรกzรญch vรฝvoje. Zde jsou klรญฤovรฉ oblasti:\n\n| Kategorie | Plรกnovanรฉ funkce | Hlavnรญ body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| ๐Ÿง  **Smฤ›rovรกnรญ a inteligence** | 25+ | Smฤ›rovรกnรญ s nejniลพลกรญ latencรญ, smฤ›rovรกnรญ zaloลพenรฉ na tagech, kontrola kvรณt pล™ed vรฝstupem, vรฝbฤ›r รบฤtu P2C |\n| ๐Ÿ”’ **Zabezpeฤenรญ a dodrลพovรกnรญ pล™edpisลฏ** | 20+ | Zpevnฤ›nรญ SSRF, maskovรกnรญ pล™ihlaลกovacรญch รบdajลฏ, limit rychlosti pro kaลพdรฝ koncovรฝ bod, stanovenรญ rozsahu klรญฤลฏ pro sprรกvu |\n| ๐Ÿ“Š **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledovรกnรญ kvรณt v reรกlnรฉm ฤase, sledovรกnรญ nรกkladลฏ podle modelu |\n| ๐Ÿ”„ **Integrace poskytovatelลฏ** | 20+ | Dynamickรฝ registr modelลฏ, doba zchlazenรญ poskytovatelลฏ, Codex pro vรญce รบฤtลฏ, analรฝza kvรณt Copilota |\n| โšก **Vรฝkon** | 15+ | Dvojitรก vrstva mezipamฤ›ti, mezipamฤ›ลฅ vรฝzev, mezipamฤ›ลฅ odpovฤ›dรญ, udrลพovรกnรญ streamovรกnรญ, dรกvkovรฉ API |\n| ๐ŸŒ **Ekosystรฉm** | 10+ | WebSocket API, horkรฉ opฤ›tovnรฉ naฤรญtรกnรญ konfigurace, distribuovanรฉ รบloลพiลกtฤ› konfigurace, komerฤnรญ reลพim |\n\n### ๐Ÿ”œ Jiลพ brzy\n\n- ๐Ÿ”— **Integrace OpenCode** โ€” Nativnรญ podpora poskytovatelลฏ pro IDE kรณdovรกnรญ s AI v OpenCode\n- ๐Ÿ”— **Integrace TRAE** โ€” Plnรก podpora vรฝvojovรฉho rรกmce TRAE pro umฤ›lou inteligenci\n- ๐Ÿ“ฆ **Dรกvkovรฉ API** โ€” Asynchronnรญ dรกvkovรฉ zpracovรกnรญ hromadnรฝch poลพadavkลฏ\n- ๐ŸŽฏ **Smฤ›rovรกnรญ na zรกkladฤ› tagลฏ** โ€” Smฤ›rovรกnรญ poลพadavkลฏ na zรกkladฤ› vlastnรญch tagลฏ a metadat\n- ๐Ÿ’ฐ **Strategie nejniลพลกรญch nรกkladลฏ** โ€“ Automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n> ๐Ÿ“ รšplnรฉ specifikace funkcรญ jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobnรฝch specifikacรญ)\n\n---\n\n## ๐Ÿ‘ฅ Pล™ispฤ›vatelรฉ\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Pล™ispฤ›vatelรฉ](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak pล™ispฤ›t\n\n1. Vytvoล™enรญ forku repozitรกล™e\n2. Vytvoล™te si vlastnรญ vฤ›tev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrฤte zmฤ›ny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do vฤ›tve ( `git push origin feature/amazing-feature` )\n5. Otevล™รญt ลพรกdost o zmฤ›ny (pull request)\n\nPodrobnรฉ pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydรกnรญ novรฉ verze\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Hvฤ›zdnรก historie\n\n## Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## ๐Ÿ™ Podฤ›kovรกnรญ\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** โ€“ pลฏvodnรญmu projektu, kterรฝ inspiroval tento fork. OmniRoute stavรญ na tomto neuvฤ›ล™itelnรฉm zรกkladu s dalลกรญmi funkcemi, multimodรกlnรญmi API a kompletnรญm pล™epsรกnรญm TypeScriptu.\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€“ pลฏvodnรญ implementaci Go, kterรก inspirovala tento JavaScriptovรฝ port.\n\n---\n\n## ๐Ÿ“„ Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n
\n Vytvoล™eno s โค๏ธ pro vรฝvojรกล™e, kteล™รญ programujรญ 24 hodin dennฤ›, 7 dnรญ v tรฝdnu\n
\n

omniroute.online

\n
\n\n"}, "9eb3c2349439e57999804619dfe7658844981a2a": {"t": 1785764462.7234874, "n": 92285, "h": "34425aa96dd72148", "c": "# ๐Ÿš€ OmniRoute โ€” Bezplatnรก brรกna umฤ›lรฉ inteligence\n\n### Nikdy nepล™estรกvejte s kรณdovรกnรญm. Chytrรฉ smฤ›rovรกnรญ k **BEZPLATNรM a levnรฝm modelลฏm AI** s automatickรฝm pล™epรญnรกnรญm mezi zรกloลพnรญmi systรฉmy.\n\n_Vรกลก univerzรกlnรญ API proxy โ€“ jeden endpoint, vรญce neลพ 44 poskytovatelลฏ, nulovรฉ vรฝpadky. Nynรญ s orchestracรญ agentลฏ **MCP a A2A** ._\n\n**Dokonฤenรญ chatu โ€ข Vklรกdรกnรญ โ€ข Generovรกnรญ obrรกzkลฏ โ€ข Video โ€ข Hudba โ€ข Audio โ€ข Zmฤ›na poล™adรญ โ€ข **Vyhledรกvรกnรญ na webu** โ€ข MCP server โ€ข A2A protokol โ€ข 100% TypeScript**\n\n---\n\n
\n
\n

\"verze\"Docker\"Licence\"\"Webovรฉ\"WhatsApp\"

\n

๐ŸŒ Webovรฉ strรกnky โ€ข ๐Ÿš€ Rychlรฝ start โ€ข ๐Ÿ’ก Funkce โ€ข ๐Ÿ“– Dokumentace โ€ข ๐Ÿ’ฐ Cenรญk โ€ข ๐Ÿ’ฌ WhatsApp

\n
\n\n๐ŸŒ **Dostupnรฉ v:** ๐Ÿ‡บ๐Ÿ‡ธ [Angliฤtina](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n### ๐Ÿ†• What's New in v3.0.0\n\n| Area | Change |\n| -------------------------- | --------------------------------------------------------------------------------- |\n| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| โœ… **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |\n| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| ๐ŸŒ **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| ๐Ÿ”ง **926 Tests** | Full test suite passes with 0 failures |\n\n### ๐Ÿ†• What's New in v3.0.0\n\n| Area | Change |\n| -------------------------- | --------------------------------------------------------------------------------- |\n| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| โœ… **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |\n| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| ๐ŸŒ **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| ๐Ÿ”ง **926 Tests** | Full test suite passes with 0 failures |\n\n---\n\n## ๐Ÿ–ผ๏ธ Hlavnรญ ovlรกdacรญ panel\n\n
\"ล˜รญdicรญ
\n\n---\n\n## ๐Ÿ“ธ Nรกhled ล™รญdicรญho panelu\n\n
\nKliknutรญm zobrazรญte snรญmky obrazovky z ล™รญdicรญho panelu\n
\n\n| Strana | Snรญmek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelรฉ** | ![Poskytovatelรฉ](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdravรญ** | ![Zdravรญ](docs/screenshots/04-health.png) |\n| **Pล™ekladatel** | ![Pล™ekladatel](docs/screenshots/05-translator.png) |\n| **Nastavenรญ** | ![Nastavenรญ](docs/screenshots/06-settings.png) |\n| **Nรกstroje CLI** | ![Nรกstroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly pouลพรญvรกnรญ** | ![Pouลพรญvรกnรญ](docs/screenshots/08-usage.png) |\n| **Koncovรฉ body** | ![Koncovรฉ body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### ๐Ÿค– Bezplatnรฝ poskytovatel umฤ›lรฉ inteligence pro vaลกe oblรญbenรฉ programรกtory\n\n_Pล™ipojte libovolnรฝ nรกstroj IDE nebo CLI s umฤ›lou inteligencรญ pล™es OmniRoute โ€” bezplatnou API brรกnu pro neomezenรฉ kรณdovรกnรญ._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\"OpenClaw\"
OpenClaw
โญ 205 tisรญc 		\"NanoBot\"
NanoBot
โญ 20,9 tisรญc 		\"PicoClaw\"
PicoClaw
โญ 14,6 tisรญc 		\"ZeroClaw\"
ZeroClaw
โญ 9,9 tisรญc 		\"ลฝeleznรฝ
ลฝeleznรฝ drรกp
โญ 2,1 tisรญce
\"OpenCode\"
OpenCode
โญ 106 tisรญc 		\"Codex
Codex CLI
โญ 60,8 tisรญc 		\"Claude
Claude Code
โญ 67,3 tisรญc 		\"Gemini
Gemini CLI
โญ 94,7 tisรญc 		\"Kilo
Kilo kรณd
โญ 15,5 tisรญc
\n\n๐Ÿ“ก Vลกichni agenti se pล™ipojujรญ pล™es http://localhost:20128/v1 nebo http://cloud.omniroute.online/v1 โ€” jedna konfigurace, neomezenรฉ modely a kvรณty\n\n---\n\n## ๐Ÿค” Proฤ OmniRoute?\n\n**Pล™estaลˆte plรฝtvat penฤ›zi a narรกลพet na limity:**\n\n- Kvรณta pล™edplatnรฉho vyprลกรญ kaลพdรฝ mฤ›sรญc\n- Limity rychlosti vรกm zabrรกnรญ v kรณdovรกnรญ\n- Drahรก API (20โ€“50 USD/mฤ›sรญc na poskytovatele)\n- Ruฤnรญ pล™epรญnรกnรญ mezi poskytovateli\n\n**OmniRoute to ล™eลกรญ:**\n\n- โœ… **Maximalizujte pล™edplatnรฉ** โ€“ Sledujte kvรณtu, vyuลพijte kaลพdou ฤรกstku pล™ed resetovรกnรญm\n- โœ… **Automatickรฉ zรกloลพnรญ** โ€“ Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma, ลพรกdnรฉ vรฝpadky\n- โœ… **Vรญce รบฤtลฏ** โ€“ Round-robin mezi รบฤty u jednotlivรฝch poskytovatelลฏ\n- โœ… **Univerzรกlnรญ** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakรฝmkoli nรกstrojem CLI\n\n---\n\n## ๐Ÿ“ง Podpora\n\n> ๐Ÿ’ฌ **Pล™idejte se k naลกรญ komunitฤ›!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Zรญskejte pomoc, sdรญlejte tipy a buฤte v obraze.\n\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problรฉmy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitnรญ skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Pล™ispรญvรกnรญ** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevล™ete ลพรกdost o pล™รญspฤ›vek nebo si vyberte `good first issue`\n- **Pลฏvodnรญ projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Hlรกsรญte chybu?\n\nPล™i otevรญrรกnรญ problรฉmu spusลฅte pล™รญkaz system-info a pล™iloลพte vygenerovanรฝ soubor:\n\n```bash\nnpm run system-info\n```\n\nTรญm se vygeneruje soubor `system-info.txt` s verzรญ Node.js, verzรญ OmniRoute, podrobnostmi o operaฤnรญm systรฉmu, nainstalovanรฝmi nรกstroji CLI (iflow, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systรฉmovรฝmi balรญฤky โ€“ vลกe, co potล™ebujeme k rychlรฉ reprodukci vaลกeho problรฉmu. Soubor pล™iloลพte pล™รญmo k vaลกemu problรฉmu na GitHubu.\n\n---\n\n## ๐Ÿ”„ Jak to funguje\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ Co ล™eลกรญ OmniRoute โ€” 30 skuteฤnรฝch problรฉmลฏ a pล™รญpadลฏ pouลพitรญ\n\n> **Kaลพdรฝ vรฝvojรกล™ pouลพรญvajรญcรญ nรกstroje umฤ›lรฉ inteligence se s tฤ›mito problรฉmy setkรกvรก dennฤ›.** OmniRoute byl vytvoล™en tak, aby je vลกechny vyล™eลกil โ€“ od pล™ekroฤenรญ nรกkladลฏ po regionรกlnรญ bloky, od nefunkฤnรญch tokลฏ OAuth aลพ po operace s protokoly a sledovatelnost v podniku.\n\n
\n๐Ÿ’ธ 1. โ€žPlatรญm si drahรฉ pล™edplatnรฉ, ale stรกle mฤ› ruลกรญ limityโ€œ\n
\n\nVรฝvojรกล™i platรญ za Claude Pro, Codex Pro nebo GitHub Copilot 20โ€“200 dolarลฏ mฤ›sรญฤnฤ›. I pล™i platbฤ› mรก kvรณta strop โ€“ 5 hodin pouลพรญvรกnรญ, tรฝdennรญ limity nebo limity rychlosti za minutu. Uprostล™ed kรณdovacรญ relace poskytovatel pล™estane reagovat a vรฝvojรกล™ ztrรกcรญ plynulost a produktivitu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Inteligentnรญ ฤtyล™รบrovลˆovรก zรกloลพnรญ sluลพba** โ€“ Pokud dojde kvรณta pล™edplatnรฉho, โ€‹โ€‹automaticky se pล™esmฤ›ruje na API klรญฤ โ†’ Levnรฉ โ†’ Zdarma bez manuรกlnรญho zรกsahu\n- **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** โ€“ Zobrazuje spotล™ebu tokenลฏ v reรกlnรฉm ฤase s odpoฤรญtรกvรกnรญm resetovรกnรญ (5 hodin, dennฤ›, tรฝdnฤ›)\n- **Podpora vรญce รบฤtลฏ** โ€“ Vรญce รบฤtลฏ u jednoho poskytovatele s automatickรฝm pล™epรญnรกnรญm โ€“ kdyลพ jeden dojde, pล™epne se na dalลกรญ\n- **Vlastnรญ kombinace** โ€” Pล™izpลฏsobitelnรฉ zรกloลพnรญ ล™etฤ›zce se 6 strategiemi vyvaลพovรกnรญ (fill-first, round robin, P2C, nรกhodnรฉ, nejmรฉnฤ› pouลพรญvanรฉ, nรกkladovฤ› optimalizovanรฉ)\n- **Codex Business Quotas** โ€” Sledovรกnรญ kvรณt pracovnรญho prostoru firmy/tรฝmu pล™รญmo v dashboardu\n\n
\n๐Ÿ”Œ 2. โ€žPotล™ebuji pouลพรญt vรญce poskytovatelลฏ, ale kaลพdรฝ mรก jinรฉ APIโ€œ\n
\n\nOpenAI pouลพรญvรก jeden formรกt, Claude (Anthropic) jinรฝ a Gemini jeลกtฤ› tล™etรญ. Pokud chce vรฝvojรกล™ testovat modely od rลฏznรฝch poskytovatelลฏ nebo mezi nimi pล™echรกzet, musรญ pล™ekonfigurovat SDK, zmฤ›nit koncovรฉ body a vypoล™รกdat se s nekompatibilnรญmi formรกty. Vlastnรญ poskytovatelรฉ (FriendLI, NIM) majรญ nestandardnรญ koncovรฉ body modelลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sjednocenรฝ koncovรฝ bod** โ€” Jeden `http://localhost:20128/v1` slouลพรญ jako proxy pro vลกech 67+ poskytovatelลฏ.\n- **Pล™eklad formรกtu** โ€” Automatickรฝ a transparentnรญ: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Sanitizace odpovฤ›dรญ** โ€” Odstraลˆuje nestandardnรญ pole ( `x_groq` , `usage_breakdown` , `service_tier` ), kterรก poruลกujรญ OpenAI SDK v1.83+\n- **Normalizace rolรญ** โ€” Pล™evรกdรญ `developer` โ†’ `system` pro poskytovatele bez OpenAI; `system` โ†’ `user` pro GLM/ERNIE\n- **Extrakce tagลฏ Think** โ€” Extrahuje bloky `` z modelลฏ, jako je DeepSeek R1, do standardizovanรฉho `reasoning_content`\n- **Strukturovanรฝ vรฝstup pro Gemini** โ€” `json_schema` โ†’ automatickรก konverze `responseMimeType` / `responseSchema`\n- **Vรฝchozรญ hodnota `stream` je `false`** โ€“ Odpovรญdรก specifikaci OpenAI, ฤรญmลพ se zabrรกnรญ neoฤekรกvanรฉmu SSE v Python/Rust/Go SDK.\n\n
\n๐ŸŒ 3. โ€žMลฏj poskytovatel AI blokuje mลฏj region/zemiโ€œ\n
\n\nPoskytovatelรฉ jako OpenAI/Codex blokujรญ pล™รญstup z urฤitรฝch geografickรฝch oblastรญ. Uลพivatelรฉ se bฤ›hem pล™ipojenรญ OAuth a API dostรกvajรญ k chybรกm jako `unsupported_country_region_territory` . To je obzvlรกลกtฤ› frustrujรญcรญ pro vรฝvojรกล™e z rozvojovรฝch zemรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **3รบrovลˆovรก konfigurace proxy** โ€“ Konfigurovatelnรก proxy na 3 รบrovnรญch: globรกlnรญ (veลกkerรฝ provoz), pro jednotlivรฉ poskytovatele (pouze jeden poskytovatel) a pro jednotlivรฉ pล™ipojenรญ/klรญฤ\n- **Barevnฤ› kรณdovanรฉ odznaky proxy** โ€“ Vizuรกlnรญ indikรกtory: ๐ŸŸข globรกlnรญ proxy, ๐ŸŸก proxy poskytovatele, ๐Ÿ”ต proxy pล™ipojenรญ, vลพdy zobrazujรญcรญ IP adresu\n- **Vรฝmฤ›na tokenลฏ OAuth prostล™ednictvรญm proxy** โ€“ tok OAuth takรฉ prochรกzรญ pล™es proxy, ฤรญmลพ se ล™eลกรญ `unsupported_country_region_territory`\n- **Testy pล™ipojenรญ pล™es proxy** โ€“ Testy pล™ipojenรญ pouลพรญvajรญ nakonfigurovanรฝ proxy (jiลพ ลพรกdnรฉ pล™รญmรฉ obchรกzenรญ)\n- **Podpora SOCKS5** โ€” Plnรก podpora proxy SOCKS5 pro odchozรญ smฤ›rovรกnรญ\n- **TLS Fingerprint Spoofing** โ€” Otisk prstu TLS podobnรฝ prohlรญลพeฤi pomocรญ `wreq-js` pro obchรกzenรญ detekce botลฏ\n- **๐Ÿ” Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** โ€” Zmฤ›nรญ poล™adรญ zรกhlavรญ a polรญ v tฤ›le serveru tak, aby odpovรญdala nativnรญm binรกrnรญm podpisลฏm v CLI, ฤรญmลพ drasticky sniลพuje riziko nahlaลกovรกnรญ รบฤtu. IP adresa proxy je zachovรกna โ€” zรญskรกte souฤasnฤ› stealth **i** maskovรกnรญ IP adresy.\n\n
\n๐Ÿ†“ 4. โ€žChci pouลพรญvat umฤ›lou inteligenci pro kรณdovรกnรญ, ale nemรกm penรญzeโ€œ\n
\n\nNe kaลพdรฝ si mลฏลพe dovolit zaplatit 20โ€“200 dolarลฏ mฤ›sรญฤnฤ› za pล™edplatnรฉ AI. Studenti, vรฝvojรกล™i z rozvรญjejรญcรญch se zemรญ, amatรฉล™i a freelanceล™i potล™ebujรญ pล™รญstup ke kvalitnรญm modelลฏm za nulovou cenu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vestavฤ›nรญ poskytovatelรฉ bezplatnรฉ รบrovnฤ›** โ€” Nativnรญ podpora pro 100% bezplatnรฉ poskytovatele: iFlow (5 neomezenรฝch modelลฏ pล™es OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezenรฉ modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisรญc tokenลฏ/mฤ›sรญc zdarma)\n- **Ollama Cloud** โ€” Cloudovฤ› hostovanรฉ modely Ollama na `api.ollama.com` s bezplatnou รบrovnรญ โ€žLight usageโ€œ; pouลพijte prefix `ollamacloud/`\n- **Kombinace pouze zdarma** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = 0 $/mฤ›sรญc s nulovรฝmi prostoji\n- **NVIDIA NIM Free Access** โ€” ~40 RPM developerskรฝ pล™รญstup k vรญce neลพ 70 modelลฏm na build.nvidia.com (pล™echod z kreditลฏ na ฤistรฉ limity rychlosti)\n- **Strategie optimalizace nรกkladลฏ** โ€“ Strategie smฤ›rovรกnรญ, kterรก automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n
\n๐Ÿ”’ 5. โ€žPotล™ebuji chrรกnit svou brรกnu umฤ›lรฉ inteligence pล™ed neoprรกvnฤ›nรฝm pล™รญstupemโ€œ\n
\n\nPล™i zpล™รญstupnฤ›nรญ brรกny umฤ›lรฉ inteligence sรญti (LAN, VPS, Docker) mลฏลพe kdokoli s adresou spotล™ebovat tokeny/kvรณtu vรฝvojรกล™e. Bez ochrany jsou API zranitelnรก vลฏฤi zneuลพitรญ, prompt injection a dalลกรญmu zneuลพitรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sprรกva klรญฤลฏ API** โ€“ generovรกnรญ, rotace a vymezovรกnรญ rozsahu pro kaลพdรฉho poskytovatele s vyhrazenou strรกnkou `/dashboard/api-manager`\n- **Oprรกvnฤ›nรญ na รบrovni modelu** โ€“ Omezenรญ klรญฤลฏ API na konkrรฉtnรญ modely ( `openai/*` , zรกstupnรฉ znaky) pomocรญ pล™epรญnaฤe Povolit vลกe/Omezit\n- **Ochrana koncovรฝch bodลฏ API** โ€“ Vyลพaduje klรญฤ pro `/v1/models` a blokuje konkrรฉtnรญ poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** โ€” Vลกechny trasy dashboardu chrรกnฤ›nรฉ middlewarem `withAuth` + tokeny CSRF\n- **Omezovaฤ rychlosti** โ€” Omezovรกnรญ rychlosti na IP s konfigurovatelnรฝmi okny\n- **Filtrovรกnรญ IP adres** โ€” Seznam povolenรฝch/blokovanรฝch adres pro ล™รญzenรญ pล™รญstupu\n- **Ochrana proti vklรกdรกnรญ vรฝzev** โ€“ Sanitizace proti ลกkodlivรฝm vzorcลฏm vรฝzev\n- **ล ifrovรกnรญ AES-256-GCM** โ€“ pล™ihlaลกovacรญ รบdaje jsou v klidovรฉm stavu ลกifrovรกny\n\n
\n๐Ÿ›‘ 6. โ€žMลฏj poskytovatel selhal a jรก ztratil/a programovacรญ tokโ€œ\n
\n\nPoskytovatelรฉ umฤ›lรฉ inteligence se mohou stรกt nestabilnรญmi, vracet chyby 5xx nebo dosรกhnout doฤasnรฝch limitลฏ rychlosti. Pokud je vรฝvojรกล™ zรกvislรฝ na jedinรฉm poskytovateli, je jeho prรกce pล™eruลกena. Bez jistiฤลฏ mลฏลพe opakovanรฉ pokusy vรฉst k pรกdu aplikace.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Jistiฤ pro kaลพdรฝ model** โ€“ Automatickรฉ otevรญrรกnรญ/zavรญrรกnรญ s konfigurovatelnรฝmi prahovรฝmi hodnotami a dobou ochlazovรกnรญ (Zavล™eno/Otevล™eno/Poloviฤnรญ otevล™enรญ), rozsah definovanรฝ pro kaลพdรฝ model, aby se zabrรกnilo kaskรกdovรกnรญ blokลฏ\n- **Exponenciรกlnรญ odklad** โ€” Progresivnรญ zpoลพdฤ›nรญ opakovรกnรญ\n- **Anti-Thundering Herd** โ€” ochrana Mutex + semafor proti soubฤ›ลพnรฝm bouล™รญm s opakovanรฝmi pokusy\n- **Kombinovanรฉ zรกloลพnรญ ล™etฤ›zce** โ€“ Pokud primรกrnรญ poskytovatel selลพe, automaticky se propadne ล™etฤ›zcem bez zรกsahu.\n- **Kombinovanรฝ jistiฤ** โ€“ Automaticky deaktivuje selhรกvajรญcรญho poskytovatele v rรกmci kombinovanรฉho ล™etฤ›zce\n- **Dashboard stavu** โ€” Monitorovรกnรญ provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti, latence p50/p95/p99\n\n
\n๐Ÿ”ง 7. โ€žKonfigurace kaลพdรฉho nรกstroje umฤ›lรฉ inteligence je zdlouhavรก a opakujรญcรญ seโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Kaลพdรฝ nรกstroj potล™ebuje jinou konfiguraci (API endpoint, klรญฤ, model). Pล™ekonfigurovรกnรญ pล™i zmฤ›nฤ› poskytovatele nebo modelu je ztrรกta ฤasu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel nรกstrojลฏ CLI** โ€” Vyhrazenรก strรกnka s nastavenรญm jednรญm kliknutรญm pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generรกtor konfigurace GitHub Copilot** โ€“ Generuje `chatLanguageModels.json` pro VS Code s hromadnรฝm vรฝbฤ›rem modelu\n- **Prลฏvodce zavรกdฤ›nรญm** โ€“ 4krokovรฉ nastavenรญ pro zaฤรญnajรญcรญ uลพivatele\n- **Jeden koncovรฝ bod, vลกechny modely** โ€“ jednou nakonfigurujte `http://localhost:20128/v1` a zรญskejte pล™รญstup k vรญce neลพ 44 poskytovatelลฏm\n\n
\n๐Ÿ”‘ 8. โ€žSprรกva OAuth tokenลฏ od vรญce poskytovatelลฏ je pekloโ€œ\n
\n\nClaude Code, Codex, Gemini CLI, Copilot โ€“ vลกechny pouลพรญvajรญ OAuth 2.0 s tokeny s vyprลกenรญm platnosti. Vรฝvojรกล™i se musรญ neustรกle znovu autentizovat, ล™eลกit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdรกlenรฝch serverech. Obzvlรกลกtฤ› problematickรฝ je OAuth v LAN/VPS.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Automatickรก aktualizace tokenลฏ** โ€“ Tokeny OAuth se obnovujรญ na pozadรญ pล™ed vyprลกenรญm platnosti.\n- **Vestavฤ›nรฝ OAuth 2.0 (PKCE)** โ€“ Automatickรฝ tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow\n- **Multi-Account OAuth** โ€” Vรญce รบฤtลฏ na poskytovatele prostล™ednictvรญm extrakce tokenลฏ JWT/ID\n- **OAuth LAN/Remote Fix** โ€” Detekce privรกtnรญ IP adresy pro `redirect_uri` + manuรกlnรญ reลพim URL pro vzdรกlenรฉ servery\n- **OAuth Behind Nginx** โ€” Pouลพรญvรก `window.location.origin` pro kompatibilitu s reverznรญ proxy\n- **Prลฏvodce vzdรกlenรฝm OAuth** โ€“ Podrobnรฝ nรกvod k pล™ihlaลกovacรญm รบdajลฏm Google Cloud na VPS/Dockeru\n\n
\n๐Ÿ“Š 9. โ€žNevรญm, kolik utrรกcรญm ani kdeโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ vรญce placenรฝch poskytovatelลฏ, ale nemajรญ jednotnรฝ pล™ehled o vรฝdajรญch. Kaลพdรฝ poskytovatel mรก svลฏj vlastnรญ fakturaฤnรญ panel, ale neexistuje ลพรกdnรฝ konsolidovanรฝ pล™ehled. Mohou se hromadit neoฤekรกvanรฉ nรกklady.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard pro analรฝzu nรกkladลฏ** โ€“ Sledovรกnรญ nรกkladลฏ na token a sprรกva rozpoฤtu pro kaลพdรฉho poskytovatele\n- **Rozpoฤtovรฉ limity na รบroveลˆ** โ€“ Strop vรฝdajลฏ na รบroveลˆ, kterรฝ spouลกtรญ automatickรฝ zรกloลพnรญ reลพim\n- **Konfigurace cen podle modelu** โ€“ Konfigurovatelnรฉ ceny podle modelu\n- **Statistiky pouลพitรญ pro kaลพdรฝ klรญฤ API** โ€” Poฤet poลพadavkลฏ a ฤasovรฉ razรญtko poslednรญho pouลพitรญ pro kaลพdรฝ klรญฤ\n- **Analytickรฝ panel** โ€“ Statistickรฉ karty, graf vyuลพitรญ modelu, tabulka poskytovatelลฏ s mรญrou รบspฤ›ลกnosti a latencรญ\n\n
\n๐Ÿ› 10. โ€žNedokรกลพu diagnostikovat chyby a problรฉmy ve volรกnรญ umฤ›lรฉ inteligence.โ€œ\n
\n\nKdyลพ volรกnรญ selลพe, vรฝvojรกล™ nevรญ, zda se jednalo o limit rychlosti, vyprลกelรฝ token, ลกpatnรฝ formรกt nebo chybu poskytovatele. Fragmentovanรฉ protokoly napล™รญฤ rลฏznรฝmi terminรกly. Bez sledovatelnosti je ladฤ›nรญ metodou pokus-omyl.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel jednotnรฝch protokolลฏ** โ€“ 4 karty: Protokoly poลพadavkลฏ, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlรญลพeฤ protokolลฏ konzole** โ€” Prohlรญลพeฤ protokolลฏ v reรกlnรฉm ฤase ve stylu terminรกlu s barevnฤ› kรณdovanรฝmi รบrovnฤ›mi, automatickรฝm posouvรกnรญm, vyhledรกvรกnรญm a filtrovรกnรญm\n- **Protokoly proxy SQLite** โ€“ trvalรฉ protokoly, kterรฉ pล™eลพijรญ restart serveru\n- **Pล™ekladaฤskรฉ hล™iลกtฤ›** โ€” 4 reลพimy ladฤ›nรญ: Hล™iลกtฤ› (pล™eklad formรกtu), Tester chatu (okruลพnรญ), Testovacรญ stลฏl (dรกvkovรฝ), ลฝivรฝ monitor (v reรกlnรฉm ฤase)\n- **Telemetrie poลพadavkลฏ** โ€” latence p50/p95/p99 + trasovรกnรญ X-Request-Id\n- **Souborovรฉ protokolovรกnรญ s rotacรญ** โ€“ Konzolovรฝ interceptor zachycuje vลกe do protokolu JSON s rotacรญ na zรกkladฤ› velikosti\n- **Zprรกva o systรฉmovรฝch informacรญch** โ€” pล™รญkaz `npm run system-info` vygeneruje `system-info.txt` s kompletnรญm popisem vaลกeho prostล™edรญ (verze uzlu, verze OmniRoute, operaฤnรญ systรฉm, nรกstroje CLI, stav Dockeru/PM2). Pล™iloลพte jej pล™i hlรกลกenรญ problรฉmลฏ pro okamลพitรฉ tล™รญdฤ›nรญ.\n\n
\n๐Ÿ—๏ธ 11. โ€žNasazenรญ a รบdrลพba brรกny je sloลพitรกโ€œ\n
\n\nInstalace, konfigurace a รบdrลพba AI proxy v rลฏznรฝch prostล™edรญch (lokรกlnรญ, VPS, Docker, cloud) je pracnรก. Problรฉmy, jako jsou pevnฤ› zakรณdovanรฉ cesty, `EACCES` u adresรกล™ลฏ, konflikty portลฏ a multiplatformnรญ sestavenรญ, pล™ispรญvajรญ k obtรญลพรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **npm globรกlnรญ instalace** โ€” `npm install -g omniroute && omniroute` โ€” hotovo\n- **Docker Multi-Platform** โ€” AMD64 + nativnรญ ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** โ€” `base` (bez nรกstrojลฏ CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopovรก aplikace Electron** โ€” Nativnรญ aplikace pro Windows/macOS/Linux se systรฉmovou liลกtou, automatickรฝm spuลกtฤ›nรญm a offline reลพimem\n- **Reลพim rozdฤ›lenรฝch portลฏ** โ€“ API a ล™รญdicรญ panel na samostatnรฝch portech pro pokroฤilรฉ scรฉnรกล™e (reverznรญ proxy, sรญลฅovรกnรญ kontejnerลฏ)\n- **Cloud Sync** โ€“ Konfigurace synchronizace mezi zaล™รญzenรญmi pomocรญ Cloudflare Workers\n- **Zรกlohy databรกzรญ** โ€” Automatickรฉ zรกlohovรกnรญ, obnovenรญ, export a import vลกech nastavenรญ\n\n
\n๐ŸŒ 12. โ€žRozhranรญ je pouze v angliฤtinฤ› a mลฏj tรฝm nemluvรญ anglickyโ€œ\n
\n\nTรฝmy v neanglicky mluvรญcรญch zemรญch, zejmรฉna v Latinskรฉ Americe, Asii a Evropฤ›, se potรฝkajรญ s rozhranรญmi pouze v angliฤtinฤ›. Jazykovรฉ bariรฉry sniลพujรญ mรญru pล™ijetรญ a zvyลกujรญ chyby v konfiguraci.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard i18n โ€” 30 jazykลฏ** โ€” Vลกech 500+ klรกves je pล™eloลพeno vฤetnฤ› arabลกtiny, bulharลกtiny, dรกnลกtiny, nฤ›mฤiny, ลกpanฤ›lลกtiny, finลกtiny, francouzลกtiny, hebrejลกtiny, hindลกtiny, maฤarลกtiny, indonรฉลกtiny, italลกtiny, japonลกtiny, korejลกtiny, malajลกtiny, holandลกtiny, norลกtiny, polลกtiny, portugalลกtiny (PT/BR), rumunลกtiny, ruลกtiny, slovenลกtiny, ลกvรฉdลกtiny, thajลกtiny, ukrajinลกtiny, vietnamลกtiny, ฤรญnลกtiny, filipรญnลกtiny a angliฤtiny\n- **Podpora RTL** โ€“ Podpora psanรญ zprava doleva pro arabลกtinu a hebrejลกtinu\n- **Vรญcejazyฤnรฉ soubory README** โ€” 30 kompletnรญch pล™ekladลฏ dokumentace\n- **Vรฝbฤ›r jazyka** โ€” Ikona glรณbu v zรกhlavรญ pro pล™epรญnรกnรญ v reรกlnรฉm ฤase\n\n
\n๐Ÿ”„ 13. โ€žPotล™ebuji vรญc neลพ jen chat โ€“ potล™ebuji vloลพenรฉ soubory, obrรกzky, zvuk.โ€œ\n
\n\nUmฤ›lรก inteligence nenรญ jen dokonฤovรกnรญ chatu. Vรฝvojรกล™i potล™ebujรญ generovat obrรกzky, pล™episovat zvuk, vytvรกล™et embeddedy pro RAG, mฤ›nit poล™adรญ dokumentลฏ a moderovat obsah. Kaลพdรฉ API mรก jinรฝ koncovรฝ bod a formรกt.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vklรกdรกnรญ** โ€” `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generovรกnรญ obrรกzkลฏ** โ€” `/v1/images/generations` s 10 poskytovateli a vรญce neลพ 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Pล™evod textu na video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Pล™evod textu na hudbu** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Pล™epis zvuku** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Pล™evod textu na ล™eฤ** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a dalลกรญ stรกvajรญcรญ poskytovatelรฉ\n- **Moderovรกnรญ** โ€” `/v1/moderations` โ€” Kontroly bezpeฤnosti obsahu\n- **Zmฤ›na poล™adรญ** โ€” `/v1/rerank` โ€” Zmฤ›na poล™adรญ relevance dokumentu\n- **Responses API** โ€” Plnรก podpora `/v1/responses` pro Codex\n\n
\n๐Ÿงช 14. โ€žNemรกm zpลฏsob, jak testovat a porovnรกvat kvalitu napล™รญฤ modely.โ€œ\n
\n\nVรฝvojรกล™i chtฤ›jรญ vฤ›dฤ›t, kterรฝ model je pro jejich pล™รญpad pouลพitรญ nejlepลกรญ โ€“ kรณd, pล™eklad, uvaลพovรกnรญ โ€“ ale ruฤnรญ porovnรกvรกnรญ je pomalรฉ. Neexistujรญ ลพรกdnรฉ integrovanรฉ nรกstroje pro vyhodnocovรกnรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Hodnocenรญ LLM** โ€” Testovรกnรญ Golden setu s 10 pล™edinstalovanรฝmi pล™รญpady zahrnujรญcรญmi pozdravy, matematiku, geografii, generovรกnรญ kรณdu, dodrลพovรกnรญ JSON, pล™eklad, markdown, odmรญtnutรญ bezpeฤnostnรญch poลพadavkลฏ\n- **4 strategie shody** โ€” `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovacรญ lavice pro pล™ekladatelskรฉ hล™iลกtฤ›** โ€” Dรกvkovรฉ testovรกnรญ s vรญce vstupy a oฤekรกvanรฝmi vรฝstupy, porovnรกnรญ napล™รญฤ poskytovateli\n- **Tester chatu** โ€” Kompletnรญ okruลพnรญ cesta s vizuรกlnรญm vykreslovรกnรญm odpovฤ›dรญ\n- **ลฝivรฝ monitor** โ€” Stream vลกech poลพadavkลฏ prochรกzejรญcรญch proxy serverem v reรกlnรฉm ฤase\n\n
\n๐Ÿ“ˆ 15. โ€žPotล™ebuji ลกkรกlovat bez ztrรกty vรฝkonuโ€œ\n
\n\nS rostoucรญm objemem poลพadavkลฏ generujรญ stejnรฉ otรกzky bez uklรกdรกnรญ do mezipamฤ›ti duplicitnรญ nรกklady. Bez idempotence duplicitnรญ poลพadavky plรฝtvajรญ zpracovรกnรญm. Je nutnรฉ dodrลพovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sรฉmantickรก mezipamฤ›ลฅ** โ€” Dvouvrstvรก mezipamฤ›ลฅ (signatura + sรฉmantika) sniลพuje nรกklady a latenci\n- **Idempotence poลพadavku** โ€” 5s deduplikaฤnรญ okno pro identickรฉ poลพadavky\n- **Detekce limitu rychlosti** โ€“ sledovรกnรญ otรกฤek za minutu (RPM), minimรกlnรญ mezera a maximรกlnรญ soubฤ›ลพnรฉ sledovรกnรญ pro kaลพdรฉho poskytovatele\n- **Upravitelnรฉ limity rychlosti** โ€” Konfigurovatelnรฉ vรฝchozรญ hodnoty v Nastavenรญ โ†’ Odolnost s perzistencรญ\n- **Mezipamฤ›ลฅ pro ovฤ›ล™enรญ klรญฤลฏ API** โ€” tล™รญvrstvรก mezipamฤ›ลฅ pro vรฝkon produkฤnรญho prostล™edรญ\n- **Dashboard s telemetriรญ** โ€“ latence p50/p95/p99, statistiky mezipamฤ›ti, dostupnost\n\n
\n๐Ÿค– 16. โ€žChci mรญt chovรกnรญ modelลฏ globรกlnฤ› pod kontrolouโ€œ\n
\n\nVรฝvojรกล™i, kteล™รญ chtฤ›jรญ vลกechny odpovฤ›di v urฤitรฉm jazyce, se specifickรฝm tรณnem nebo chtฤ›jรญ omezit tokeny pro uvaลพovรกnรญ. Konfigurace tรฉto funkce v kaลพdรฉm nรกstroji/poลพadavku je nepraktickรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vloลพenรญ systรฉmovรฉho prompt** โ€“ Globรกlnรญ prompt aplikovanรฝ na vลกechny poลพadavky\n- **Validace rozpoฤtu Thinking** โ€” ล˜รญzenรญ alokace tokenลฏ na poลพadavek (prลฏchozรญ, automatickรฉ, vlastnรญ, adaptivnรญ)\n- **6 strategiรญ smฤ›rovรกnรญ** โ€“ Globรกlnรญ strategie, kterรฉ urฤujรญ, jak jsou poลพadavky distribuovรกny\n- **Smฤ›rovaฤ se zรกstupnรฝmi znaky** โ€” vzory `provider/*` dynamicky smฤ›rujรญ k libovolnรฉmu poskytovateli\n- **Pล™epรญnรกnรญ povolenรญ/zakรกzรกnรญ kombinacรญ** โ€“ Pล™epรญnรกnรญ kombinacรญ pล™รญmo z ล™รญdicรญho panelu\n- **Pล™epรญnรกnรญ poskytovatele** โ€“ Povolenรญ/zakรกzรกnรญ vลกech pล™ipojenรญ pro poskytovatele jednรญm kliknutรญm\n- **Blokovanรญ poskytovatelรฉ** โ€“ Vylouฤenรญ konkrรฉtnรญch poskytovatelลฏ ze seznamu `/v1/models`\n\n
\n๐Ÿงฐ 17. โ€žPotล™ebuji nรกstroje MCP jako prvotล™รญdnรญ produktovรฉ funkce.โ€œ\n
\n\nMnoho bran umฤ›lรฉ inteligence odhaluje MCP pouze jako skrytรฝ implementaฤnรญ detail. Tรฝmy potล™ebujรญ viditelnou a spravovatelnou operaฤnรญ vrstvu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- MCP se zobrazuje v navigaci na ล™รญdicรญm panelu a na kartฤ› protokolu koncovรฉho bodu.\n- Vyhrazenรก strรกnka pro sprรกvu MCP s procesy, nรกstroji, rozsahy a auditem\n- Vestavฤ›nรฝ rychlรฝ start pro `omniroute --mcp` a onboarding klienta\n\n
\n๐Ÿง  18. โ€žPotล™ebuji orchestraci A2A se synchronizacรญ a cestami รบloh streamu.โ€œ\n
\n\nPracovnรญ postupy agentลฏ vyลพadujรญ jak pล™รญmรฉ odpovฤ›di, tak dlouhodobรฉ streamovanรฉ provรกdฤ›nรญ s kontrolou ลพivotnรญho cyklu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Koncovรฝ bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamovรกnรญ SSE s ลกรญล™enรญm stavu terminรกlu\n- Rozhranรญ API ลพivotnรญho cyklu รบloh pro `tasks/get` a `tasks/cancel`\n\n
\n๐Ÿ›ฐ๏ธ 19. โ€žPotล™ebuji skuteฤnรฝ stav procesu MCP, ne odhadovanรฝ stav.โ€œ\n
\n\nProvoznรญ tรฝmy potล™ebujรญ vฤ›dฤ›t, zda je MCP skuteฤnฤ› aktivnรญ, nejen zda je API dosaลพitelnรฉ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Soubor bฤ›hovรฉho heartbeatu s PID, ฤasovรฝmi razรญtky, transportem, poฤtem nรกstrojลฏ a reลพimem rozsahu\n- API stavu MCP kombinujรญcรญ prezenฤnรญ signรกl a nedรกvnou aktivitu\n- Karty stavu uลพivatelskรฉho rozhranรญ pro zobrazenรญ aktuรกlnosti procesลฏ/provozuschopnosti/prezenฤnรญho signรกlu\n\n
\n๐Ÿ“‹ 20. โ€žPotล™ebuji auditovatelnรฉ provedenรญ nรกstroje MCPโ€œ\n
\n\nKdyลพ nรกstroje mฤ›nรญ konfiguraci nebo spouลกtฤ›jรญ operaฤnรญ akce, tรฝmy potล™ebujรญ forenznรญ sledovatelnost.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Protokolovรกnรญ auditu pro volรกnรญ nรกstrojลฏ MCP s podporou SQLite\n- Filtruje podle nรกstroje, รบspฤ›chu/neรบspฤ›chu, klรญฤe API a strรกnkovรกnรญ\n- Tabulka auditu dashboardu + koncovรฉ body statistik pro automatizaci\n\n
\n๐Ÿ” 21. โ€žPotล™ebuji omezenรก oprรกvnฤ›nรญ MCP pro kaลพdou integraci.โ€œ\n
\n\nRลฏznรญ klienti by mฤ›li mรญt pล™รญstup ke kategoriรญm nรกstrojลฏ s nejniลพลกรญmi oprรกvnฤ›nรญmi.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- 9 detailnรญch MCP sond pro kontrolovanรฝ pล™รญstup k nรกstrojลฏm\n- Vynucenรญ rozsahu a viditelnost v uลพivatelskรฉm rozhranรญ sprรกvy MCP\n- Bezpeฤnรก vรฝchozรญ poloha pro provoznรญ nรกstroje\n\n
\nโš™๏ธ 22. โ€žPotล™ebuji provoznรญ kontroly bez nutnosti pล™esouvรกnรญโ€œ\n
\n\nTรฝmy potล™ebujรญ rychlรฉ zmฤ›ny v bฤ›hovรฉm prostล™edรญ bฤ›hem incidentลฏ nebo nรกkladovรฝch udรกlostรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Pล™epnฤ›te aktivaci komba pล™รญmo z ล™รญdicรญho panelu MCP\n- Pouลพรญvejte profily odolnosti z pล™eddefinovanรฝch balรญฤkลฏ zรกsad\n- Resetujte stav jistiฤe ze stejnรฉho ovlรกdacรญho panelu\n\n
\n๐Ÿ”„ 23. โ€žPotล™ebuji ลพivรฝ pล™ehled o ลพivotnรญm cyklu รบkolลฏ A2A a jejich zruลกenรญ.โ€œ\n
\n\nBez pล™ehledu o ลพivotnรญm cyklu je obtรญลพnรฉ tล™รญdit incidenty รบkolลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Vรฝpis/filtrovรกnรญ รบkolลฏ podle stรกtu/dovednosti s strรกnkovรกnรญm\n- Podrobnรฝ pล™ehled metadat รบloh, udรกlostรญ a artefaktลฏ\n- Koncovรฝ bod zruลกenรญ รบlohy a akce uลพivatelskรฉho rozhranรญ s potvrzenรญm\n\n
\n๐ŸŒŠ 24. โ€žPotล™ebuji metriky aktivnรญho streamu pro A2A zรกtฤ›ลพโ€œ\n
\n\nStreamovacรญ pracovnรญ postupy vyลพadujรญ provoznรญ pล™ehled o soubฤ›ลพnosti a ลพivรฝch pล™ipojenรญch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- ฤŒรญtaฤe aktivnรญch streamลฏ integrovanรฉ do stavu A2A\n- ฤŒasovรฉ razรญtko poslednรญho รบkolu a poฤty pro jednotlivรฉ stavy\n- Karty A2A dashboardu pro monitorovรกnรญ provozu v reรกlnรฉm ฤase\n\n
\n๐Ÿชช 25. โ€žPotล™ebuji standardnรญ vyhledรกvรกnรญ agentลฏ pro klientyโ€œ\n
\n\nExternรญ klienti a orchestratoล™i potล™ebujรญ pro onboarding strojovฤ› ฤitelnรก metadata.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazenรฉ v uลพivatelskรฉm rozhranรญ pro sprรกvu\n- API pro stav A2A zahrnuje metadata pro zjiลกลฅovรกnรญ pro automatizaci\n\n
\n๐Ÿงญ 26. โ€žPotล™ebuji v uลพivatelskรฉm rozhranรญ produktu zjistitelnost protokolu.โ€œ\n
\n\nPokud uลพivatelรฉ nemohou objevit protokolovรฉ povrchy, kvalita pล™ijetรญ a podpory klesรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Strรกnka Konsolidovanรฉ **koncovรฉ body** s kartami pro koncovรฉ body Proxy, MCP, A2A a API\n- Pล™epรญnรกnรญ stavu inline sluลพby (Online/Offline) pro MCP a A2A\n- Odkazy z pล™ehledu na vyhrazenรฉ karty pro sprรกvu\n\n
\n๐Ÿงช 27. โ€žPotล™ebuji komplexnรญ ovฤ›ล™enรญ protokolu se skuteฤnรฝmi klienty.โ€œ\n
\n\nSimulovanรฉ testy nestaฤรญ k ovฤ›ล™enรญ kompatibility protokolu pล™ed vydรกnรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sada E2E, kterรก spouลกtรญ aplikaci a pouลพรญvรก skuteฤnรฝ transport klienta MCP SDK.\n- Klientskรฉ testy A2A pro toky zjiลกลฅovรกnรญ, odesรญlรกnรญ, streamovรกnรญ, naฤรญtรกnรญ a zruลกenรญ\n- Kล™รญลพovรก kontrola tvrzenรญ oproti API pro audit MCP a รบkoly A2A\n\n
\n๐Ÿ“ก 28. โ€žPotล™ebuji jednotnou pozorovatelnost napล™รญฤ vลกemi rozhranรญmiโ€œ\n
\n\nRozdฤ›lenรญ pozorovatelnosti podle protokolu vytvรกล™รญ slepรก mรญsta a delลกรญ MTTR.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรฉ dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie poลพadavkลฏ napล™รญฤ vrstvami OpenAI, MCP a A2A\n- Provoznรญ API pro stav a automatizaci\n\n
\n๐Ÿ’ผ 29. โ€žPotล™ebuji jeden runtime pro proxy + nรกstroje + orchestraci agentลฏโ€œ\n
\n\nSpouลกtฤ›nรญ mnoha samostatnรฝch sluลพeb zvyลกuje provoznรญ nรกklady a poฤet poruch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Proxy, MCP server a A2A server kompatibilnรญ s OpenAI v jednom balรญฤku\n- Sdรญlenรฉ ovฤ›ล™ovรกnรญ, odolnost, รบloลพiลกtฤ› dat a pozorovatelnost\n- Konzistentnรญ model politik napล™รญฤ vลกemi interakฤnรญmi plochami\n\n
\n๐Ÿš€ 30. โ€žPotล™ebuji agentskรฉ pracovnรญ postupy bez slepenรญ kรณdu.โ€œ\n
\n\nTรฝmy ztrรกcejรญ rychlost pล™i spojovรกnรญ vรญce ad-hoc sluลพeb a skriptลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรก strategie koncovรฝch bodลฏ pro klienty a agenty\n- Vestavฤ›nรก uลพivatelskรก rozhranรญ pro sprรกvu protokolลฏ a cesty pro ovฤ›ล™ovรกnรญ kouล™e\n- Zรกklady pล™ipravenรฉ pro produkฤnรญ prostล™edรญ (zabezpeฤenรญ, protokolovรกnรญ, odolnost, zรกlohovรกnรญ)\n\n### Pล™รญklady hernรญch plรกnลฏ (integrovanรฉ pล™รญpady uลพitรญ)\n\n**Pล™รญruฤka A: Maximalizace placenรฉho pล™edplatnรฉho + levnรฉ zรกlohovรกnรญ**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Pล™รญruฤka B: Kรณdovacรญ stack s nulovรฝmi nรกklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Pล™รญruฤka C: Nonstop zรกloลพnรญ ล™etฤ›zec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Pล™รญruฤka D: Operace agentลฏ s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Zaฤnฤ›te zdarma โ€” Nulovรฉ nรกklady na konfiguraci\n\n> Nastavte si kรณdovรกnรญ s umฤ›lou inteligencรญ bฤ›hem nฤ›kolika minut za **0 $/mฤ›sรญc** . Propojte tyto bezplatnรฉ รบฤty a vyuลพijte vestavฤ›nou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelรฉ odemฤeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Pล™ipojenรญ **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€“ **neomezenฤ›** |\n| 2 | Pล™ipojenรญ k **iFlow** (Google OAuth) | kimi-k2-myลกlenรญ, qwen3-coder-plus, deepseek-r1... โ€” **neomezenฤ›** |\n| 3 | Pล™ipojenรญ **Qwen** (kรณd zaล™รญzenรญ) | qwen3-coder-plus, qwen3-coder-flash... โ€” **neomezenฤ›** |\n| 4 | Pล™ipojenรญ **rozhranรญ pล™รญkazovรฉho ล™รกdku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180 000 GBP/mฤ›sรญc zdarma** |\n| 5 | `/dashboard/combos` โ†’ ล ablona **Free Stack (0 $)** | Automatickรฉ zaล™azenรญ vลกech bezplatnรฝch poskytovatelลฏ do routingu |\n\n**V libovolnรฉm IDE/CLI naveฤte:** `http://localhost:20128/v1` ยท Klรญฤ API: `any-string` ยท Hotovo.\n\n> **Volitelnรฉ doplลˆkovรฉ krytรญ (takรฉ zdarma):** Groq API klรญฤ (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelลฏ), Cerebras (1 milion tok/den).\n\n## โšก Rychlรฝ start\n\n### 1) Nainstalujte a spusลฅte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uลพivatelรฉ pnpm:** Po instalaci spusลฅte `pnpm approve-builds -g` , abyste povolili nativnรญ skripty pro sestavenรญ vyลพadovanรฉ programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard se otevรญrรก na `http://localhost:20128` a zรกkladnรญ URL API je `http://localhost:20128/v1` .\n\n| Pล™รญkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuลกtฤ›nรญ serveru ( `PORT=20128` , API a dashboard na stejnรฉm portu) |\n| `omniroute --port 3000` | Nastavte kanonickรฝ/API port na 3000 |\n| `omniroute --mcp` | Spuลกtฤ›nรญ MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevรญrat prohlรญลพeฤ automaticky |\n| `omniroute --help` | Zobrazit nรกpovฤ›du |\n\nVolitelnรฝ reลพim s rozdฤ›lenรฝm portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Pล™ipojte poskytovatele a vytvoล™te si klรญฤ API\n\n1. Otevล™ete Dashboard โ†’ `Providers` a pล™ipojte alespoลˆ jednoho poskytovatele (klรญฤ OAuth nebo API).\n2. Otevล™ete Dashboard โ†’ `Endpoints` a vytvoล™te API klรญฤ.\n3. (Volitelnรฉ) Otevล™ete Dashboard โ†’ `Combos` a nastavte zรกloลพnรญ ล™etฤ›zec.\n\n### 3) Nasmฤ›rujte svลฏj kรณdovacรญ nรกstroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilnรญmi s OpenAI.\n\n### 4) Povolenรญ a ovฤ›ล™enรญ protokolลฏ (v2.0)\n\n**MCP (pro operace ล™รญzenรฉ nรกstroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak pล™ipojte svรฉho MCP klienta pล™es `stdio` a otestujte nรกstroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovnรญ postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ovฤ›ล™te vลกe od zaฤรกtku do konce (doporuฤeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ovฤ›ล™uje skuteฤnรฉ toky klientลฏ MCP a A2A v porovnรกnรญ se spuลกtฤ›nou aplikacรญ.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute je k dispozici jako veล™ejnรฝ obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlรฝ bฤ›h:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostล™edรญ:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Pouลพรญvรกnรญ Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | ล tรญtek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovฤ›jลกรญ stabilnรญ verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuรกlnรญ verze |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktopovรก aplikace โ€“ offline a vลพdy zapnutรก\n\n> ๐Ÿ†• **NOVINKA!** OmniRoute je nynรญ k dispozici jako **nativnรญ desktopovรก aplikace** pro Windows, macOS a Linux.\n\nSpusลฅte OmniRoute jako samostatnou desktopovou aplikaci โ€“ pro lokรกlnรญ modely nenรญ potล™eba ลพรกdnรฝ terminรกl, prohlรญลพeฤ ani internet. Aplikace zaloลพenรก na platformฤ› Electron obsahuje:\n\n- ๐Ÿ–ฅ๏ธ **Nativnรญ okno** โ€” Vyhrazenรฉ okno aplikace s integracรญ do systรฉmovรฉ liลกty\n- ๐Ÿ”„ **Automatickรฉ spuลกtฤ›nรญ** โ€” Spuลกtฤ›nรญ OmniRoute po pล™ihlรกลกenรญ do systรฉmu\n- ๐Ÿ”” **Nativnรญ oznรกmenรญ** โ€“ Zรญskejte upozornฤ›nรญ na vyฤerpรกnรญ kvรณty nebo problรฉmy s poskytovateli\n- โšก **Instalace jednรญm kliknutรญm** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline reลพim** โ€” Funguje plnฤ› offline s pล™iloลพenรฝm serverem\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systรฉmovรฝ zรกsobnรญk\n\nPo minimalizaci se OmniRoute nachรกzรญ v systรฉmovรฉ liลกtฤ› a nabรญzรญ rychlรฉ akce:\n\n- Otevล™รญt ล™รญdicรญ panel\n- Zmฤ›nit port serveru\n- Ukonฤit aplikaci\n\n๐Ÿ“– รšplnรก dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pล™ehled cen\n\n| รšroveลˆ | Poskytovatel | Nรกklady | Obnovenรญ kvรณty | Nejlepลกรญ pro |\n| --------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **๐Ÿ’ณ Pล˜EDPLATNร‰** | Claude Code (profesionรกl) | 20 dolarลฏ mฤ›sรญฤnฤ› | 5 hodin + tรฝdnฤ› | Jiลพ pล™ihlรกลกen/a k odbฤ›ru |\n| Kodex (Plus/Pro) | 20โ€“200 USD/mฤ›sรญc | 5 hodin + tรฝdnฤ› | Uลพivatelรฉ OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisรญc mฤ›sรญฤnฤ› + 1 tisรญc dennฤ› | Kaลพdรฝ! |\n| GitHub Copilot | 10โ€“19 USD/mฤ›sรญc | Mฤ›sรญฤnรญ | Uลพivatelรฉ GitHubu |\n| **๐Ÿ”‘ KLรฤŒ API** | NVIDIA NIM | **ZDARMA** (vรฝvoj navลพdy) | ~40 ot./min | 70+ otevล™enรฝch modelลฏ |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ na svฤ›tฤ› |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisรญc otรกฤek za minutu | Ultrarychlรก lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | ลฝรกdnรฝ | Nejlepลกรญ zdลฏvodnฤ›nรญ ceny a kvality |\n| xAI Grok-4 Rychlรฝ | **0,20/0,50 USD za 1 milion** ๐Ÿ†• | ลฝรกdnรฝ | Nejrychlejลกรญ + volรกnรญ nรกstroje, ultranรญzkรฉ |\n| xAI Grok-4 (standardnรญ) | 0,20/1,50 USD za 1 milion ๐Ÿ†• | ลฝรกdnรฝ | Vlajkovรก loฤ Reasoning od xAI |\n| Mistral | Zkuลกebnรญ verze zdarma + placenรฉ | Omezenรก sazba | Evropskรก umฤ›lรก inteligence |\n| OpenRouter | Platba za pouลพitรญ | ลฝรกdnรฝ | Vรญce neลพ 100 modelลฏ agregovรกno. |\n| **๐Ÿ’ฐ LEVNร‰** | GLM-5 (pล™es Z.AI) ๐Ÿ†• | 0,5 USD/1 milion | Dennฤ› v 10:00 | Vรฝstup 128 tisรญc obrazovรฝch bodลฏ, nejnovฤ›jลกรญ vlajkovรก loฤ |\n| GLM-4.7 | 0,6 USD/1 milion | Dennฤ› v 10:00 | Zรกloha rozpoฤtu |\n| MiniMax M2.5 ๐Ÿ†• | Vstup 0,3 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | รšvaha + agentnรญ รบkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | Nejlevnฤ›jลกรญ varianta |\n| Kimi K2.5 (Moonshot API) ๐Ÿ†• | Platba za pouลพitรญ | ลฝรกdnรฝ | Pล™รญmรฝ pล™รญstup k Moonshot API |\n| Kimi K2 | 9 dolarลฏ mฤ›sรญฤnฤ› bez zรกvazkลฏ | 10 milionลฏ tokenลฏ/mฤ›sรญc | Pล™edvรญdatelnรฉ nรกklady |\n| **๐Ÿ†“ ZDARMA** | iFlow | **0 dolarลฏ** | Neomezenรฝ | 5 modelลฏ neomezenฤ› |\n| Qwen | **0 dolarลฏ** | Neomezenรฝ | 4 modely neomezenฤ› |\n| Kiro | **0 dolarลฏ** | Neomezenรฝ | Claude Sonnet/Haiku (tvorce AWS) |\n\n> ๐Ÿ†• **Pล™idรกny novรฉ modely (bล™ezen 2026):** ล™ada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkovรกno na 1143 ms โ€“ o 30 % rychlejลกรญ neลพ Gemini 2.5 Flash), GLM-5 pล™es Z.AI s vรฝstupem 128K, uvaลพovรกnรญ MiniMax M2.5, aktualizovanรฉ ceny DeepSeek V3.2, Kimi K2.5 pล™es Moonshot Direct API.\n\n**๐Ÿ’ก Kombinovanรฝ balรญk za 0 $ โ€” Kompletnรญ bezplatnรก instalace:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\niFlow (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Nulovรฉ nรกklady. Nikdy nepล™estรกvejte s kรณdovรกnรญm.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a vลกechny zรกloลพnรญ reลพimy se provede automaticky โ€“ ลพรกdnรฉ ruฤnรญ pล™epรญnรกnรญ.\n\n---\n\n---\n\n## ๐Ÿ†“ Bezplatnรฉ modely โ€“ Co skuteฤnฤ› zรญskรกte\n\n> Vลกechny nรญลพe uvedenรฉ modely jsou **100% zdarma a nevyลพadujรญ ลพรกdnou kreditnรญ kartu** . OmniRoute mezi nimi automaticky propojรญ trasy, kdyลพ dojde jedna kvรณta โ€“ zkombinujte je vลกechny a zรญskejte tak nerozluฤnou kombinaci za 0 dolarลฏ.\n\n### ๐Ÿ”ต CLAUDE MODELS (pล™es Kiro โ€” AWS Builder ID)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-opus-4.6` | `kr/` | **Neomezenรฝ** | Nejnovฤ›jลกรญ opus od Kira |\n\n### ๐ŸŸข MODELY IFLOW (Bezplatnรฉ OAuth โ€” bez nutnosti platit kreditnรญ kartou)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-plus` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `deepseek-r1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `minimax-m2.1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `kimi-k2` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n\n### ๐ŸŸก MODELY QWEN (Ovฤ›ล™enรญ kรณdu zaล™รญzenรญ)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-next` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `vision-model` | `qw/` | **Neomezenรฝ** | Multimodรกlnรญ (obrรกzky) |\n\n### ๐ŸŸฃ Rozhranรญ GEMINI CLI (Google OAuth)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisรญc tok/mฤ›sรญc** + 1 tisรญc/den | Mฤ›sรญฤnรญ reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisรญc mฤ›sรญฤnฤ› (sdรญlenรฝ bazรฉn) | Vysokรก kvalita |\n\n### โšซ NVIDIA NIM (Bezplatnรฝ klรญฤ API โ€” build.nvidia.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vรฝvojรกล™) | ลฝรกdnรฝ limit tokenลฏ | **~40 ot./min** | Vรญce neลพ 70 modelลฏ; pล™echod na ฤistรฉ limity sazeb v polovinฤ› roku 2025 |\n\nOblรญbenรฉ bezplatnรฉ modely: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct` , `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Bezplatnรฝ klรญฤ API โ€” inference.cerebras.ai)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenลฏ/den** | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ inference LLM na svฤ›tฤ›; dennฤ› se resetuje |\n\nDostupnรฉ zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Bezplatnรฝ API klรญฤ โ€” console.groq.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisรญc otรกฤek za minutu** | 30 ot./min na model | ลฝรกdnรก kreditnรญ karta; limit 429, neรบฤtovรกno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **๐Ÿ’ก Ultimรกtnรญ bezplatnรฝ zรกsobnรญk:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> โ†’ iFlow (5 models, unlimited)\n> โ†’ Qwen (4 models, unlimited)\n> โ†’ Gemini CLI (180K/mo)\n> โ†’ Cerebras (1M tok/day)\n> โ†’ Groq (14.4K req/day)\n> โ†’ NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a uลพ nikdy nebudete platit za umฤ›lou inteligenci.\n\n## ๐ŸŽ™๏ธ Kombinovanรก transkripce zdarma\n\n> Pล™episujte libovolnรฉ audio/video za **0 $** โ€“ Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako zรกloลพnรญ nรกstroj, Groq Whisper jako neomezenรก nouzovรก zรกloha.\n\n| Poskytovatel | Bezplatnรฉ kredity | Nejlepลกรญ model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| ๐ŸŸข **Deepgram** | **200 dolarลฏ zdarma** (registrace) | `nova-3` โ€” nejvyลกลกรญ pล™esnost, vรญce neลพ 30 jazykลฏ | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ต **AssemblyAI** | **50 dolarลฏ zdarma** (registrace) | `universal-3-pro` โ€” kapitoly, sentiment, osobnรญ รบdaje | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ด **Groq** | **Navลพdy zdarma** | `whisper-large-v3` โ€” OpenAI ล epot | 30 ot./min (omezenรก rychlost) |\n\n**Navrhovanรก kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nPak v `/dashboard/media` โ†’ zรกloลพka **Pล™epis** : nahrajte libovolnรฝ zvukovรฝ nebo video soubor โ†’ vyberte kombinovanรฝ koncovรฝ bod โ†’ zรญskejte pล™epis v podporovanรฝch formรกtech.\n\n## ๐Ÿ’ก Klรญฤovรฉ vlastnosti\n\nOmniRoute v2.0 je navrลพen jako operaฤnรญ platforma, nikoli pouze jako proxy pro relรฉ.\n\n### ๐Ÿค– Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dฤ›lรก |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (16 nรกstrojลฏ)** | Nรกstroje IDE/agent prostล™ednictvรญm 3 transportลฏ: stdio, SSE ( `/api/mcp/sse` ), Streamovatelnรฝ HTTP ( `/api/mcp/stream` ) |\n| ๐Ÿค **A2A server (JSON-RPC + SSE)** | Spouลกtฤ›nรญ รบloh mezi agenty se synchronizacรญ a streamovรกnรญm |\n| ๐Ÿงญ **Konsolidovanรก strรกnka koncovรฝch bodลฏ** | Strรกnka pro sprรกvu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| ๐ŸŽš๏ธ **Pล™epรญnaฤe pro povolenรญ/zakรกzรกnรญ sluลพby** | Pล™epรญnaฤe ZAP/VYP pro MCP a A2A s trvalรฝm nastavenรญm (vรฝchozรญ: VYP) |\n| ๐Ÿ›ฐ๏ธ **Srdeฤnรญ tep za bฤ›hu MCP** | Skuteฤnรฝ stav procesu (pid, doba provozuschopnosti, stรกล™รญ heartbeatu, transport, reลพim rozsahu) |\n| ๐Ÿ“‹ **Auditnรญ zรกznam MCP** | Filtrovatelnรฉ protokoly auditu s hodnocenรญm รบspฤ›chu/neรบspฤ›chu a klรญฤovรฝm pล™iล™azenรญm |\n| ๐Ÿ” **Vynucovรกnรญ rozsahu MCP** | 9 podrobnรฝch oprรกvnฤ›nรญ pro ล™รญzenรฝ pล™รญstup k nรกstrojลฏm |\n| ๐Ÿ“ก **Sprรกva ลพivotnรญho cyklu รบkolลฏ A2A** | Seznam/filtrovรกnรญ รบloh, kontrola udรกlostรญ/artefaktลฏ, zruลกenรญ spuลกtฤ›nรฝch รบloh |\n| ๐Ÿ“‹ **Objevenรญ karty agenta** | `/.well-known/agent.json` pro automatickรฉ vyhledรกvรกnรญ klientลฏ |\n| ๐Ÿงช **Testovacรญ postroj Protocol E2E** | Skuteฤnรฉ MCP SDK + toky klientลฏ A2A v `test:protocols:e2e` |\n| โš™๏ธ **Provoznรญ kontroly** | Kombinace pล™epรญnaฤลฏ, pouลพitรญ profilลฏ odolnosti, resetovรกnรญ jistiฤลฏ z jednoho ovlรกdacรญho panelu |\n\n### ๐Ÿง  Smฤ›rovรกnรญ a inteligence\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| ๐ŸŽฏ **Inteligentnรญ ฤtyล™รบrovลˆovรฝ zรกloลพnรญ systรฉm** | Automatickรก trasa: Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma |\n| ๐Ÿ“Š **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** | Poฤet tokenลฏ v reรกlnรฉm ฤase + odpoฤet resetovรกnรญ pro kaลพdรฉho poskytovatele |\n| ๐Ÿ”„ **Pล™eklad formรกtu** | OpenAI โ†” Claude โ†” Gemini โ†” Odpovฤ›di s konverzemi bezpeฤnรฝmi pro schรฉma |\n| ๐Ÿ‘ฅ **Podpora vรญce รบฤtลฏ** | Vรญce รบฤtลฏ na poskytovatele s inteligentnรญm vรฝbฤ›rem |\n| ๐Ÿ”„ **Automatickรก aktualizace tokenลฏ** | Tokeny OAuth se automaticky obnovujรญ pล™i opakovanรฉm pokusu. |\n| ๐ŸŽจ **Vlastnรญ kombinace** | 6 vyvaลพovacรญch strategiรญ + ล™รญzenรญ zรกloลพnรญho ล™etฤ›zce |\n| ๐ŸŒ **Smฤ›rovaฤ se zรกstupnรฝmi znaky** | dynamickรฉ smฤ›rovรกnรญ `provider/*` |\n| ๐Ÿง  **Pล™emรฝลกlenรญ o rozpoฤtovรฝch kontrolรกch** | Limity pro prลฏchozรญ, automatickรฉ, vlastnรญ a adaptivnรญ uvaลพovรกnรญ |\n| ๐Ÿ”€ **Aliasy modelลฏ** | Vestavฤ›nรฉ + vlastnรญ aliasovรกnรญ modelลฏ a bezpeฤnost migrace |\n| โšก **Degradace pozadรญ** | Smฤ›rujte รบlohy na pozadรญ s nรญzkou prioritou na levnฤ›jลกรญ modely |\n| ๐Ÿงช **Chytrรฉ smฤ›rovรกnรญ s ohledem na รบkoly** | Automatickรฝ vรฝbฤ›r modelu podle typu obsahu (kรณdovรกnรญ/vize/analรฝza/sumarizace) |\n| ๐Ÿ’ฌ **Vstล™ikovรกnรญ do systรฉmu** | Globรกlnรญ kontroly chovรกnรญ uplatลˆovanรฉ konzistentnฤ› |\n| ๐Ÿ“„ **Kompatibilita API pro odpovฤ›di** | Plnรก podpora `/v1/responses` pro Codex a pokroฤilรฉ agentickรฉ pracovnรญ postupy |\n\n### ๐ŸŽต Multimodรกlnรญ API\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Generovรกnรญ obrรกzkลฏ** | `/v1/images/generations` s cloudovรฝm a lokรกlnรญm backendem |\n| ๐Ÿ“ **Vloลพenรญ** | `/v1/embeddings` pro vyhledรกvรกnรญ a RAG pipelines |\n| ๐ŸŽค **Pล™epis zvuku** | `/v1/audio/transcriptions` (Whisper a dalลกรญ poskytovatelรฉ) |\n| ๐Ÿ”Š **Pล™evod textu na ล™eฤ** | `/v1/audio/speech` (vรญce enginลฏ/poskytovatelลฏ) |\n| ๐ŸŽฌ **Generovรกnรญ videa** | `/v1/videos/generations` (pracovnรญ postupy ComfyUI + SD WebUI) |\n| ๐ŸŽต **Hudebnรญ generace** | `/v1/music/generations` (pracovnรญ postupy ComfyUI) |\n| ๐Ÿ›ก๏ธ **Moderovรกnรญ** | Bezpeฤnostnรญ kontroly `/v1/moderations` |\n| ๐Ÿ”€ **Zmฤ›na poล™adรญ** | `/v1/rerank` pro hodnocenรญ relevance |\n| ๐Ÿ” **Vyhledรกvรกnรญ na webu** ๐Ÿ†• | `/v1/search` โ€” 5 poskytovatelลฏ (Serper, Brave, Perplexity, Exa, Tavily), vรญce neลพ 6 500 zdarma/mฤ›sรญc, automatickรฉ pล™epnutรญ na zรกloลพnรญ systรฉm, mezipamฤ›ลฅ |\n\n### ๐Ÿ›ก๏ธ Odolnost, bezpeฤnost a sprรกva vฤ›cรญ veล™ejnรฝch\n\n| Funkce | Co to dฤ›lรก |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Jistiฤe** | Vypnutรญ/obnovenรญ pro kaลพdรฝ model s ovlรกdรกnรญm prahovรฝch hodnot |\n| ๐ŸŽฏ **Modely s ohledem na koncovรฉ body** | Vlastnรญ modely deklarujรญ podporovanรฉ koncovรฉ body + formรกt API |\n| ๐Ÿ›ก๏ธ **Stรกdo proti hromลฏm** | Ochrana mutexu a semaforu pล™i udรกlostech opakovรกnรญ/rychlosti |\n| ๐Ÿง  **Sรฉmantickรก + podpisovรก mezipamฤ›ลฅ** | Snรญลพenรญ nรกkladลฏ/latence dรญky dvฤ›ma vrstvรกm mezipamฤ›ti |\n| โšก **ลฝรกdost o idempotenci** | Okno ochrany proti duplikacรญm |\n| ๐Ÿ”’ **Falลกovรกnรญ otiskลฏ prstลฏ pomocรญ TLS** | Otisk TLS podobnรฝ prohlรญลพeฤi โ€“ **sniลพuje detekci botลฏ a nahlaลกovรกnรญ รบฤtลฏ** |\n| ๐Ÿ” **Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** | Shoduje se s nativnรญmi podpisy poลพadavkลฏ CLI โ€“ **sniลพuje riziko zablokovรกnรญ a zรกroveลˆ zachovรกvรก IP adresu proxy** |\n| ๐ŸŒ **Filtrovรกnรญ IP adres** | Ovlรกdรกnรญ seznamu povolenรฝch/blokovanรฝch poloลพek pro odhalenรก nasazenรญ |\n| ๐Ÿ“Š **Upravitelnรฉ limity rychlosti** | Konfigurovatelnรฉ globรกlnรญ/na รบrovni poskytovatele limity s perzistencรญ |\n| ๐Ÿ”‘ **Sprรกva klรญฤลฏ API a stanovenรญ rozsahu** | Bezpeฤnรฉ vydรกvรกnรญ/rotace klรญฤลฏ a kontroly modelu/poskytovatele |\n| ๐Ÿ›ก๏ธ **Chrรกnฤ›nรฉ `/models`** | Volitelnรฉ ovฤ›ล™ovรกnรญ a skrytรญ poskytovatele pro katalog modelลฏ |\n\n### ๐Ÿ“Š Pozorovatelnost a analytika\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| ๐Ÿ“ **ลฝรกdost + protokolovรกnรญ proxy** | รšplnรฉ protokolovรกnรญ poลพadavkลฏ/odpovฤ›dรญ a proxy |\n| ๐Ÿ“‹ **Sjednocenรฝ panel protokolลฏ** | Zobrazenรญ poลพadavkลฏ, proxy, auditu a konzole na jednรฉ strรกnce |\n| ๐Ÿ” **Vyลพรกdat si telemetrii** | Latence p50/p95/p99 a trasovรกnรญ poลพadavkลฏ |\n| ๐Ÿฅ **Panel zdravรญ** | Doba provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti |\n| ๐Ÿ’ฐ **Sledovรกnรญ nรกkladลฏ** | Kontrola rozpoฤtu a pล™ehled o cenรกch pro jednotlivรฉ modely |\n| ๐Ÿ“ˆ **Analytickรฉ vizualizace** | Pล™ehledy vyuลพitรญ modelลฏ/poskytovatelลฏ a zobrazenรญ trendลฏ |\n| ๐Ÿงช **Rรกmec hodnocenรญ** | Testovรกnรญ zlatรฉ sady s konfigurovatelnรฝmi strategiemi shody |\n\n### โ˜๏ธ Nasazenรญ a platforma\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| ๐ŸŒ **Nasazenรญ kdekoli** | Localhost, VPS, Docker, cloudovรก prostล™edรญ |\n| ๐Ÿ’พ **Synchronizace s cloudem** | Synchronizace konfigurace pล™es cloud worker |\n| ๐Ÿ”„ **Zรกlohovรกnรญ/Obnovenรญ** | Toky exportu/importu a obnovy po havรกrii |\n| ๐Ÿง™ **Prลฏvodce nรกstupem** | Prลฏvodce prvnรญm spuลกtฤ›nรญm |\n| ๐Ÿ”ง **Panel nรกstrojลฏ CLI** | Nastavenรญ oblรญbenรฝch kรณdovacรญch nรกstrojลฏ jednรญm kliknutรญm |\n| ๐ŸŽฎ **Modelovรฉ hล™iลกtฤ›** | Otestujte libovolnรฉho poskytovatele/model/koncovรฝ bod z ล™รญdicรญho panelu |\n| ๐Ÿ” **Pล™epรญnaฤ otiskลฏ prstลฏ v pล™รญkazovรฉm ล™รกdku** | Porovnรกvรกnรญ otiskลฏ prstลฏ podle poskytovatele v Nastavenรญ > Zabezpeฤenรญ |\n| ๐ŸŒ **i18n (30 jazykลฏ)** | Plnรก jazykovรก podpora dashboardu a dokumentace s psanรญm zprava doleva |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Adresรกล™ vlastnรญch dat** | Pล™epsรกnรญ `DATA_DIR` pro umรญstฤ›nรญ รบloลพiลกtฤ› |\n\n### Hlubokรฝ pohled na funkce\n\n#### Chytrรก zรกloลพnรญ funkce s praktickou kontrolou nรกkladลฏ\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyลพ selลพe kvรณta, rychlost nebo stav, OmniRoute automaticky pล™ejde k dalลกรญmu kandidรกtovi bez nutnosti ruฤnรญho pล™epรญnรกnรญ.\n\n#### Sprรกva protokolลฏ, kterรก je viditelnรก a ovladatelnรก\n\n- MCP + A2A jsou viditelnรฉ v uลพivatelskรฉm rozhranรญ a dokumentaci (nejsou skrytรฉ)\n- API pro stav protokolu zpล™รญstupลˆujรญ ลพivรก provoznรญ data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnujรญ akce pro operace 2. dne (pล™epรญnรกnรญ kombinacรญ, resetovรกnรญ jistiฤลฏ, zruลกenรญ รบkolลฏ)\n\n#### Pracovnรญ postup pล™ekladatele + validace\n\nOblast pล™ekladatele zahrnuje:\n\n- **Hล™iลกtฤ›** : kontroly transformace poลพadavkลฏ\n- **Tester chatu** : kompletnรญ okruลพnรญ cesta poลพadavku/odpovฤ›di\n- **Testovacรญ stolice** : vรญce pล™รญpadลฏ v jednom bฤ›hu\n- **ลฝivรฝ monitor** : zobrazenรญ provozu v reรกlnรฉm ฤase\n\nPlus validace protokolu se skuteฤnรฝmi klienty pomocรญ `npm run test:protocols:e2e` .\n\n> ๐Ÿ“– **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** โ€” Referenฤnรญ informace o nรกstrojรญch, konfigurace IDE a pล™รญklady klientลฏ\n>\n> ๐Ÿ“– **[Soubor README pro A2A Server](src/lib/a2a/README.md)** โ€” Dovednosti, metody JSON-RPC, streamovรกnรญ a ลพivotnรญ cyklus รบloh\n\n## ๐Ÿงช Hodnocenรญ (Evals)\n\nOmniRoute obsahuje vestavฤ›nรฝ hodnotรญcรญ rรกmec pro testovรกnรญ kvality odpovฤ›dรญ LLM v porovnรกnรญ se zlatou sadou. Pล™รญstup k nฤ›mu je moลพnรฝ pล™es **Analรฝzy โ†’ Hodnocenรญ** v dashboardu.\n\n### Vestavฤ›nรก zlatรก sada\n\nPล™edinstalovanรก sada โ€žOmniRoute Golden Setโ€œ obsahuje testovacรญ pล™รญpady pro:\n\n- Zdravรญm, matematika, zemฤ›pis, generovรกnรญ kรณdu\n- Shoda s formรกtem JSON, pล™eklad, generovรกnรญ markdownลฏ\n- Bezpeฤnostnรญ odmรญtnutรญ (ลกkodlivรฝ obsah), poฤรญtรกnรญ, booleovskรก logika\n\n### Strategie hodnocenรญ\n\n| Strategie | Popis | Pล™รญklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Vรฝstup se musรญ pล™esnฤ› shodovat | `\"4\"` |\n| `contains` | Vรฝstup musรญ obsahovat podล™etฤ›zec (bez rozliลกenรญ velkรฝch a malรฝch pรญsmen) | `\"Paris\"` |\n| `regex` | Vรฝstup musรญ odpovรญdat vzoru regulรกrnรญch vรฝrazลฏ | `\"1.*2.*3\"` |\n| `custom` | Vlastnรญ JS funkce vracรญ true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Prลฏvodce nastavenรญm\n\n### Nastavenรญ protokolu (MCP + A2A)\n\n
\n๐Ÿงฉ Nastavenรญ MCP (Model Context Protocol)\n
\n\nSpuลกtฤ›nรญ MCP transportu v reลพimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporuฤenรฝ postup ovฤ›ล™enรญ:\n\n1. Pล™ipojte svรฉho MCP klienta pล™es stdio.\n2. Spusลฅte `omniroute_get_health` .\n3. Spusลฅte `omniroute_list_combos` .\n4. Otevล™ete `/dashboard/mcp` pro ovฤ›ล™enรญ prezenฤnรญho signรกlu, aktivity a auditu.\n\nUลพiteฤnรก API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n๐Ÿค Nastavenรญ A2A (Agent2Agent)\n
\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat รบkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSprรกva ลพivotnรญho cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvoznรญ uลพivatelskรฉ rozhranรญ:\n\n- `/dashboard/a2a` pro pozorovatelnost รบloh/stavลฏ/streamลฏ a akce kouล™enรญ\n\n
\n๐Ÿงช Komplexnรญ validace protokolu\n
\n\nOvฤ›ล™te oba protokoly se skuteฤnรฝmi klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTรญm se ovฤ›ล™uje:\n\n- Pล™ipojenรญ/seznam/volรกnรญ klienta MCP SDK\n- A2A objevovรกnรญ/odesรญlรกnรญ/streamovรกnรญ/zรญskรกvรกnรญ/zruลกenรญ\n- Kล™รญลพovรก kontrola dat v auditu MCP a API pro sprรกvu รบloh A2A\n\n
\n๐Ÿ’ณ Poskytovatelรฉ pล™edplatnรฉho\n
\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionรกly:** Pro sloลพitรฉ รบkoly pouลพรญvejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvรณtu pro kaลพdรฝ model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Sprรกva limitลฏ รบฤtu Codex (5h + tรฝdnฤ›)\n\nKaลพdรฝ รบฤet Codex mรก nynรญ pล™epรญnaฤe zรกsad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinovรฉho prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zรกsadu tรฝdennรญho prahu okna.\n- Prahovรฉ chovรกnรญ: kdyลพ povolenรฉ okno dosรกhne vyuลพitรญ >=90 %, je danรฝ รบฤet pล™eskoฤen.\n- Chovรกnรญ rotace: OmniRoute automaticky pล™esmฤ›ruje na dalลกรญ zpลฏsobilรฝ รบฤet Codex.\n- Chovรกnรญ pล™i resetovรกnรญ: Po `resetAt` urฤitรฉ doby se รบฤet automaticky opฤ›t stane zpลฏsobilรฝm.\n\nScรฉnรกล™e:\n\n- `5h ON` + `Weekly ON` : รบฤet je pล™eskoฤen, kdyลพ kterรฉkoli z oken dosรกhne prahovรฉ hodnoty.\n- `5h OFF` + `Weekly ON` : รบฤet mลฏลพe bรฝt zablokovรกn pouze tรฝdennรญm pouลพรญvรกnรญm.\n- `5h ON` + `Weekly OFF` : รบฤet mลฏลพe bรฝt zablokovรกn pouze pล™i 5hodinovรฉm pouลพรญvรกnรญ.\n- `resetAt` passed: รบฤet se automaticky znovu zapne (bez ruฤnรญho opฤ›tovnรฉho povolenรญ).\n\n### Gemini CLI (ZDARMA 180 000/mฤ›sรญc!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepลกรญ hodnota:** Obrovskรก bezplatnรก รบroveลˆ! Pouลพijte ji pล™ed placenรฝmi รบrovnฤ›mi.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n
\n๐Ÿ”‘ Poskytovatelรฉ klรญฤลฏ API\n
\n\n### NVIDIA NIM (BEZPLATNร pล™รญstup pro vรฝvojรกล™e โ€” vรญce neลพ 70 modelลฏ)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Zรญskejte zdarma klรญฤ API (vฤetnฤ› 1000 inferenฤnรญch kreditลฏ)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ NVIDIA NIM:\n - Klรญฤ API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a vรญce neลพ 50 dalลกรญch\n\n**Tip pro profesionรกly:** API kompatibilnรญ s OpenAI โ€“ funguje bez problรฉmลฏ s pล™ekladem formรกtลฏ OmniRoute!\n\n### Hlubokรฉ vyhledรกvรกnรญ\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatnรก รบroveลˆ!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Zรญskejte klรญฤ API (vฤetnฤ› bezplatnรฉ รบrovnฤ›)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionรกly:** Ultrarychlรก inference โ€“ nejlepลกรญ pro kรณdovรกnรญ v reรกlnรฉm ฤase!\n\n### OpenRouter (100+ modelลฏ)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ OpenRouter\n\n**Modely:** Zรญskejte pล™รญstup k vรญce neลพ 100 modelลฏm od vลกech hlavnรญch poskytovatelลฏ prostล™ednictvรญm jedinรฉho klรญฤe API.\n\n
\n๐Ÿ’ฐ Levnรญ poskytovatelรฉ (zรกloลพnรญ)\n
\n\n### GLM-4.7 (Dennรญ reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Zรญskejte klรญฤ API z kรณdovacรญho plรกnu\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API:\n - Poskytovatel: `glm`\n - Klรญฤ API: `your-key`\n\n**Pouลพitรญ:** `glm/glm-4.7`\n\n**Tip pro profesionรกly:** Programovacรญ plรกn nabรญzรญ 3ร— kvรณtu za cenu 1/7! Obnovuje se dennฤ› v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionรกly:** Nejlevnฤ›jลกรญ varianta pro dlouhรฝ kontext (1 milion tokenลฏ)!\n\n### Kimi K2 (pauลกรกlnรญ poplatek 9 dolarลฏ mฤ›sรญฤnฤ›)\n\n1. Odebรญrat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `kimi/kimi-latest`\n\n**Tip pro profesionรกly:** Fixnรญch 9 $/mฤ›sรญc za 10 milionลฏ tokenลฏ = efektivnรญ nรกklady 0,90 $/1 milion!\n\n
\n๐Ÿ†“ BEZPLATNร poskytovatelรฉ (nouzovรฉ zรกlohovรกnรญ)\n
\n\n### iFlow (5 BEZPLATNรCH modelลฏ pล™es OAuth)\n\n```bash\nDashboard โ†’ Connect iFlow\nโ†’ iFlow OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kรณdem zaล™รญzenรญ)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n๐ŸŽจ Vytvoล™te kombinace\n
\n\n### Pล™รญklad 1: Maximalizace pล™edplatnรฉho โ†’ Levnรฉ zรกlohovรกnรญ\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Pล™รญklad 2: Pouze zdarma (nulovรฉ nรกklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n๐Ÿ”ง Integrace s rozhranรญm pล™รญkazovรฉho ล™รกdku\n
\n\n### IDE kurzoru\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jednรญm kliknutรญm pouลพijte strรกnku **Nรกstroje CLI** na ล™รญdicรญm panelu nebo ruฤnฤ› upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Moลพnost 1 โ€“ Dashboard (doporuฤeno):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Moลพnost 2 โ€“ Manuรกlnรญ รบprava:** รšprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznรกmka:** OpenClaw funguje pouze s lokรกlnรญm OmniRoute. Mรญsto `localhost` pouลพijte `127.0.0.1` , abyste se vyhnuli problรฉmลฏm s rozliลกenรญm IPv6.\n\n### Cline / Pokraฤovat / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Pล™idรกnรญ OmniRoute jako vlastnรญho poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvoล™te/upravte `opencode.json` v koล™enovรฉm adresรกล™i projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` pล™idejte jakรฝkoli model dostupnรฝ ve vaลกem koncovรฉm bodu OmniRoute `/v1/models` . Pouลพijte formรกt `provider/model-id` z vaลกeho dashboardu OmniRoute.\n\n---\n\n## ๐Ÿ› ล˜eลกenรญ problรฉmลฏ\n\n
\nKliknutรญm rozbalรญte prลฏvodce ล™eลกenรญm problรฉmลฏ\n
\n\n**\"Jazykovรฝ model neposkytoval zprรกvy\"**\n\n- Kvรณta poskytovatele vyฤerpรกna โ†’ Zkontrolujte sledovรกnรญ kvรณt na ล™รญdicรญm panelu\n- ล˜eลกenรญ: Pouลพijte zรกloลพnรญ kombinovanou variantu nebo pล™ejdฤ›te na levnฤ›jลกรญ รบroveลˆ\n\n**Omezenรญ rychlosti**\n\n- Kvรณta pล™edplatnรฉho vyฤerpรกna โ†’ Pล™echod na GLM/MiniMax\n- Pล™idat kombo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vyprลกela**\n\n- Automaticky aktualizovรกno sluลพbou OmniRoute\n- Pokud problรฉmy pล™etrvรกvajรญ: Ovlรกdacรญ panel โ†’ Poskytovatel โ†’ Znovu pล™ipojit\n\n**Vysokรฉ nรกklady**\n\n- Zkontrolujte statistiky vyuลพitรญ v sekci Nรกstฤ›nka โ†’ Nรกklady\n- Pล™epnout primรกrnรญ model na GLM/MiniMax\n- Pro nekritickรฉ รบlohy pouลพijte bezplatnou รบroveลˆ (Gemini CLI, iFlow).\n\n**Porty ล™รญdicรญho panelu/API jsou nesprรกvnรฉ**\n\n- `PORT` je kanonickรฝ zรกkladnรญ port (a standardnฤ› port API)\n- `API_PORT` pล™episuje pouze posluchaฤ API kompatibilnรญ s OpenAI.\n- `DASHBOARD_PORT` pล™episuje pouze posluchaฤ dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaลกi veล™ejnou URL adresu ล™รญdicรญho panelu (pro zpฤ›tnรก volรกnรญ OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ovฤ›ล™te, zda `BASE_URL` odkazuje na vaลกi spuลกtฤ›nou instanci.\n- Ovฤ›ล™te, zda `CLOUD_URL` odkazuje na vรกลก oฤekรกvanรฝ cloudovรฝ koncovรฝ bod.\n- Udrลพujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na stranฤ› serveru.\n\n**Prvnรญ pล™ihlรกลกenรญ nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud nenรญ nastaveno, zรกloลพnรญ heslo je `123456`\n\n**ลฝรกdnรฉ protokoly poลพadavkลฏ**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test pล™ipojenรญ ukazuje โ€žNeplatnรฉโ€œ pro poskytovatele kompatibilnรญ s OpenAI**\n\n- Mnoho poskytovatelลฏ nezpล™รญstupลˆuje koncovรฝ bod `/models`\n- OmniRoute v1.0.6+ zahrnuje zรกloลพnรญ ovฤ›ล™enรญ pomocรญ dokonฤenรญ chatu\n- Zajistฤ›te, aby zรกkladnรญ URL adresa obsahovala pล™รญponu `/v1`\n\n### ๐Ÿ” OAuth na vzdรกlenรฉm serveru\n\n\n\n> **โš ๏ธ Dลฏleลพitรฉ pro uลพivatele, kteล™รญ provozujรญ OmniRoute na VPS, Dockeru nebo jakรฉmkoli vzdรกlenรฉm serveru**\n\n#### Proฤ selhรกvรก OAuth v rozhranรญ CLI Antigravity / Gemini na vzdรกlenรฝch serverech?\n\nPoskytovatelรฉ rozhranรญ CLI **Antigravity** a **Gemini** pouลพรญvajรญ **Google OAuth 2.0** . Google vyลพaduje, aby se `redirect_uri` v toku OAuth pล™esnฤ› shodoval s jednรญm z pล™edregistrovanรฝch URI v konzoli Google Cloud Console aplikace.\n\nPล™ihlaลกovacรญ รบdaje OAuth, kterรฉ jsou souฤรกstรญ OmniRoute, jsou registrovรกny **pouze pro `localhost`** . Kdyลพ pล™istupujete k OmniRoute na vzdรกlenรฉm serveru (napล™. `https://omniroute.myserver.com` ), Google odmรญtne ovฤ›ล™enรญ pomocรญ:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### ล˜eลกenรญ: Nakonfigurujte si vlastnรญ pล™ihlaลกovacรญ รบdaje OAuth\n\nV Google Cloud Console je potล™eba vytvoล™it **ID klienta OAuth 2.0** s URI vaลกeho serveru.\n\n#### Krok za krokem\n\n**1. Otevล™ete konzoli Google Cloud**\n\nPล™ejdฤ›te na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvoล™te novรฉ ID klienta OAuth 2.0**\n\n- Kliknฤ›te na **โ€ž+ Vytvoล™it pล™ihlaลกovacรญ รบdajeโ€œ** โ†’ **โ€žID klienta OAuthโ€œ**\n- Typ aplikace: **โ€žWebovรก aplikaceโ€œ**\n- Nรกzev: cokoli chcete (napล™. `OmniRoute Remote` )\n\n**3. Pล™idejte autorizovanรฉ URI pro pล™esmฤ›rovรกnรญ**\n\nDo pole **โ€žAutorizovanรฉ identifikรกtory URI pro pล™esmฤ›rovรกnรญโ€œ** pล™idejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraฤte `your-server.com` domรฉnou nebo IP adresou vaลกeho serveru (v pล™รญpadฤ› potล™eby uveฤte i port, napล™. `http://45.33.32.156:20128/callback` ).\n\n**4. Uloลพte a zkopรญrujte pล™ihlaลกovacรญ รบdaje**\n\nPo vytvoล™enรญ Google zobrazรญ **ID klienta** a **tajnรฝ kรณd klienta** .\n\n**5. Nastavenรญ promฤ›nnรฝch prostล™edรญ**\n\nVe vaลกem souboru `.env` (nebo promฤ›nnรฝch prostล™edรญ Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu pล™ipojit**\n\nล˜รญdicรญ panel โ†’ Poskytovatelรฉ โ†’ Antigravity (nebo Gemini CLI) โ†’ OAuth\n\nGoogle nynรญ bude sprรกvnฤ› pล™esmฤ›rovรกvat na `https://your-server.com/callback` .\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nPokud si teฤ nechcete nastavovat vlastnรญ pล™ihlaลกovacรญ รบdaje, mลฏลพete stรกle pouลพรญt **ruฤnรญ postup pro URL** :\n\n1. OmniRoute otevรญrรก autorizaฤnรญ URL od Googlu\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru).\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe (i kdyลพ se strรกnka nenaฤte)\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute.\n5. Kliknฤ›te na **โ€žPล™ipojitโ€œ**\n\n> To funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na to, zda se naฤetla pล™esmฤ›rovacรญ strรกnka.\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nChcete-li zรญskat pล™รญstup k pล™ihlaลกovacรญm รบdajลฏm bez vlastnรญ konfigurace, mลฏลพete pouลพรญt nรกsledujรญcรญ postup:\n\n1. OmniRoute otevล™e URL autorizace Google\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru)\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute\n5. Kliknฤ›te na **โ€žPล™ipojit\"**\n\n> Toto ล™eลกenรญ funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na naฤtenรญ pล™esmฤ›rovacรญ strรกnky.\n\n---\n\n## ๐Ÿ› ๏ธ Technologickรฝ stack\n\n
\nKliknutรญm rozbalรญte podrobnosti o technologickรฉm stacku\n
\n\n- **Runtime** : Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ **nenรญ podporovรกn** โ€” nativnรญ binรกrnรญ soubory `better-sqlite3` jsou nekompatibilnรญ)\n- **Jazyk** : TypeScript 5.9 โ€” **100% TypeScript** napล™รญฤ `src/` a `open-sse/` ( `any` v zรกkladnรญch modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databรกze** : LowDB (JSON) + SQLite (stav domรฉny + protokoly proxy + audit MCP + rozhodnutรญ o smฤ›rovรกnรญ)\n- **Schรฉmata** : Zod (validace I/O nรกstrojลฏ MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamovรกnรญ** : Udรกlosti odeslanรฉ serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klรญฤe + autorizace s rozsahem MCP\n- **Testovรกnรญ** : Node.js test runner + Vitest (900+ testลฏ vฤetnฤ› unit, integraฤnรญch, E2E)\n- **CI/CD** : Akce GitHubu (automatickรฉ publikovรกnรญ v npm + Docker Hub pล™i vydรกnรญ)\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **Balรญฤek** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistiฤ, exponenciรกlnรญ odstavenรญ, ochrana proti hromลฏm, faleลกnรฉ TLS, automatickรฉ kombinovanรฉ samoopravovรกnรญ\n\n---\n\n## ๐Ÿ“– Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uลพivatelskรก pล™รญruฤka](docs/USER_GUIDE.md) | Poskytovatelรฉ, kombinace, integrace CLI, nasazenรญ |\n| [Referenฤnรญ informace k API](docs/API_REFERENCE.md) | Vลกechny koncovรฉ body s pล™รญklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nรกstrojลฏ MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamovรกnรญ, sprรกva รบloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorovรฉ bodovรกnรญ, balรญฤky reลพimลฏ, samolรฉฤba |\n| [Odstraลˆovรกnรญ problรฉmลฏ](docs/TROUBLESHOOTING.md) | Bฤ›ลพnรฉ problรฉmy a jejich ล™eลกenรญ |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a internรญ prvky systรฉmu |\n| [Pล™ispรญvรกnรญ](CONTRIBUTING.md) | Nastavenรญ a pokyny pro vรฝvoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpeฤnostnรญ zรกsady](SECURITY.md) | Hlรกลกenรญ zranitelnostรญ a bezpeฤnostnรญ postupy |\n| [Nasazenรญ virtuรกlnรญho poฤรญtaฤe](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletnรญ prลฏvodce: Nastavenรญ virtuรกlnรญho poฤรญtaฤe + nginx + Cloudflare |\n| [Galerie funkcรญ](docs/FEATURES.md) | Vizuรกlnรญ prohlรญdka ล™รญdicรญho panelu se snรญmky obrazovky |\n| [Kontrolnรญ seznam vydรกnรญ](docs/RELEASE_CHECKLIST.md) | Kroky ovฤ›ล™enรญ pล™ed vydรกnรญm |\n\n---\n\n## ๐Ÿ—บ๏ธ Plรกn\n\nOmniRoute mรก **v plรกnu vรญce neลพ 210 funkcรญ** v nฤ›kolika fรกzรญch vรฝvoje. Zde jsou klรญฤovรฉ oblasti:\n\n| Kategorie | Plรกnovanรฉ funkce | Hlavnรญ body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| ๐Ÿง  **Smฤ›rovรกnรญ a inteligence** | 25+ | Smฤ›rovรกnรญ s nejniลพลกรญ latencรญ, smฤ›rovรกnรญ zaloลพenรฉ na tagech, kontrola kvรณt pล™ed vรฝstupem, vรฝbฤ›r รบฤtu P2C |\n| ๐Ÿ”’ **Zabezpeฤenรญ a dodrลพovรกnรญ pล™edpisลฏ** | 20+ | Zpevnฤ›nรญ SSRF, maskovรกnรญ pล™ihlaลกovacรญch รบdajลฏ, limit rychlosti pro kaลพdรฝ koncovรฝ bod, stanovenรญ rozsahu klรญฤลฏ pro sprรกvu |\n| ๐Ÿ“Š **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledovรกnรญ kvรณt v reรกlnรฉm ฤase, sledovรกnรญ nรกkladลฏ podle modelu |\n| ๐Ÿ”„ **Integrace poskytovatelลฏ** | 20+ | Dynamickรฝ registr modelลฏ, doba zchlazenรญ poskytovatelลฏ, Codex pro vรญce รบฤtลฏ, analรฝza kvรณt Copilota |\n| โšก **Vรฝkon** | 15+ | Dvojitรก vrstva mezipamฤ›ti, mezipamฤ›ลฅ vรฝzev, mezipamฤ›ลฅ odpovฤ›dรญ, udrลพovรกnรญ streamovรกnรญ, dรกvkovรฉ API |\n| ๐ŸŒ **Ekosystรฉm** | 10+ | WebSocket API, horkรฉ opฤ›tovnรฉ naฤรญtรกnรญ konfigurace, distribuovanรฉ รบloลพiลกtฤ› konfigurace, komerฤnรญ reลพim |\n\n### ๐Ÿ”œ Jiลพ brzy\n\n- ๐Ÿ”— **Integrace OpenCode** โ€” Nativnรญ podpora poskytovatelลฏ pro IDE kรณdovรกnรญ s AI v OpenCode\n- ๐Ÿ”— **Integrace TRAE** โ€” Plnรก podpora vรฝvojovรฉho rรกmce TRAE pro umฤ›lou inteligenci\n- ๐Ÿ“ฆ **Dรกvkovรฉ API** โ€” Asynchronnรญ dรกvkovรฉ zpracovรกnรญ hromadnรฝch poลพadavkลฏ\n- ๐ŸŽฏ **Smฤ›rovรกnรญ na zรกkladฤ› tagลฏ** โ€” Smฤ›rovรกnรญ poลพadavkลฏ na zรกkladฤ› vlastnรญch tagลฏ a metadat\n- ๐Ÿ’ฐ **Strategie nejniลพลกรญch nรกkladลฏ** โ€“ Automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n> ๐Ÿ“ รšplnรฉ specifikace funkcรญ jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobnรฝch specifikacรญ)\n\n---\n\n## ๐Ÿ‘ฅ Pล™ispฤ›vatelรฉ\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Pล™ispฤ›vatelรฉ](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak pล™ispฤ›t\n\n1. Vytvoล™enรญ forku repozitรกล™e\n2. Vytvoล™te si vlastnรญ vฤ›tev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrฤte zmฤ›ny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do vฤ›tve ( `git push origin feature/amazing-feature` )\n5. Otevล™รญt ลพรกdost o zmฤ›ny (pull request)\n\nPodrobnรฉ pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydรกnรญ novรฉ verze\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Hvฤ›zdnรก historie\n\n## Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## ๐Ÿ™ Podฤ›kovรกnรญ\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** โ€“ pลฏvodnรญmu projektu, kterรฝ inspiroval tento fork. OmniRoute stavรญ na tomto neuvฤ›ล™itelnรฉm zรกkladu s dalลกรญmi funkcemi, multimodรกlnรญmi API a kompletnรญm pล™epsรกnรญm TypeScriptu.\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€“ pลฏvodnรญ implementaci Go, kterรก inspirovala tento JavaScriptovรฝ port.\n\n---\n\n## ๐Ÿ“„ Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n
\n Vytvoล™eno s โค๏ธ pro vรฝvojรกล™e, kteล™รญ programujรญ 24 hodin dennฤ›, 7 dnรญ v tรฝdnu\n
\n

omniroute.online

\n
\n\n"}, "8182825e92dd0b46ae7d855196abb897f9bc23e5": {"t": 1785764464.5762768, "n": 92325, "h": "844c1ed70cd6a6fc", "c": "# ๐Ÿš€ OmniRoute โ€” Bezplatnรก brรกna umฤ›lรฉ inteligence\n\n### Nikdy nepล™estรกvejte s kรณdovรกnรญm. Chytrรฉ smฤ›rovรกnรญ k **BEZPLATNรM a levnรฝm modelลฏm AI** s automatickรฝm pล™epรญnรกnรญm mezi zรกloลพnรญmi systรฉmy.\n\n_Vรกลก univerzรกlnรญ API proxy โ€“ jeden endpoint, vรญce neลพ 44 poskytovatelลฏ, nulovรฉ vรฝpadky. Nynรญ s orchestracรญ agentลฏ **MCP a A2A** ._\n\n**Dokonฤenรญ chatu โ€ข Vklรกdรกnรญ โ€ข Generovรกnรญ obrรกzkลฏ โ€ข Video โ€ข Hudba โ€ข Audio โ€ข Zmฤ›na poล™adรญ โ€ข **Vyhledรกvรกnรญ na webu** โ€ข MCP server โ€ข A2A protokol โ€ข 100% TypeScript**\n\n---\n\n
\n
\n

\"verze\"Docker\"Licence\"\"Webovรฉ\"WhatsApp\"

\n

๐ŸŒ Webovรฉ strรกnky โ€ข ๐Ÿš€ Rychlรฝ start โ€ข ๐Ÿ’ก Funkce โ€ข ๐Ÿ“– Dokumentace โ€ข ๐Ÿ’ฐ Cenรญk โ€ข ๐Ÿ’ฌ WhatsApp

\n
\n\n๐ŸŒ **Dostupnรฉ v:** ๐Ÿ‡บ๐Ÿ‡ธ [Angliฤtina](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n### ๐Ÿ†• What's New in v3.0.0\n\n| Area | Change |\n| -------------------------- | --------------------------------------------------------------------------------- |\n| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| โœ… **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |\n| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| ๐ŸŒ **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| ๐Ÿ”ง **926 Tests** | Full test suite passes with 0 failures |\n\n### ๐Ÿ†• What's New in v3.0.0\n\n| Area | Change |\n| -------------------------- | --------------------------------------------------------------------------------- |\n| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| โœ… **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |\n| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| ๐ŸŒ **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| ๐Ÿ”ง **926 Tests** | Full test suite passes with 0 failures |\n\n---\n\n## ๐Ÿ–ผ๏ธ Hlavnรญ ovlรกdacรญ panel\n\n
\"ล˜รญdicรญ
\n\n---\n\n## ๐Ÿ“ธ Nรกhled ล™รญdicรญho panelu\n\n
\nKliknutรญm zobrazรญte snรญmky obrazovky z ล™รญdicรญho panelu\n
\n\n| Strana | Snรญmek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelรฉ** | ![Poskytovatelรฉ](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdravรญ** | ![Zdravรญ](docs/screenshots/04-health.png) |\n| **Pล™ekladatel** | ![Pล™ekladatel](docs/screenshots/05-translator.png) |\n| **Nastavenรญ** | ![Nastavenรญ](docs/screenshots/06-settings.png) |\n| **Nรกstroje CLI** | ![Nรกstroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly pouลพรญvรกnรญ** | ![Pouลพรญvรกnรญ](docs/screenshots/08-usage.png) |\n| **Koncovรฉ body** | ![Koncovรฉ body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### ๐Ÿค– Bezplatnรฝ poskytovatel umฤ›lรฉ inteligence pro vaลกe oblรญbenรฉ programรกtory\n\n_Pล™ipojte libovolnรฝ nรกstroj IDE nebo CLI s umฤ›lou inteligencรญ pล™es OmniRoute โ€” bezplatnou API brรกnu pro neomezenรฉ kรณdovรกnรญ._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\"OpenClaw\"
OpenClaw
โญ 205 tisรญc 		\"NanoBot\"
NanoBot
โญ 20,9 tisรญc 		\"PicoClaw\"
PicoClaw
โญ 14,6 tisรญc 		\"ZeroClaw\"
ZeroClaw
โญ 9,9 tisรญc 		\"ลฝeleznรฝ
ลฝeleznรฝ drรกp
โญ 2,1 tisรญce
\"OpenCode\"
OpenCode
โญ 106 tisรญc 		\"Codex
Codex CLI
โญ 60,8 tisรญc 		\"Claude
Claude Code
โญ 67,3 tisรญc 		\"Gemini
Gemini CLI
โญ 94,7 tisรญc 		\"Kilo
Kilo kรณd
โญ 15,5 tisรญc
\n\n๐Ÿ“ก Vลกichni agenti se pล™ipojujรญ pล™es http://localhost:20128/v1 nebo http://cloud.omniroute.online/v1 โ€” jedna konfigurace, neomezenรฉ modely a kvรณty\n\n---\n\n## ๐Ÿค” Proฤ OmniRoute?\n\n**Pล™estaลˆte plรฝtvat penฤ›zi a narรกลพet na limity:**\n\n- Kvรณta pล™edplatnรฉho vyprลกรญ kaลพdรฝ mฤ›sรญc\n- Limity rychlosti vรกm zabrรกnรญ v kรณdovรกnรญ\n- Drahรก API (20โ€“50 USD/mฤ›sรญc na poskytovatele)\n- Ruฤnรญ pล™epรญnรกnรญ mezi poskytovateli\n\n**OmniRoute to ล™eลกรญ:**\n\n- โœ… **Maximalizujte pล™edplatnรฉ** โ€“ Sledujte kvรณtu, vyuลพijte kaลพdou ฤรกstku pล™ed resetovรกnรญm\n- โœ… **Automatickรฉ zรกloลพnรญ** โ€“ Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma, ลพรกdnรฉ vรฝpadky\n- โœ… **Vรญce รบฤtลฏ** โ€“ Round-robin mezi รบฤty u jednotlivรฝch poskytovatelลฏ\n- โœ… **Univerzรกlnรญ** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakรฝmkoli nรกstrojem CLI\n\n---\n\n## ๐Ÿ“ง Podpora\n\n> ๐Ÿ’ฌ **Pล™idejte se k naลกรญ komunitฤ›!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Zรญskejte pomoc, sdรญlejte tipy a buฤte v obraze.\n\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problรฉmy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitnรญ skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Pล™ispรญvรกnรญ** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevล™ete ลพรกdost o pล™รญspฤ›vek nebo si vyberte `good first issue`\n- **Pลฏvodnรญ projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Hlรกsรญte chybu?\n\nPล™i otevรญrรกnรญ problรฉmu spusลฅte pล™รญkaz system-info a pล™iloลพte vygenerovanรฝ soubor:\n\n```bash\nnpm run system-info\n```\n\nTรญm se vygeneruje soubor `system-info.txt` s verzรญ Node.js, verzรญ OmniRoute, podrobnostmi o operaฤnรญm systรฉmu, nainstalovanรฝmi nรกstroji CLI (iflow, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systรฉmovรฝmi balรญฤky โ€“ vลกe, co potล™ebujeme k rychlรฉ reprodukci vaลกeho problรฉmu. Soubor pล™iloลพte pล™รญmo k vaลกemu problรฉmu na GitHubu.\n\n---\n\n## ๐Ÿ”„ Jak to funguje\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ Co ล™eลกรญ OmniRoute โ€” 30 skuteฤnรฝch problรฉmลฏ a pล™รญpadลฏ pouลพitรญ\n\n> **Kaลพdรฝ vรฝvojรกล™ pouลพรญvajรญcรญ nรกstroje umฤ›lรฉ inteligence se s tฤ›mito problรฉmy setkรกvรก dennฤ›.** OmniRoute byl vytvoล™en tak, aby je vลกechny vyล™eลกil โ€“ od pล™ekroฤenรญ nรกkladลฏ po regionรกlnรญ bloky, od nefunkฤnรญch tokลฏ OAuth aลพ po operace s protokoly a sledovatelnost v podniku.\n\n
\n๐Ÿ’ธ 1. โ€žPlatรญm si drahรฉ pล™edplatnรฉ, ale stรกle mฤ› ruลกรญ limityโ€œ\n
\n\nVรฝvojรกล™i platรญ za Claude Pro, Codex Pro nebo GitHub Copilot 20โ€“200 dolarลฏ mฤ›sรญฤnฤ›. I pล™i platbฤ› mรก kvรณta strop โ€“ 5 hodin pouลพรญvรกnรญ, tรฝdennรญ limity nebo limity rychlosti za minutu. Uprostล™ed kรณdovacรญ relace poskytovatel pล™estane reagovat a vรฝvojรกล™ ztrรกcรญ plynulost a produktivitu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Inteligentnรญ ฤtyล™รบrovลˆovรก zรกloลพnรญ sluลพba** โ€“ Pokud dojde kvรณta pล™edplatnรฉho, โ€‹โ€‹automaticky se pล™esmฤ›ruje na API klรญฤ โ†’ Levnรฉ โ†’ Zdarma bez manuรกlnรญho zรกsahu\n- **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** โ€“ Zobrazuje spotล™ebu tokenลฏ v reรกlnรฉm ฤase s odpoฤรญtรกvรกnรญm resetovรกnรญ (5 hodin, dennฤ›, tรฝdnฤ›)\n- **Podpora vรญce รบฤtลฏ** โ€“ Vรญce รบฤtลฏ u jednoho poskytovatele s automatickรฝm pล™epรญnรกnรญm โ€“ kdyลพ jeden dojde, pล™epne se na dalลกรญ\n- **Vlastnรญ kombinace** โ€” Pล™izpลฏsobitelnรฉ zรกloลพnรญ ล™etฤ›zce se 6 strategiemi vyvaลพovรกnรญ (fill-first, round robin, P2C, nรกhodnรฉ, nejmรฉnฤ› pouลพรญvanรฉ, nรกkladovฤ› optimalizovanรฉ)\n- **Codex Business Quotas** โ€” Sledovรกnรญ kvรณt pracovnรญho prostoru firmy/tรฝmu pล™รญmo v dashboardu\n\n
\n๐Ÿ”Œ 2. โ€žPotล™ebuji pouลพรญt vรญce poskytovatelลฏ, ale kaลพdรฝ mรก jinรฉ APIโ€œ\n
\n\nOpenAI pouลพรญvรก jeden formรกt, Claude (Anthropic) jinรฝ a Gemini jeลกtฤ› tล™etรญ. Pokud chce vรฝvojรกล™ testovat modely od rลฏznรฝch poskytovatelลฏ nebo mezi nimi pล™echรกzet, musรญ pล™ekonfigurovat SDK, zmฤ›nit koncovรฉ body a vypoล™รกdat se s nekompatibilnรญmi formรกty. Vlastnรญ poskytovatelรฉ (FriendLI, NIM) majรญ nestandardnรญ koncovรฉ body modelลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sjednocenรฝ koncovรฝ bod** โ€” Jeden `http://localhost:20128/v1` slouลพรญ jako proxy pro vลกech 67+ poskytovatelลฏ.\n- **Pล™eklad formรกtu** โ€” Automatickรฝ a transparentnรญ: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Sanitizace odpovฤ›dรญ** โ€” Odstraลˆuje nestandardnรญ pole ( `x_groq` , `usage_breakdown` , `service_tier` ), kterรก poruลกujรญ OpenAI SDK v1.83+\n- **Normalizace rolรญ** โ€” Pล™evรกdรญ `developer` โ†’ `system` pro poskytovatele bez OpenAI; `system` โ†’ `user` pro GLM/ERNIE\n- **Extrakce tagลฏ Think** โ€” Extrahuje bloky `` z modelลฏ, jako je DeepSeek R1, do standardizovanรฉho `reasoning_content`\n- **Strukturovanรฝ vรฝstup pro Gemini** โ€” `json_schema` โ†’ automatickรก konverze `responseMimeType` / `responseSchema`\n- **Vรฝchozรญ hodnota `stream` je `false`** โ€“ Odpovรญdรก specifikaci OpenAI, ฤรญmลพ se zabrรกnรญ neoฤekรกvanรฉmu SSE v Python/Rust/Go SDK.\n\n
\n๐ŸŒ 3. โ€žMลฏj poskytovatel AI blokuje mลฏj region/zemiโ€œ\n
\n\nPoskytovatelรฉ jako OpenAI/Codex blokujรญ pล™รญstup z urฤitรฝch geografickรฝch oblastรญ. Uลพivatelรฉ se bฤ›hem pล™ipojenรญ OAuth a API dostรกvajรญ k chybรกm jako `unsupported_country_region_territory` . To je obzvlรกลกtฤ› frustrujรญcรญ pro vรฝvojรกล™e z rozvojovรฝch zemรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **3รบrovลˆovรก konfigurace proxy** โ€“ Konfigurovatelnรก proxy na 3 รบrovnรญch: globรกlnรญ (veลกkerรฝ provoz), pro jednotlivรฉ poskytovatele (pouze jeden poskytovatel) a pro jednotlivรฉ pล™ipojenรญ/klรญฤ\n- **Barevnฤ› kรณdovanรฉ odznaky proxy** โ€“ Vizuรกlnรญ indikรกtory: ๐ŸŸข globรกlnรญ proxy, ๐ŸŸก proxy poskytovatele, ๐Ÿ”ต proxy pล™ipojenรญ, vลพdy zobrazujรญcรญ IP adresu\n- **Vรฝmฤ›na tokenลฏ OAuth prostล™ednictvรญm proxy** โ€“ tok OAuth takรฉ prochรกzรญ pล™es proxy, ฤรญmลพ se ล™eลกรญ `unsupported_country_region_territory`\n- **Testy pล™ipojenรญ pล™es proxy** โ€“ Testy pล™ipojenรญ pouลพรญvajรญ nakonfigurovanรฝ proxy (jiลพ ลพรกdnรฉ pล™รญmรฉ obchรกzenรญ)\n- **Podpora SOCKS5** โ€” Plnรก podpora proxy SOCKS5 pro odchozรญ smฤ›rovรกnรญ\n- **TLS Fingerprint Spoofing** โ€” Otisk prstu TLS podobnรฝ prohlรญลพeฤi pomocรญ `wreq-js` pro obchรกzenรญ detekce botลฏ\n- **๐Ÿ” Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** โ€” Zmฤ›nรญ poล™adรญ zรกhlavรญ a polรญ v tฤ›le serveru tak, aby odpovรญdala nativnรญm binรกrnรญm podpisลฏm v CLI, ฤรญmลพ drasticky sniลพuje riziko nahlaลกovรกnรญ รบฤtu. IP adresa proxy je zachovรกna โ€” zรญskรกte souฤasnฤ› stealth **i** maskovรกnรญ IP adresy.\n\n
\n๐Ÿ†“ 4. โ€žChci pouลพรญvat umฤ›lou inteligenci pro kรณdovรกnรญ, ale nemรกm penรญzeโ€œ\n
\n\nNe kaลพdรฝ si mลฏลพe dovolit zaplatit 20โ€“200 dolarลฏ mฤ›sรญฤnฤ› za pล™edplatnรฉ AI. Studenti, vรฝvojรกล™i z rozvรญjejรญcรญch se zemรญ, amatรฉล™i a freelanceล™i potล™ebujรญ pล™รญstup ke kvalitnรญm modelลฏm za nulovou cenu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vestavฤ›nรญ poskytovatelรฉ bezplatnรฉ รบrovnฤ›** โ€” Nativnรญ podpora pro 100% bezplatnรฉ poskytovatele: iFlow (5 neomezenรฝch modelลฏ pล™es OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezenรฉ modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisรญc tokenลฏ/mฤ›sรญc zdarma)\n- **Ollama Cloud** โ€” Cloudovฤ› hostovanรฉ modely Ollama na `api.ollama.com` s bezplatnou รบrovnรญ โ€žLight usageโ€œ; pouลพijte prefix `ollamacloud/`\n- **Kombinace pouze zdarma** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = 0 $/mฤ›sรญc s nulovรฝmi prostoji\n- **NVIDIA NIM Free Access** โ€” ~40 RPM developerskรฝ pล™รญstup k vรญce neลพ 70 modelลฏm na build.nvidia.com (pล™echod z kreditลฏ na ฤistรฉ limity rychlosti)\n- **Strategie optimalizace nรกkladลฏ** โ€“ Strategie smฤ›rovรกnรญ, kterรก automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n
\n๐Ÿ”’ 5. โ€žPotล™ebuji chrรกnit svou brรกnu umฤ›lรฉ inteligence pล™ed neoprรกvnฤ›nรฝm pล™รญstupemโ€œ\n
\n\nPล™i zpล™รญstupnฤ›nรญ brรกny umฤ›lรฉ inteligence sรญti (LAN, VPS, Docker) mลฏลพe kdokoli s adresou spotล™ebovat tokeny/kvรณtu vรฝvojรกล™e. Bez ochrany jsou API zranitelnรก vลฏฤi zneuลพitรญ, prompt injection a dalลกรญmu zneuลพitรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sprรกva klรญฤลฏ API** โ€“ generovรกnรญ, rotace a vymezovรกnรญ rozsahu pro kaลพdรฉho poskytovatele s vyhrazenou strรกnkou `/dashboard/api-manager`\n- **Oprรกvnฤ›nรญ na รบrovni modelu** โ€“ Omezenรญ klรญฤลฏ API na konkrรฉtnรญ modely ( `openai/*` , zรกstupnรฉ znaky) pomocรญ pล™epรญnaฤe Povolit vลกe/Omezit\n- **Ochrana koncovรฝch bodลฏ API** โ€“ Vyลพaduje klรญฤ pro `/v1/models` a blokuje konkrรฉtnรญ poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** โ€” Vลกechny trasy dashboardu chrรกnฤ›nรฉ middlewarem `withAuth` + tokeny CSRF\n- **Omezovaฤ rychlosti** โ€” Omezovรกnรญ rychlosti na IP s konfigurovatelnรฝmi okny\n- **Filtrovรกnรญ IP adres** โ€” Seznam povolenรฝch/blokovanรฝch adres pro ล™รญzenรญ pล™รญstupu\n- **Ochrana proti vklรกdรกnรญ vรฝzev** โ€“ Sanitizace proti ลกkodlivรฝm vzorcลฏm vรฝzev\n- **ล ifrovรกnรญ AES-256-GCM** โ€“ pล™ihlaลกovacรญ รบdaje jsou v klidovรฉm stavu ลกifrovรกny\n\n
\n๐Ÿ›‘ 6. โ€žMลฏj poskytovatel selhal a jรก ztratil/a programovacรญ tokโ€œ\n
\n\nPoskytovatelรฉ umฤ›lรฉ inteligence se mohou stรกt nestabilnรญmi, vracet chyby 5xx nebo dosรกhnout doฤasnรฝch limitลฏ rychlosti. Pokud je vรฝvojรกล™ zรกvislรฝ na jedinรฉm poskytovateli, je jeho prรกce pล™eruลกena. Bez jistiฤลฏ mลฏลพe opakovanรฉ pokusy vรฉst k pรกdu aplikace.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Jistiฤ pro kaลพdรฝ model** โ€“ Automatickรฉ otevรญrรกnรญ/zavรญrรกnรญ s konfigurovatelnรฝmi prahovรฝmi hodnotami a dobou ochlazovรกnรญ (Zavล™eno/Otevล™eno/Poloviฤnรญ otevล™enรญ), rozsah definovanรฝ pro kaลพdรฝ model, aby se zabrรกnilo kaskรกdovรกnรญ blokลฏ\n- **Exponenciรกlnรญ odklad** โ€” Progresivnรญ zpoลพdฤ›nรญ opakovรกnรญ\n- **Anti-Thundering Herd** โ€” ochrana Mutex + semafor proti soubฤ›ลพnรฝm bouล™รญm s opakovanรฝmi pokusy\n- **Kombinovanรฉ zรกloลพnรญ ล™etฤ›zce** โ€“ Pokud primรกrnรญ poskytovatel selลพe, automaticky se propadne ล™etฤ›zcem bez zรกsahu.\n- **Kombinovanรฝ jistiฤ** โ€“ Automaticky deaktivuje selhรกvajรญcรญho poskytovatele v rรกmci kombinovanรฉho ล™etฤ›zce\n- **Dashboard stavu** โ€” Monitorovรกnรญ provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti, latence p50/p95/p99\n\n
\n๐Ÿ”ง 7. โ€žKonfigurace kaลพdรฉho nรกstroje umฤ›lรฉ inteligence je zdlouhavรก a opakujรญcรญ seโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Kaลพdรฝ nรกstroj potล™ebuje jinou konfiguraci (API endpoint, klรญฤ, model). Pล™ekonfigurovรกnรญ pล™i zmฤ›nฤ› poskytovatele nebo modelu je ztrรกta ฤasu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel nรกstrojลฏ CLI** โ€” Vyhrazenรก strรกnka s nastavenรญm jednรญm kliknutรญm pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generรกtor konfigurace GitHub Copilot** โ€“ Generuje `chatLanguageModels.json` pro VS Code s hromadnรฝm vรฝbฤ›rem modelu\n- **Prลฏvodce zavรกdฤ›nรญm** โ€“ 4krokovรฉ nastavenรญ pro zaฤรญnajรญcรญ uลพivatele\n- **Jeden koncovรฝ bod, vลกechny modely** โ€“ jednou nakonfigurujte `http://localhost:20128/v1` a zรญskejte pล™รญstup k vรญce neลพ 44 poskytovatelลฏm\n\n
\n๐Ÿ”‘ 8. โ€žSprรกva OAuth tokenลฏ od vรญce poskytovatelลฏ je pekloโ€œ\n
\n\nClaude Code, Codex, Gemini CLI, Copilot โ€“ vลกechny pouลพรญvajรญ OAuth 2.0 s tokeny s vyprลกenรญm platnosti. Vรฝvojรกล™i se musรญ neustรกle znovu autentizovat, ล™eลกit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdรกlenรฝch serverech. Obzvlรกลกtฤ› problematickรฝ je OAuth v LAN/VPS.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Automatickรก aktualizace tokenลฏ** โ€“ Tokeny OAuth se obnovujรญ na pozadรญ pล™ed vyprลกenรญm platnosti.\n- **Vestavฤ›nรฝ OAuth 2.0 (PKCE)** โ€“ Automatickรฝ tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow\n- **Multi-Account OAuth** โ€” Vรญce รบฤtลฏ na poskytovatele prostล™ednictvรญm extrakce tokenลฏ JWT/ID\n- **OAuth LAN/Remote Fix** โ€” Detekce privรกtnรญ IP adresy pro `redirect_uri` + manuรกlnรญ reลพim URL pro vzdรกlenรฉ servery\n- **OAuth Behind Nginx** โ€” Pouลพรญvรก `window.location.origin` pro kompatibilitu s reverznรญ proxy\n- **Prลฏvodce vzdรกlenรฝm OAuth** โ€“ Podrobnรฝ nรกvod k pล™ihlaลกovacรญm รบdajลฏm Google Cloud na VPS/Dockeru\n\n
\n๐Ÿ“Š 9. โ€žNevรญm, kolik utrรกcรญm ani kdeโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ vรญce placenรฝch poskytovatelลฏ, ale nemajรญ jednotnรฝ pล™ehled o vรฝdajรญch. Kaลพdรฝ poskytovatel mรก svลฏj vlastnรญ fakturaฤnรญ panel, ale neexistuje ลพรกdnรฝ konsolidovanรฝ pล™ehled. Mohou se hromadit neoฤekรกvanรฉ nรกklady.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard pro analรฝzu nรกkladลฏ** โ€“ Sledovรกnรญ nรกkladลฏ na token a sprรกva rozpoฤtu pro kaลพdรฉho poskytovatele\n- **Rozpoฤtovรฉ limity na รบroveลˆ** โ€“ Strop vรฝdajลฏ na รบroveลˆ, kterรฝ spouลกtรญ automatickรฝ zรกloลพnรญ reลพim\n- **Konfigurace cen podle modelu** โ€“ Konfigurovatelnรฉ ceny podle modelu\n- **Statistiky pouลพitรญ pro kaลพdรฝ klรญฤ API** โ€” Poฤet poลพadavkลฏ a ฤasovรฉ razรญtko poslednรญho pouลพitรญ pro kaลพdรฝ klรญฤ\n- **Analytickรฝ panel** โ€“ Statistickรฉ karty, graf vyuลพitรญ modelu, tabulka poskytovatelลฏ s mรญrou รบspฤ›ลกnosti a latencรญ\n\n
\n๐Ÿ› 10. โ€žNedokรกลพu diagnostikovat chyby a problรฉmy ve volรกnรญ umฤ›lรฉ inteligence.โ€œ\n
\n\nKdyลพ volรกnรญ selลพe, vรฝvojรกล™ nevรญ, zda se jednalo o limit rychlosti, vyprลกelรฝ token, ลกpatnรฝ formรกt nebo chybu poskytovatele. Fragmentovanรฉ protokoly napล™รญฤ rลฏznรฝmi terminรกly. Bez sledovatelnosti je ladฤ›nรญ metodou pokus-omyl.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel jednotnรฝch protokolลฏ** โ€“ 4 karty: Protokoly poลพadavkลฏ, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlรญลพeฤ protokolลฏ konzole** โ€” Prohlรญลพeฤ protokolลฏ v reรกlnรฉm ฤase ve stylu terminรกlu s barevnฤ› kรณdovanรฝmi รบrovnฤ›mi, automatickรฝm posouvรกnรญm, vyhledรกvรกnรญm a filtrovรกnรญm\n- **Protokoly proxy SQLite** โ€“ trvalรฉ protokoly, kterรฉ pล™eลพijรญ restart serveru\n- **Pล™ekladaฤskรฉ hล™iลกtฤ›** โ€” 4 reลพimy ladฤ›nรญ: Hล™iลกtฤ› (pล™eklad formรกtu), Tester chatu (okruลพnรญ), Testovacรญ stลฏl (dรกvkovรฝ), ลฝivรฝ monitor (v reรกlnรฉm ฤase)\n- **Telemetrie poลพadavkลฏ** โ€” latence p50/p95/p99 + trasovรกnรญ X-Request-Id\n- **Souborovรฉ protokolovรกnรญ s rotacรญ** โ€“ Konzolovรฝ interceptor zachycuje vลกe do protokolu JSON s rotacรญ na zรกkladฤ› velikosti\n- **Zprรกva o systรฉmovรฝch informacรญch** โ€” pล™รญkaz `npm run system-info` vygeneruje `system-info.txt` s kompletnรญm popisem vaลกeho prostล™edรญ (verze uzlu, verze OmniRoute, operaฤnรญ systรฉm, nรกstroje CLI, stav Dockeru/PM2). Pล™iloลพte jej pล™i hlรกลกenรญ problรฉmลฏ pro okamลพitรฉ tล™รญdฤ›nรญ.\n\n
\n๐Ÿ—๏ธ 11. โ€žNasazenรญ a รบdrลพba brรกny je sloลพitรกโ€œ\n
\n\nInstalace, konfigurace a รบdrลพba AI proxy v rลฏznรฝch prostล™edรญch (lokรกlnรญ, VPS, Docker, cloud) je pracnรก. Problรฉmy, jako jsou pevnฤ› zakรณdovanรฉ cesty, `EACCES` u adresรกล™ลฏ, konflikty portลฏ a multiplatformnรญ sestavenรญ, pล™ispรญvajรญ k obtรญลพรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **npm globรกlnรญ instalace** โ€” `npm install -g omniroute && omniroute` โ€” hotovo\n- **Docker Multi-Platform** โ€” AMD64 + nativnรญ ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** โ€” `base` (bez nรกstrojลฏ CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopovรก aplikace Electron** โ€” Nativnรญ aplikace pro Windows/macOS/Linux se systรฉmovou liลกtou, automatickรฝm spuลกtฤ›nรญm a offline reลพimem\n- **Reลพim rozdฤ›lenรฝch portลฏ** โ€“ API a ล™รญdicรญ panel na samostatnรฝch portech pro pokroฤilรฉ scรฉnรกล™e (reverznรญ proxy, sรญลฅovรกnรญ kontejnerลฏ)\n- **Cloud Sync** โ€“ Konfigurace synchronizace mezi zaล™รญzenรญmi pomocรญ Cloudflare Workers\n- **Zรกlohy databรกzรญ** โ€” Automatickรฉ zรกlohovรกnรญ, obnovenรญ, export a import vลกech nastavenรญ\n\n
\n๐ŸŒ 12. โ€žRozhranรญ je pouze v angliฤtinฤ› a mลฏj tรฝm nemluvรญ anglickyโ€œ\n
\n\nTรฝmy v neanglicky mluvรญcรญch zemรญch, zejmรฉna v Latinskรฉ Americe, Asii a Evropฤ›, se potรฝkajรญ s rozhranรญmi pouze v angliฤtinฤ›. Jazykovรฉ bariรฉry sniลพujรญ mรญru pล™ijetรญ a zvyลกujรญ chyby v konfiguraci.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard i18n โ€” 30 jazykลฏ** โ€” Vลกech 500+ klรกves je pล™eloลพeno vฤetnฤ› arabลกtiny, bulharลกtiny, dรกnลกtiny, nฤ›mฤiny, ลกpanฤ›lลกtiny, finลกtiny, francouzลกtiny, hebrejลกtiny, hindลกtiny, maฤarลกtiny, indonรฉลกtiny, italลกtiny, japonลกtiny, korejลกtiny, malajลกtiny, holandลกtiny, norลกtiny, polลกtiny, portugalลกtiny (PT/BR), rumunลกtiny, ruลกtiny, slovenลกtiny, ลกvรฉdลกtiny, thajลกtiny, ukrajinลกtiny, vietnamลกtiny, ฤรญnลกtiny, filipรญnลกtiny a angliฤtiny\n- **Podpora RTL** โ€“ Podpora psanรญ zprava doleva pro arabลกtinu a hebrejลกtinu\n- **Vรญcejazyฤnรฉ soubory README** โ€” 30 kompletnรญch pล™ekladลฏ dokumentace\n- **Vรฝbฤ›r jazyka** โ€” Ikona glรณbu v zรกhlavรญ pro pล™epรญnรกnรญ v reรกlnรฉm ฤase\n\n
\n๐Ÿ”„ 13. โ€žPotล™ebuji vรญc neลพ jen chat โ€“ potล™ebuji vloลพenรฉ soubory, obrรกzky, zvuk.โ€œ\n
\n\nUmฤ›lรก inteligence nenรญ jen dokonฤovรกnรญ chatu. Vรฝvojรกล™i potล™ebujรญ generovat obrรกzky, pล™episovat zvuk, vytvรกล™et embeddedy pro RAG, mฤ›nit poล™adรญ dokumentลฏ a moderovat obsah. Kaลพdรฉ API mรก jinรฝ koncovรฝ bod a formรกt.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vklรกdรกnรญ** โ€” `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generovรกnรญ obrรกzkลฏ** โ€” `/v1/images/generations` s 10 poskytovateli a vรญce neลพ 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Pล™evod textu na video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Pล™evod textu na hudbu** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Pล™epis zvuku** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Pล™evod textu na ล™eฤ** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a dalลกรญ stรกvajรญcรญ poskytovatelรฉ\n- **Moderovรกnรญ** โ€” `/v1/moderations` โ€” Kontroly bezpeฤnosti obsahu\n- **Zmฤ›na poล™adรญ** โ€” `/v1/rerank` โ€” Zmฤ›na poล™adรญ relevance dokumentu\n- **Responses API** โ€” Plnรก podpora `/v1/responses` pro Codex\n\n
\n๐Ÿงช 14. โ€žNemรกm zpลฏsob, jak testovat a porovnรกvat kvalitu napล™รญฤ modely.โ€œ\n
\n\nVรฝvojรกล™i chtฤ›jรญ vฤ›dฤ›t, kterรฝ model je pro jejich pล™รญpad pouลพitรญ nejlepลกรญ โ€“ kรณd, pล™eklad, uvaลพovรกnรญ โ€“ ale ruฤnรญ porovnรกvรกnรญ je pomalรฉ. Neexistujรญ ลพรกdnรฉ integrovanรฉ nรกstroje pro vyhodnocovรกnรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Hodnocenรญ LLM** โ€” Testovรกnรญ Golden setu s 10 pล™edinstalovanรฝmi pล™รญpady zahrnujรญcรญmi pozdravy, matematiku, geografii, generovรกnรญ kรณdu, dodrลพovรกnรญ JSON, pล™eklad, markdown, odmรญtnutรญ bezpeฤnostnรญch poลพadavkลฏ\n- **4 strategie shody** โ€” `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovacรญ lavice pro pล™ekladatelskรฉ hล™iลกtฤ›** โ€” Dรกvkovรฉ testovรกnรญ s vรญce vstupy a oฤekรกvanรฝmi vรฝstupy, porovnรกnรญ napล™รญฤ poskytovateli\n- **Tester chatu** โ€” Kompletnรญ okruลพnรญ cesta s vizuรกlnรญm vykreslovรกnรญm odpovฤ›dรญ\n- **ลฝivรฝ monitor** โ€” Stream vลกech poลพadavkลฏ prochรกzejรญcรญch proxy serverem v reรกlnรฉm ฤase\n\n
\n๐Ÿ“ˆ 15. โ€žPotล™ebuji ลกkรกlovat bez ztrรกty vรฝkonuโ€œ\n
\n\nS rostoucรญm objemem poลพadavkลฏ generujรญ stejnรฉ otรกzky bez uklรกdรกnรญ do mezipamฤ›ti duplicitnรญ nรกklady. Bez idempotence duplicitnรญ poลพadavky plรฝtvajรญ zpracovรกnรญm. Je nutnรฉ dodrลพovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sรฉmantickรก mezipamฤ›ลฅ** โ€” Dvouvrstvรก mezipamฤ›ลฅ (signatura + sรฉmantika) sniลพuje nรกklady a latenci\n- **Idempotence poลพadavku** โ€” 5s deduplikaฤnรญ okno pro identickรฉ poลพadavky\n- **Detekce limitu rychlosti** โ€“ sledovรกnรญ otรกฤek za minutu (RPM), minimรกlnรญ mezera a maximรกlnรญ soubฤ›ลพnรฉ sledovรกnรญ pro kaลพdรฉho poskytovatele\n- **Upravitelnรฉ limity rychlosti** โ€” Konfigurovatelnรฉ vรฝchozรญ hodnoty v Nastavenรญ โ†’ Odolnost s perzistencรญ\n- **Mezipamฤ›ลฅ pro ovฤ›ล™enรญ klรญฤลฏ API** โ€” tล™รญvrstvรก mezipamฤ›ลฅ pro vรฝkon produkฤnรญho prostล™edรญ\n- **Dashboard s telemetriรญ** โ€“ latence p50/p95/p99, statistiky mezipamฤ›ti, dostupnost\n\n
\n๐Ÿค– 16. โ€žChci mรญt chovรกnรญ modelลฏ globรกlnฤ› pod kontrolouโ€œ\n
\n\nVรฝvojรกล™i, kteล™รญ chtฤ›jรญ vลกechny odpovฤ›di v urฤitรฉm jazyce, se specifickรฝm tรณnem nebo chtฤ›jรญ omezit tokeny pro uvaลพovรกnรญ. Konfigurace tรฉto funkce v kaลพdรฉm nรกstroji/poลพadavku je nepraktickรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vloลพenรญ systรฉmovรฉho prompt** โ€“ Globรกlnรญ prompt aplikovanรฝ na vลกechny poลพadavky\n- **Validace rozpoฤtu Thinking** โ€” ล˜รญzenรญ alokace tokenลฏ na poลพadavek (prลฏchozรญ, automatickรฉ, vlastnรญ, adaptivnรญ)\n- **6 strategiรญ smฤ›rovรกnรญ** โ€“ Globรกlnรญ strategie, kterรฉ urฤujรญ, jak jsou poลพadavky distribuovรกny\n- **Smฤ›rovaฤ se zรกstupnรฝmi znaky** โ€” vzory `provider/*` dynamicky smฤ›rujรญ k libovolnรฉmu poskytovateli\n- **Pล™epรญnรกnรญ povolenรญ/zakรกzรกnรญ kombinacรญ** โ€“ Pล™epรญnรกnรญ kombinacรญ pล™รญmo z ล™รญdicรญho panelu\n- **Pล™epรญnรกnรญ poskytovatele** โ€“ Povolenรญ/zakรกzรกnรญ vลกech pล™ipojenรญ pro poskytovatele jednรญm kliknutรญm\n- **Blokovanรญ poskytovatelรฉ** โ€“ Vylouฤenรญ konkrรฉtnรญch poskytovatelลฏ ze seznamu `/v1/models`\n\n
\n๐Ÿงฐ 17. โ€žPotล™ebuji nรกstroje MCP jako prvotล™รญdnรญ produktovรฉ funkce.โ€œ\n
\n\nMnoho bran umฤ›lรฉ inteligence odhaluje MCP pouze jako skrytรฝ implementaฤnรญ detail. Tรฝmy potล™ebujรญ viditelnou a spravovatelnou operaฤnรญ vrstvu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- MCP se zobrazuje v navigaci na ล™รญdicรญm panelu a na kartฤ› protokolu koncovรฉho bodu.\n- Vyhrazenรก strรกnka pro sprรกvu MCP s procesy, nรกstroji, rozsahy a auditem\n- Vestavฤ›nรฝ rychlรฝ start pro `omniroute --mcp` a onboarding klienta\n\n
\n๐Ÿง  18. โ€žPotล™ebuji orchestraci A2A se synchronizacรญ a cestami รบloh streamu.โ€œ\n
\n\nPracovnรญ postupy agentลฏ vyลพadujรญ jak pล™รญmรฉ odpovฤ›di, tak dlouhodobรฉ streamovanรฉ provรกdฤ›nรญ s kontrolou ลพivotnรญho cyklu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Koncovรฝ bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamovรกnรญ SSE s ลกรญล™enรญm stavu terminรกlu\n- Rozhranรญ API ลพivotnรญho cyklu รบloh pro `tasks/get` a `tasks/cancel`\n\n
\n๐Ÿ›ฐ๏ธ 19. โ€žPotล™ebuji skuteฤnรฝ stav procesu MCP, ne odhadovanรฝ stav.โ€œ\n
\n\nProvoznรญ tรฝmy potล™ebujรญ vฤ›dฤ›t, zda je MCP skuteฤnฤ› aktivnรญ, nejen zda je API dosaลพitelnรฉ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Soubor bฤ›hovรฉho heartbeatu s PID, ฤasovรฝmi razรญtky, transportem, poฤtem nรกstrojลฏ a reลพimem rozsahu\n- API stavu MCP kombinujรญcรญ prezenฤnรญ signรกl a nedรกvnou aktivitu\n- Karty stavu uลพivatelskรฉho rozhranรญ pro zobrazenรญ aktuรกlnosti procesลฏ/provozuschopnosti/prezenฤnรญho signรกlu\n\n
\n๐Ÿ“‹ 20. โ€žPotล™ebuji auditovatelnรฉ provedenรญ nรกstroje MCPโ€œ\n
\n\nKdyลพ nรกstroje mฤ›nรญ konfiguraci nebo spouลกtฤ›jรญ operaฤnรญ akce, tรฝmy potล™ebujรญ forenznรญ sledovatelnost.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Protokolovรกnรญ auditu pro volรกnรญ nรกstrojลฏ MCP s podporou SQLite\n- Filtruje podle nรกstroje, รบspฤ›chu/neรบspฤ›chu, klรญฤe API a strรกnkovรกnรญ\n- Tabulka auditu dashboardu + koncovรฉ body statistik pro automatizaci\n\n
\n๐Ÿ” 21. โ€žPotล™ebuji omezenรก oprรกvnฤ›nรญ MCP pro kaลพdou integraci.โ€œ\n
\n\nRลฏznรญ klienti by mฤ›li mรญt pล™รญstup ke kategoriรญm nรกstrojลฏ s nejniลพลกรญmi oprรกvnฤ›nรญmi.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- 9 detailnรญch MCP sond pro kontrolovanรฝ pล™รญstup k nรกstrojลฏm\n- Vynucenรญ rozsahu a viditelnost v uลพivatelskรฉm rozhranรญ sprรกvy MCP\n- Bezpeฤnรก vรฝchozรญ poloha pro provoznรญ nรกstroje\n\n
\nโš™๏ธ 22. โ€žPotล™ebuji provoznรญ kontroly bez nutnosti pล™esouvรกnรญโ€œ\n
\n\nTรฝmy potล™ebujรญ rychlรฉ zmฤ›ny v bฤ›hovรฉm prostล™edรญ bฤ›hem incidentลฏ nebo nรกkladovรฝch udรกlostรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Pล™epnฤ›te aktivaci komba pล™รญmo z ล™รญdicรญho panelu MCP\n- Pouลพรญvejte profily odolnosti z pล™eddefinovanรฝch balรญฤkลฏ zรกsad\n- Resetujte stav jistiฤe ze stejnรฉho ovlรกdacรญho panelu\n\n
\n๐Ÿ”„ 23. โ€žPotล™ebuji ลพivรฝ pล™ehled o ลพivotnรญm cyklu รบkolลฏ A2A a jejich zruลกenรญ.โ€œ\n
\n\nBez pล™ehledu o ลพivotnรญm cyklu je obtรญลพnรฉ tล™รญdit incidenty รบkolลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Vรฝpis/filtrovรกnรญ รบkolลฏ podle stรกtu/dovednosti s strรกnkovรกnรญm\n- Podrobnรฝ pล™ehled metadat รบloh, udรกlostรญ a artefaktลฏ\n- Koncovรฝ bod zruลกenรญ รบlohy a akce uลพivatelskรฉho rozhranรญ s potvrzenรญm\n\n
\n๐ŸŒŠ 24. โ€žPotล™ebuji metriky aktivnรญho streamu pro A2A zรกtฤ›ลพโ€œ\n
\n\nStreamovacรญ pracovnรญ postupy vyลพadujรญ provoznรญ pล™ehled o soubฤ›ลพnosti a ลพivรฝch pล™ipojenรญch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- ฤŒรญtaฤe aktivnรญch streamลฏ integrovanรฉ do stavu A2A\n- ฤŒasovรฉ razรญtko poslednรญho รบkolu a poฤty pro jednotlivรฉ stavy\n- Karty A2A dashboardu pro monitorovรกnรญ provozu v reรกlnรฉm ฤase\n\n
\n๐Ÿชช 25. โ€žPotล™ebuji standardnรญ vyhledรกvรกnรญ agentลฏ pro klientyโ€œ\n
\n\nExternรญ klienti a orchestratoล™i potล™ebujรญ pro onboarding strojovฤ› ฤitelnรก metadata.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazenรฉ v uลพivatelskรฉm rozhranรญ pro sprรกvu\n- API pro stav A2A zahrnuje metadata pro zjiลกลฅovรกnรญ pro automatizaci\n\n
\n๐Ÿงญ 26. โ€žPotล™ebuji v uลพivatelskรฉm rozhranรญ produktu zjistitelnost protokolu.โ€œ\n
\n\nPokud uลพivatelรฉ nemohou objevit protokolovรฉ povrchy, kvalita pล™ijetรญ a podpory klesรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Strรกnka Konsolidovanรฉ **koncovรฉ body** s kartami pro koncovรฉ body Proxy, MCP, A2A a API\n- Pล™epรญnรกnรญ stavu inline sluลพby (Online/Offline) pro MCP a A2A\n- Odkazy z pล™ehledu na vyhrazenรฉ karty pro sprรกvu\n\n
\n๐Ÿงช 27. โ€žPotล™ebuji komplexnรญ ovฤ›ล™enรญ protokolu se skuteฤnรฝmi klienty.โ€œ\n
\n\nSimulovanรฉ testy nestaฤรญ k ovฤ›ล™enรญ kompatibility protokolu pล™ed vydรกnรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sada E2E, kterรก spouลกtรญ aplikaci a pouลพรญvรก skuteฤnรฝ transport klienta MCP SDK.\n- Klientskรฉ testy A2A pro toky zjiลกลฅovรกnรญ, odesรญlรกnรญ, streamovรกnรญ, naฤรญtรกnรญ a zruลกenรญ\n- Kล™รญลพovรก kontrola tvrzenรญ oproti API pro audit MCP a รบkoly A2A\n\n
\n๐Ÿ“ก 28. โ€žPotล™ebuji jednotnou pozorovatelnost napล™รญฤ vลกemi rozhranรญmiโ€œ\n
\n\nRozdฤ›lenรญ pozorovatelnosti podle protokolu vytvรกล™รญ slepรก mรญsta a delลกรญ MTTR.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรฉ dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie poลพadavkลฏ napล™รญฤ vrstvami OpenAI, MCP a A2A\n- Provoznรญ API pro stav a automatizaci\n\n
\n๐Ÿ’ผ 29. โ€žPotล™ebuji jeden runtime pro proxy + nรกstroje + orchestraci agentลฏโ€œ\n
\n\nSpouลกtฤ›nรญ mnoha samostatnรฝch sluลพeb zvyลกuje provoznรญ nรกklady a poฤet poruch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Proxy, MCP server a A2A server kompatibilnรญ s OpenAI v jednom balรญฤku\n- Sdรญlenรฉ ovฤ›ล™ovรกnรญ, odolnost, รบloลพiลกtฤ› dat a pozorovatelnost\n- Konzistentnรญ model politik napล™รญฤ vลกemi interakฤnรญmi plochami\n\n
\n๐Ÿš€ 30. โ€žPotล™ebuji agentskรฉ pracovnรญ postupy bez slepenรญ kรณdu.โ€œ\n
\n\nTรฝmy ztrรกcejรญ rychlost pล™i spojovรกnรญ vรญce ad-hoc sluลพeb a skriptลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรก strategie koncovรฝch bodลฏ pro klienty a agenty\n- Vestavฤ›nรก uลพivatelskรก rozhranรญ pro sprรกvu protokolลฏ a cesty pro ovฤ›ล™ovรกnรญ kouล™e\n- Zรกklady pล™ipravenรฉ pro produkฤnรญ prostล™edรญ (zabezpeฤenรญ, protokolovรกnรญ, odolnost, zรกlohovรกnรญ)\n\n### Pล™รญklady hernรญch plรกnลฏ (integrovanรฉ pล™รญpady uลพitรญ)\n\n**Pล™รญruฤka A: Maximalizace placenรฉho pล™edplatnรฉho + levnรฉ zรกlohovรกnรญ**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Pล™รญruฤka B: Kรณdovacรญ stack s nulovรฝmi nรกklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Pล™รญruฤka C: Nonstop zรกloลพnรญ ล™etฤ›zec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Pล™รญruฤka D: Operace agentลฏ s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Zaฤnฤ›te zdarma โ€” Nulovรฉ nรกklady na konfiguraci\n\n> Nastavte si kรณdovรกnรญ s umฤ›lou inteligencรญ bฤ›hem nฤ›kolika minut za **0 $/mฤ›sรญc** . Propojte tyto bezplatnรฉ รบฤty a vyuลพijte vestavฤ›nou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelรฉ odemฤeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Pล™ipojenรญ **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€“ **neomezenฤ›** |\n| 2 | Pล™ipojenรญ k **iFlow** (Google OAuth) | kimi-k2-myลกlenรญ, qwen3-coder-plus, deepseek-r1... โ€” **neomezenฤ›** |\n| 3 | Pล™ipojenรญ **Qwen** (kรณd zaล™รญzenรญ) | qwen3-coder-plus, qwen3-coder-flash... โ€” **neomezenฤ›** |\n| 4 | Pล™ipojenรญ **rozhranรญ pล™รญkazovรฉho ล™รกdku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180 000 GBP/mฤ›sรญc zdarma** |\n| 5 | `/dashboard/combos` โ†’ ล ablona **Free Stack (0 $)** | Automatickรฉ zaล™azenรญ vลกech bezplatnรฝch poskytovatelลฏ do routingu |\n\n**V libovolnรฉm IDE/CLI naveฤte:** `http://localhost:20128/v1` ยท Klรญฤ API: `any-string` ยท Hotovo.\n\n> **Volitelnรฉ doplลˆkovรฉ krytรญ (takรฉ zdarma):** Groq API klรญฤ (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelลฏ), Cerebras (1 milion tok/den).\n\n## โšก Rychlรฝ start\n\n### 1) Nainstalujte a spusลฅte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uลพivatelรฉ pnpm:** Po instalaci spusลฅte `pnpm approve-builds -g` , abyste povolili nativnรญ skripty pro sestavenรญ vyลพadovanรฉ programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard se otevรญrรก na `http://localhost:20128` a zรกkladnรญ URL API je `http://localhost:20128/v1` .\n\n| Pล™รญkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuลกtฤ›nรญ serveru ( `PORT=20128` , API a dashboard na stejnรฉm portu) |\n| `omniroute --port 3000` | Nastavte kanonickรฝ/API port na 3000 |\n| `omniroute --mcp` | Spuลกtฤ›nรญ MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevรญrat prohlรญลพeฤ automaticky |\n| `omniroute --help` | Zobrazit nรกpovฤ›du |\n\nVolitelnรฝ reลพim s rozdฤ›lenรฝm portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Pล™ipojte poskytovatele a vytvoล™te si klรญฤ API\n\n1. Otevล™ete Dashboard โ†’ `Providers` a pล™ipojte alespoลˆ jednoho poskytovatele (klรญฤ OAuth nebo API).\n2. Otevล™ete Dashboard โ†’ `Endpoints` a vytvoล™te API klรญฤ.\n3. (Volitelnรฉ) Otevล™ete Dashboard โ†’ `Combos` a nastavte zรกloลพnรญ ล™etฤ›zec.\n\n### 3) Nasmฤ›rujte svลฏj kรณdovacรญ nรกstroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilnรญmi s OpenAI.\n\n### 4) Povolenรญ a ovฤ›ล™enรญ protokolลฏ (v2.0)\n\n**MCP (pro operace ล™รญzenรฉ nรกstroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak pล™ipojte svรฉho MCP klienta pล™es `stdio` a otestujte nรกstroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovnรญ postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ovฤ›ล™te vลกe od zaฤรกtku do konce (doporuฤeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ovฤ›ล™uje skuteฤnรฉ toky klientลฏ MCP a A2A v porovnรกnรญ se spuลกtฤ›nou aplikacรญ.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute je k dispozici jako veล™ejnรฝ obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlรฝ bฤ›h:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostล™edรญ:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Pouลพรญvรกnรญ Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | ล tรญtek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovฤ›jลกรญ stabilnรญ verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuรกlnรญ verze |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktopovรก aplikace โ€“ offline a vลพdy zapnutรก\n\n> ๐Ÿ†• **NOVINKA!** OmniRoute je nynรญ k dispozici jako **nativnรญ desktopovรก aplikace** pro Windows, macOS a Linux.\n\nSpusลฅte OmniRoute jako samostatnou desktopovou aplikaci โ€“ pro lokรกlnรญ modely nenรญ potล™eba ลพรกdnรฝ terminรกl, prohlรญลพeฤ ani internet. Aplikace zaloลพenรก na platformฤ› Electron obsahuje:\n\n- ๐Ÿ–ฅ๏ธ **Nativnรญ okno** โ€” Vyhrazenรฉ okno aplikace s integracรญ do systรฉmovรฉ liลกty\n- ๐Ÿ”„ **Automatickรฉ spuลกtฤ›nรญ** โ€” Spuลกtฤ›nรญ OmniRoute po pล™ihlรกลกenรญ do systรฉmu\n- ๐Ÿ”” **Nativnรญ oznรกmenรญ** โ€“ Zรญskejte upozornฤ›nรญ na vyฤerpรกnรญ kvรณty nebo problรฉmy s poskytovateli\n- โšก **Instalace jednรญm kliknutรญm** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline reลพim** โ€” Funguje plnฤ› offline s pล™iloลพenรฝm serverem\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systรฉmovรฝ zรกsobnรญk\n\nPo minimalizaci se OmniRoute nachรกzรญ v systรฉmovรฉ liลกtฤ› a nabรญzรญ rychlรฉ akce:\n\n- Otevล™รญt ล™รญdicรญ panel\n- Zmฤ›nit port serveru\n- Ukonฤit aplikaci\n\n๐Ÿ“– รšplnรก dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pล™ehled cen\n\n| รšroveลˆ | Poskytovatel | Nรกklady | Obnovenรญ kvรณty | Nejlepลกรญ pro |\n| --------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **๐Ÿ’ณ Pล˜EDPLATNร‰** | Claude Code (profesionรกl) | 20 dolarลฏ mฤ›sรญฤnฤ› | 5 hodin + tรฝdnฤ› | Jiลพ pล™ihlรกลกen/a k odbฤ›ru |\n| Kodex (Plus/Pro) | 20โ€“200 USD/mฤ›sรญc | 5 hodin + tรฝdnฤ› | Uลพivatelรฉ OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisรญc mฤ›sรญฤnฤ› + 1 tisรญc dennฤ› | Kaลพdรฝ! |\n| GitHub Copilot | 10โ€“19 USD/mฤ›sรญc | Mฤ›sรญฤnรญ | Uลพivatelรฉ GitHubu |\n| **๐Ÿ”‘ KLรฤŒ API** | NVIDIA NIM | **ZDARMA** (vรฝvoj navลพdy) | ~40 ot./min | 70+ otevล™enรฝch modelลฏ |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ na svฤ›tฤ› |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisรญc otรกฤek za minutu | Ultrarychlรก lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | ลฝรกdnรฝ | Nejlepลกรญ zdลฏvodnฤ›nรญ ceny a kvality |\n| xAI Grok-4 Rychlรฝ | **0,20/0,50 USD za 1 milion** ๐Ÿ†• | ลฝรกdnรฝ | Nejrychlejลกรญ + volรกnรญ nรกstroje, ultranรญzkรฉ |\n| xAI Grok-4 (standardnรญ) | 0,20/1,50 USD za 1 milion ๐Ÿ†• | ลฝรกdnรฝ | Vlajkovรก loฤ Reasoning od xAI |\n| Mistral | Zkuลกebnรญ verze zdarma + placenรฉ | Omezenรก sazba | Evropskรก umฤ›lรก inteligence |\n| OpenRouter | Platba za pouลพitรญ | ลฝรกdnรฝ | Vรญce neลพ 100 modelลฏ agregovรกno. |\n| **๐Ÿ’ฐ LEVNร‰** | GLM-5 (pล™es Z.AI) ๐Ÿ†• | 0,5 USD/1 milion | Dennฤ› v 10:00 | Vรฝstup 128 tisรญc obrazovรฝch bodลฏ, nejnovฤ›jลกรญ vlajkovรก loฤ |\n| GLM-4.7 | 0,6 USD/1 milion | Dennฤ› v 10:00 | Zรกloha rozpoฤtu |\n| MiniMax M2.5 ๐Ÿ†• | Vstup 0,3 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | รšvaha + agentnรญ รบkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | Nejlevnฤ›jลกรญ varianta |\n| Kimi K2.5 (Moonshot API) ๐Ÿ†• | Platba za pouลพitรญ | ลฝรกdnรฝ | Pล™รญmรฝ pล™รญstup k Moonshot API |\n| Kimi K2 | 9 dolarลฏ mฤ›sรญฤnฤ› bez zรกvazkลฏ | 10 milionลฏ tokenลฏ/mฤ›sรญc | Pล™edvรญdatelnรฉ nรกklady |\n| **๐Ÿ†“ ZDARMA** | iFlow | **0 dolarลฏ** | Neomezenรฝ | 5 modelลฏ neomezenฤ› |\n| Qwen | **0 dolarลฏ** | Neomezenรฝ | 4 modely neomezenฤ› |\n| Kiro | **0 dolarลฏ** | Neomezenรฝ | Claude Sonnet/Haiku (tvorce AWS) |\n\n> ๐Ÿ†• **Pล™idรกny novรฉ modely (bล™ezen 2026):** ล™ada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkovรกno na 1143 ms โ€“ o 30 % rychlejลกรญ neลพ Gemini 2.5 Flash), GLM-5 pล™es Z.AI s vรฝstupem 128K, uvaลพovรกnรญ MiniMax M2.5, aktualizovanรฉ ceny DeepSeek V3.2, Kimi K2.5 pล™es Moonshot Direct API.\n\n**๐Ÿ’ก Kombinovanรฝ balรญk za 0 $ โ€” Kompletnรญ bezplatnรก instalace:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\niFlow (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Nulovรฉ nรกklady. Nikdy nepล™estรกvejte s kรณdovรกnรญm.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a vลกechny zรกloลพnรญ reลพimy se provede automaticky โ€“ ลพรกdnรฉ ruฤnรญ pล™epรญnรกnรญ.\n\n---\n\n---\n\n## ๐Ÿ†“ Bezplatnรฉ modely โ€“ Co skuteฤnฤ› zรญskรกte\n\n> Vลกechny nรญลพe uvedenรฉ modely jsou **100% zdarma a nevyลพadujรญ ลพรกdnou kreditnรญ kartu** . OmniRoute mezi nimi automaticky propojรญ trasy, kdyลพ dojde jedna kvรณta โ€“ zkombinujte je vลกechny a zรญskejte tak nerozluฤnou kombinaci za 0 dolarลฏ.\n\n### ๐Ÿ”ต CLAUDE MODELS (pล™es Kiro โ€” AWS Builder ID)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-opus-4.6` | `kr/` | **Neomezenรฝ** | Nejnovฤ›jลกรญ opus od Kira |\n\n### ๐ŸŸข MODELY IFLOW (Bezplatnรฉ OAuth โ€” bez nutnosti platit kreditnรญ kartou)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-plus` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `deepseek-r1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `minimax-m2.1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `kimi-k2` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n\n### ๐ŸŸก MODELY QWEN (Ovฤ›ล™enรญ kรณdu zaล™รญzenรญ)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-next` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `vision-model` | `qw/` | **Neomezenรฝ** | Multimodรกlnรญ (obrรกzky) |\n\n### ๐ŸŸฃ Rozhranรญ GEMINI CLI (Google OAuth)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisรญc tok/mฤ›sรญc** + 1 tisรญc/den | Mฤ›sรญฤnรญ reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisรญc mฤ›sรญฤnฤ› (sdรญlenรฝ bazรฉn) | Vysokรก kvalita |\n\n### โšซ NVIDIA NIM (Bezplatnรฝ klรญฤ API โ€” build.nvidia.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vรฝvojรกล™) | ลฝรกdnรฝ limit tokenลฏ | **~40 ot./min** | Vรญce neลพ 70 modelลฏ; pล™echod na ฤistรฉ limity sazeb v polovinฤ› roku 2025 |\n\nOblรญbenรฉ bezplatnรฉ modely: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct` , `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Bezplatnรฝ klรญฤ API โ€” inference.cerebras.ai)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenลฏ/den** | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ inference LLM na svฤ›tฤ›; dennฤ› se resetuje |\n\nDostupnรฉ zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Bezplatnรฝ API klรญฤ โ€” console.groq.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisรญc otรกฤek za minutu** | 30 ot./min na model | ลฝรกdnรก kreditnรญ karta; limit 429, neรบฤtovรกno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **๐Ÿ’ก Ultimรกtnรญ bezplatnรฝ zรกsobnรญk:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> โ†’ iFlow (5 models, unlimited)\n> โ†’ Qwen (4 models, unlimited)\n> โ†’ Gemini CLI (180K/mo)\n> โ†’ Cerebras (1M tok/day)\n> โ†’ Groq (14.4K req/day)\n> โ†’ NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a uลพ nikdy nebudete platit za umฤ›lou inteligenci.\n\n## ๐ŸŽ™๏ธ Kombinovanรก transkripce zdarma\n\n> Pล™episujte libovolnรฉ audio/video za **0 $** โ€“ Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako zรกloลพnรญ nรกstroj, Groq Whisper jako neomezenรก nouzovรก zรกloha.\n\n| Poskytovatel | Bezplatnรฉ kredity | Nejlepลกรญ model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| ๐ŸŸข **Deepgram** | **200 dolarลฏ zdarma** (registrace) | `nova-3` โ€” nejvyลกลกรญ pล™esnost, vรญce neลพ 30 jazykลฏ | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ต **AssemblyAI** | **50 dolarลฏ zdarma** (registrace) | `universal-3-pro` โ€” kapitoly, sentiment, osobnรญ รบdaje | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ด **Groq** | **Navลพdy zdarma** | `whisper-large-v3` โ€” OpenAI ล epot | 30 ot./min (omezenรก rychlost) |\n\n**Navrhovanรก kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nPak v `/dashboard/media` โ†’ zรกloลพka **Pล™epis** : nahrajte libovolnรฝ zvukovรฝ nebo video soubor โ†’ vyberte kombinovanรฝ koncovรฝ bod โ†’ zรญskejte pล™epis v podporovanรฝch formรกtech.\n\n## ๐Ÿ’ก Klรญฤovรฉ vlastnosti\n\nOmniRoute v2.0 je navrลพen jako operaฤnรญ platforma, nikoli pouze jako proxy pro relรฉ.\n\n### ๐Ÿค– Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dฤ›lรก |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (16 nรกstrojลฏ)** | Nรกstroje IDE/agent prostล™ednictvรญm 3 transportลฏ: stdio, SSE ( `/api/mcp/sse` ), Streamovatelnรฝ HTTP ( `/api/mcp/stream` ) |\n| ๐Ÿค **A2A server (JSON-RPC + SSE)** | Spouลกtฤ›nรญ รบloh mezi agenty se synchronizacรญ a streamovรกnรญm |\n| ๐Ÿงญ **Konsolidovanรก strรกnka koncovรฝch bodลฏ** | Strรกnka pro sprรกvu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| ๐ŸŽš๏ธ **Pล™epรญnaฤe pro povolenรญ/zakรกzรกnรญ sluลพby** | Pล™epรญnaฤe ZAP/VYP pro MCP a A2A s trvalรฝm nastavenรญm (vรฝchozรญ: VYP) |\n| ๐Ÿ›ฐ๏ธ **Srdeฤnรญ tep za bฤ›hu MCP** | Skuteฤnรฝ stav procesu (pid, doba provozuschopnosti, stรกล™รญ heartbeatu, transport, reลพim rozsahu) |\n| ๐Ÿ“‹ **Auditnรญ zรกznam MCP** | Filtrovatelnรฉ protokoly auditu s hodnocenรญm รบspฤ›chu/neรบspฤ›chu a klรญฤovรฝm pล™iล™azenรญm |\n| ๐Ÿ” **Vynucovรกnรญ rozsahu MCP** | 9 podrobnรฝch oprรกvnฤ›nรญ pro ล™รญzenรฝ pล™รญstup k nรกstrojลฏm |\n| ๐Ÿ“ก **Sprรกva ลพivotnรญho cyklu รบkolลฏ A2A** | Seznam/filtrovรกnรญ รบloh, kontrola udรกlostรญ/artefaktลฏ, zruลกenรญ spuลกtฤ›nรฝch รบloh |\n| ๐Ÿ“‹ **Objevenรญ karty agenta** | `/.well-known/agent.json` pro automatickรฉ vyhledรกvรกnรญ klientลฏ |\n| ๐Ÿงช **Testovacรญ postroj Protocol E2E** | Skuteฤnรฉ MCP SDK + toky klientลฏ A2A v `test:protocols:e2e` |\n| โš™๏ธ **Provoznรญ kontroly** | Kombinace pล™epรญnaฤลฏ, pouลพitรญ profilลฏ odolnosti, resetovรกnรญ jistiฤลฏ z jednoho ovlรกdacรญho panelu |\n\n### ๐Ÿง  Smฤ›rovรกnรญ a inteligence\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| ๐ŸŽฏ **Inteligentnรญ ฤtyล™รบrovลˆovรฝ zรกloลพnรญ systรฉm** | Automatickรก trasa: Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma |\n| ๐Ÿ“Š **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** | Poฤet tokenลฏ v reรกlnรฉm ฤase + odpoฤet resetovรกnรญ pro kaลพdรฉho poskytovatele |\n| ๐Ÿ”„ **Pล™eklad formรกtu** | OpenAI โ†” Claude โ†” Gemini โ†” Odpovฤ›di s konverzemi bezpeฤnรฝmi pro schรฉma |\n| ๐Ÿ‘ฅ **Podpora vรญce รบฤtลฏ** | Vรญce รบฤtลฏ na poskytovatele s inteligentnรญm vรฝbฤ›rem |\n| ๐Ÿ”„ **Automatickรก aktualizace tokenลฏ** | Tokeny OAuth se automaticky obnovujรญ pล™i opakovanรฉm pokusu. |\n| ๐ŸŽจ **Vlastnรญ kombinace** | 6 vyvaลพovacรญch strategiรญ + ล™รญzenรญ zรกloลพnรญho ล™etฤ›zce |\n| ๐ŸŒ **Smฤ›rovaฤ se zรกstupnรฝmi znaky** | dynamickรฉ smฤ›rovรกnรญ `provider/*` |\n| ๐Ÿง  **Pล™emรฝลกlenรญ o rozpoฤtovรฝch kontrolรกch** | Limity pro prลฏchozรญ, automatickรฉ, vlastnรญ a adaptivnรญ uvaลพovรกnรญ |\n| ๐Ÿ”€ **Aliasy modelลฏ** | Vestavฤ›nรฉ + vlastnรญ aliasovรกnรญ modelลฏ a bezpeฤnost migrace |\n| โšก **Degradace pozadรญ** | Smฤ›rujte รบlohy na pozadรญ s nรญzkou prioritou na levnฤ›jลกรญ modely |\n| ๐Ÿงช **Chytrรฉ smฤ›rovรกnรญ s ohledem na รบkoly** | Automatickรฝ vรฝbฤ›r modelu podle typu obsahu (kรณdovรกnรญ/vize/analรฝza/sumarizace) |\n| ๐Ÿ’ฌ **Vstล™ikovรกnรญ do systรฉmu** | Globรกlnรญ kontroly chovรกnรญ uplatลˆovanรฉ konzistentnฤ› |\n| ๐Ÿ“„ **Kompatibilita API pro odpovฤ›di** | Plnรก podpora `/v1/responses` pro Codex a pokroฤilรฉ agentickรฉ pracovnรญ postupy |\n\n### ๐ŸŽต Multimodรกlnรญ API\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Generovรกnรญ obrรกzkลฏ** | `/v1/images/generations` s cloudovรฝm a lokรกlnรญm backendem |\n| ๐Ÿ“ **Vloลพenรญ** | `/v1/embeddings` pro vyhledรกvรกnรญ a RAG pipelines |\n| ๐ŸŽค **Pล™epis zvuku** | `/v1/audio/transcriptions` (Whisper a dalลกรญ poskytovatelรฉ) |\n| ๐Ÿ”Š **Pล™evod textu na ล™eฤ** | `/v1/audio/speech` (vรญce enginลฏ/poskytovatelลฏ) |\n| ๐ŸŽฌ **Generovรกnรญ videa** | `/v1/videos/generations` (pracovnรญ postupy ComfyUI + SD WebUI) |\n| ๐ŸŽต **Hudebnรญ generace** | `/v1/music/generations` (pracovnรญ postupy ComfyUI) |\n| ๐Ÿ›ก๏ธ **Moderovรกnรญ** | Bezpeฤnostnรญ kontroly `/v1/moderations` |\n| ๐Ÿ”€ **Zmฤ›na poล™adรญ** | `/v1/rerank` pro hodnocenรญ relevance |\n| ๐Ÿ” **Vyhledรกvรกnรญ na webu** ๐Ÿ†• | `/v1/search` โ€” 5 poskytovatelลฏ (Serper, Brave, Perplexity, Exa, Tavily), vรญce neลพ 6 500 zdarma/mฤ›sรญc, automatickรฉ pล™epnutรญ na zรกloลพnรญ systรฉm, mezipamฤ›ลฅ |\n\n### ๐Ÿ›ก๏ธ Odolnost, bezpeฤnost a sprรกva vฤ›cรญ veล™ejnรฝch\n\n| Funkce | Co to dฤ›lรก |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Jistiฤe** | Vypnutรญ/obnovenรญ pro kaลพdรฝ model s ovlรกdรกnรญm prahovรฝch hodnot |\n| ๐ŸŽฏ **Modely s ohledem na koncovรฉ body** | Vlastnรญ modely deklarujรญ podporovanรฉ koncovรฉ body + formรกt API |\n| ๐Ÿ›ก๏ธ **Stรกdo proti hromลฏm** | Ochrana mutexu a semaforu pล™i udรกlostech opakovรกnรญ/rychlosti |\n| ๐Ÿง  **Sรฉmantickรก + podpisovรก mezipamฤ›ลฅ** | Snรญลพenรญ nรกkladลฏ/latence dรญky dvฤ›ma vrstvรกm mezipamฤ›ti |\n| โšก **ลฝรกdost o idempotenci** | Okno ochrany proti duplikacรญm |\n| ๐Ÿ”’ **Falลกovรกnรญ otiskลฏ prstลฏ pomocรญ TLS** | Otisk TLS podobnรฝ prohlรญลพeฤi โ€“ **sniลพuje detekci botลฏ a nahlaลกovรกnรญ รบฤtลฏ** |\n| ๐Ÿ” **Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** | Shoduje se s nativnรญmi podpisy poลพadavkลฏ CLI โ€“ **sniลพuje riziko zablokovรกnรญ a zรกroveลˆ zachovรกvรก IP adresu proxy** |\n| ๐ŸŒ **Filtrovรกnรญ IP adres** | Ovlรกdรกnรญ seznamu povolenรฝch/blokovanรฝch poloลพek pro odhalenรก nasazenรญ |\n| ๐Ÿ“Š **Upravitelnรฉ limity rychlosti** | Konfigurovatelnรฉ globรกlnรญ/na รบrovni poskytovatele limity s perzistencรญ |\n| ๐Ÿ”‘ **Sprรกva klรญฤลฏ API a stanovenรญ rozsahu** | Bezpeฤnรฉ vydรกvรกnรญ/rotace klรญฤลฏ a kontroly modelu/poskytovatele |\n| ๐Ÿ›ก๏ธ **Chrรกnฤ›nรฉ `/models`** | Volitelnรฉ ovฤ›ล™ovรกnรญ a skrytรญ poskytovatele pro katalog modelลฏ |\n\n### ๐Ÿ“Š Pozorovatelnost a analytika\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| ๐Ÿ“ **ลฝรกdost + protokolovรกnรญ proxy** | รšplnรฉ protokolovรกnรญ poลพadavkลฏ/odpovฤ›dรญ a proxy |\n| ๐Ÿ“‹ **Sjednocenรฝ panel protokolลฏ** | Zobrazenรญ poลพadavkลฏ, proxy, auditu a konzole na jednรฉ strรกnce |\n| ๐Ÿ” **Vyลพรกdat si telemetrii** | Latence p50/p95/p99 a trasovรกnรญ poลพadavkลฏ |\n| ๐Ÿฅ **Panel zdravรญ** | Doba provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti |\n| ๐Ÿ’ฐ **Sledovรกnรญ nรกkladลฏ** | Kontrola rozpoฤtu a pล™ehled o cenรกch pro jednotlivรฉ modely |\n| ๐Ÿ“ˆ **Analytickรฉ vizualizace** | Pล™ehledy vyuลพitรญ modelลฏ/poskytovatelลฏ a zobrazenรญ trendลฏ |\n| ๐Ÿงช **Rรกmec hodnocenรญ** | Testovรกnรญ zlatรฉ sady s konfigurovatelnรฝmi strategiemi shody |\n\n### โ˜๏ธ Nasazenรญ a platforma\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| ๐ŸŒ **Nasazenรญ kdekoli** | Localhost, VPS, Docker, cloudovรก prostล™edรญ |\n| ๐Ÿ’พ **Synchronizace s cloudem** | Synchronizace konfigurace pล™es cloud worker |\n| ๐Ÿ”„ **Zรกlohovรกnรญ/Obnovenรญ** | Toky exportu/importu a obnovy po havรกrii |\n| ๐Ÿง™ **Prลฏvodce nรกstupem** | Prลฏvodce prvnรญm spuลกtฤ›nรญm |\n| ๐Ÿ”ง **Panel nรกstrojลฏ CLI** | Nastavenรญ oblรญbenรฝch kรณdovacรญch nรกstrojลฏ jednรญm kliknutรญm |\n| ๐ŸŽฎ **Modelovรฉ hล™iลกtฤ›** | Otestujte libovolnรฉho poskytovatele/model/koncovรฝ bod z ล™รญdicรญho panelu |\n| ๐Ÿ” **Pล™epรญnaฤ otiskลฏ prstลฏ v pล™รญkazovรฉm ล™รกdku** | Porovnรกvรกnรญ otiskลฏ prstลฏ podle poskytovatele v Nastavenรญ > Zabezpeฤenรญ |\n| ๐ŸŒ **i18n (30 jazykลฏ)** | Plnรก jazykovรก podpora dashboardu a dokumentace s psanรญm zprava doleva |\n| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details |\n| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features |\n| ๐Ÿ“‚ **Adresรกล™ vlastnรญch dat** | Pล™epsรกnรญ `DATA_DIR` pro umรญstฤ›nรญ รบloลพiลกtฤ› |\n\n### Hlubokรฝ pohled na funkce\n\n#### Chytrรก zรกloลพnรญ funkce s praktickou kontrolou nรกkladลฏ\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyลพ selลพe kvรณta, rychlost nebo stav, OmniRoute automaticky pล™ejde k dalลกรญmu kandidรกtovi bez nutnosti ruฤnรญho pล™epรญnรกnรญ.\n\n#### Sprรกva protokolลฏ, kterรก je viditelnรก a ovladatelnรก\n\n- MCP + A2A jsou viditelnรฉ v uลพivatelskรฉm rozhranรญ a dokumentaci (nejsou skrytรฉ)\n- API pro stav protokolu zpล™รญstupลˆujรญ ลพivรก provoznรญ data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnujรญ akce pro operace 2. dne (pล™epรญnรกnรญ kombinacรญ, resetovรกnรญ jistiฤลฏ, zruลกenรญ รบkolลฏ)\n\n#### Pracovnรญ postup pล™ekladatele + validace\n\nOblast pล™ekladatele zahrnuje:\n\n- **Hล™iลกtฤ›** : kontroly transformace poลพadavkลฏ\n- **Tester chatu** : kompletnรญ okruลพnรญ cesta poลพadavku/odpovฤ›di\n- **Testovacรญ stolice** : vรญce pล™รญpadลฏ v jednom bฤ›hu\n- **ลฝivรฝ monitor** : zobrazenรญ provozu v reรกlnรฉm ฤase\n\nPlus validace protokolu se skuteฤnรฝmi klienty pomocรญ `npm run test:protocols:e2e` .\n\n> ๐Ÿ“– **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** โ€” Referenฤnรญ informace o nรกstrojรญch, konfigurace IDE a pล™รญklady klientลฏ\n>\n> ๐Ÿ“– **[Soubor README pro A2A Server](src/lib/a2a/README.md)** โ€” Dovednosti, metody JSON-RPC, streamovรกnรญ a ลพivotnรญ cyklus รบloh\n\n## ๐Ÿงช Hodnocenรญ (Evals)\n\nOmniRoute obsahuje vestavฤ›nรฝ hodnotรญcรญ rรกmec pro testovรกnรญ kvality odpovฤ›dรญ LLM v porovnรกnรญ se zlatou sadou. Pล™รญstup k nฤ›mu je moลพnรฝ pล™es **Analรฝzy โ†’ Hodnocenรญ** v dashboardu.\n\n### Vestavฤ›nรก zlatรก sada\n\nPล™edinstalovanรก sada โ€žOmniRoute Golden Setโ€œ obsahuje testovacรญ pล™รญpady pro:\n\n- Zdravรญm, matematika, zemฤ›pis, generovรกnรญ kรณdu\n- Shoda s formรกtem JSON, pล™eklad, generovรกnรญ markdownลฏ\n- Bezpeฤnostnรญ odmรญtnutรญ (ลกkodlivรฝ obsah), poฤรญtรกnรญ, booleovskรก logika\n\n### Strategie hodnocenรญ\n\n| Strategie | Popis | Pล™รญklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Vรฝstup se musรญ pล™esnฤ› shodovat | `\"4\"` |\n| `contains` | Vรฝstup musรญ obsahovat podล™etฤ›zec (bez rozliลกenรญ velkรฝch a malรฝch pรญsmen) | `\"Paris\"` |\n| `regex` | Vรฝstup musรญ odpovรญdat vzoru regulรกrnรญch vรฝrazลฏ | `\"1.*2.*3\"` |\n| `custom` | Vlastnรญ JS funkce vracรญ true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Prลฏvodce nastavenรญm\n\n### Nastavenรญ protokolu (MCP + A2A)\n\n
\n๐Ÿงฉ Nastavenรญ MCP (Model Context Protocol)\n
\n\nSpuลกtฤ›nรญ MCP transportu v reลพimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporuฤenรฝ postup ovฤ›ล™enรญ:\n\n1. Pล™ipojte svรฉho MCP klienta pล™es stdio.\n2. Spusลฅte `omniroute_get_health` .\n3. Spusลฅte `omniroute_list_combos` .\n4. Otevล™ete `/dashboard/mcp` pro ovฤ›ล™enรญ prezenฤnรญho signรกlu, aktivity a auditu.\n\nUลพiteฤnรก API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n๐Ÿค Nastavenรญ A2A (Agent2Agent)\n
\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat รบkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSprรกva ลพivotnรญho cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvoznรญ uลพivatelskรฉ rozhranรญ:\n\n- `/dashboard/a2a` pro pozorovatelnost รบloh/stavลฏ/streamลฏ a akce kouล™enรญ\n\n
\n๐Ÿงช Komplexnรญ validace protokolu\n
\n\nOvฤ›ล™te oba protokoly se skuteฤnรฝmi klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTรญm se ovฤ›ล™uje:\n\n- Pล™ipojenรญ/seznam/volรกnรญ klienta MCP SDK\n- A2A objevovรกnรญ/odesรญlรกnรญ/streamovรกnรญ/zรญskรกvรกnรญ/zruลกenรญ\n- Kล™รญลพovรก kontrola dat v auditu MCP a API pro sprรกvu รบloh A2A\n\n
\n๐Ÿ’ณ Poskytovatelรฉ pล™edplatnรฉho\n
\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionรกly:** Pro sloลพitรฉ รบkoly pouลพรญvejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvรณtu pro kaลพdรฝ model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Sprรกva limitลฏ รบฤtu Codex (5h + tรฝdnฤ›)\n\nKaลพdรฝ รบฤet Codex mรก nynรญ pล™epรญnaฤe zรกsad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinovรฉho prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zรกsadu tรฝdennรญho prahu okna.\n- Prahovรฉ chovรกnรญ: kdyลพ povolenรฉ okno dosรกhne vyuลพitรญ >=90 %, je danรฝ รบฤet pล™eskoฤen.\n- Chovรกnรญ rotace: OmniRoute automaticky pล™esmฤ›ruje na dalลกรญ zpลฏsobilรฝ รบฤet Codex.\n- Chovรกnรญ pล™i resetovรกnรญ: Po `resetAt` urฤitรฉ doby se รบฤet automaticky opฤ›t stane zpลฏsobilรฝm.\n\nScรฉnรกล™e:\n\n- `5h ON` + `Weekly ON` : รบฤet je pล™eskoฤen, kdyลพ kterรฉkoli z oken dosรกhne prahovรฉ hodnoty.\n- `5h OFF` + `Weekly ON` : รบฤet mลฏลพe bรฝt zablokovรกn pouze tรฝdennรญm pouลพรญvรกnรญm.\n- `5h ON` + `Weekly OFF` : รบฤet mลฏลพe bรฝt zablokovรกn pouze pล™i 5hodinovรฉm pouลพรญvรกnรญ.\n- `resetAt` passed: รบฤet se automaticky znovu zapne (bez ruฤnรญho opฤ›tovnรฉho povolenรญ).\n\n### Gemini CLI (ZDARMA 180 000/mฤ›sรญc!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepลกรญ hodnota:** Obrovskรก bezplatnรก รบroveลˆ! Pouลพijte ji pล™ed placenรฝmi รบrovnฤ›mi.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n
\n๐Ÿ”‘ Poskytovatelรฉ klรญฤลฏ API\n
\n\n### NVIDIA NIM (BEZPLATNร pล™รญstup pro vรฝvojรกล™e โ€” vรญce neลพ 70 modelลฏ)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Zรญskejte zdarma klรญฤ API (vฤetnฤ› 1000 inferenฤnรญch kreditลฏ)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ NVIDIA NIM:\n - Klรญฤ API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a vรญce neลพ 50 dalลกรญch\n\n**Tip pro profesionรกly:** API kompatibilnรญ s OpenAI โ€“ funguje bez problรฉmลฏ s pล™ekladem formรกtลฏ OmniRoute!\n\n### Hlubokรฉ vyhledรกvรกnรญ\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatnรก รบroveลˆ!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Zรญskejte klรญฤ API (vฤetnฤ› bezplatnรฉ รบrovnฤ›)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionรกly:** Ultrarychlรก inference โ€“ nejlepลกรญ pro kรณdovรกnรญ v reรกlnรฉm ฤase!\n\n### OpenRouter (100+ modelลฏ)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ OpenRouter\n\n**Modely:** Zรญskejte pล™รญstup k vรญce neลพ 100 modelลฏm od vลกech hlavnรญch poskytovatelลฏ prostล™ednictvรญm jedinรฉho klรญฤe API.\n\n
\n๐Ÿ’ฐ Levnรญ poskytovatelรฉ (zรกloลพnรญ)\n
\n\n### GLM-4.7 (Dennรญ reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Zรญskejte klรญฤ API z kรณdovacรญho plรกnu\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API:\n - Poskytovatel: `glm`\n - Klรญฤ API: `your-key`\n\n**Pouลพitรญ:** `glm/glm-4.7`\n\n**Tip pro profesionรกly:** Programovacรญ plรกn nabรญzรญ 3ร— kvรณtu za cenu 1/7! Obnovuje se dennฤ› v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionรกly:** Nejlevnฤ›jลกรญ varianta pro dlouhรฝ kontext (1 milion tokenลฏ)!\n\n### Kimi K2 (pauลกรกlnรญ poplatek 9 dolarลฏ mฤ›sรญฤnฤ›)\n\n1. Odebรญrat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `kimi/kimi-latest`\n\n**Tip pro profesionรกly:** Fixnรญch 9 $/mฤ›sรญc za 10 milionลฏ tokenลฏ = efektivnรญ nรกklady 0,90 $/1 milion!\n\n
\n๐Ÿ†“ BEZPLATNร poskytovatelรฉ (nouzovรฉ zรกlohovรกnรญ)\n
\n\n### iFlow (5 BEZPLATNรCH modelลฏ pล™es OAuth)\n\n```bash\nDashboard โ†’ Connect iFlow\nโ†’ iFlow OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kรณdem zaล™รญzenรญ)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n๐ŸŽจ Vytvoล™te kombinace\n
\n\n### Pล™รญklad 1: Maximalizace pล™edplatnรฉho โ†’ Levnรฉ zรกlohovรกnรญ\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Pล™รญklad 2: Pouze zdarma (nulovรฉ nรกklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n๐Ÿ”ง Integrace s rozhranรญm pล™รญkazovรฉho ล™รกdku\n
\n\n### IDE kurzoru\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jednรญm kliknutรญm pouลพijte strรกnku **Nรกstroje CLI** na ล™รญdicรญm panelu nebo ruฤnฤ› upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Moลพnost 1 โ€“ Dashboard (doporuฤeno):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Moลพnost 2 โ€“ Manuรกlnรญ รบprava:** รšprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznรกmka:** OpenClaw funguje pouze s lokรกlnรญm OmniRoute. Mรญsto `localhost` pouลพijte `127.0.0.1` , abyste se vyhnuli problรฉmลฏm s rozliลกenรญm IPv6.\n\n### Cline / Pokraฤovat / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Pล™idรกnรญ OmniRoute jako vlastnรญho poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvoล™te/upravte `opencode.json` v koล™enovรฉm adresรกล™i projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` pล™idejte jakรฝkoli model dostupnรฝ ve vaลกem koncovรฉm bodu OmniRoute `/v1/models` . Pouลพijte formรกt `provider/model-id` z vaลกeho dashboardu OmniRoute.\n\n---\n\n## ๐Ÿ› ล˜eลกenรญ problรฉmลฏ\n\n
\nKliknutรญm rozbalรญte prลฏvodce ล™eลกenรญm problรฉmลฏ\n
\n\n**\"Jazykovรฝ model neposkytoval zprรกvy\"**\n\n- Kvรณta poskytovatele vyฤerpรกna โ†’ Zkontrolujte sledovรกnรญ kvรณt na ล™รญdicรญm panelu\n- ล˜eลกenรญ: Pouลพijte zรกloลพnรญ kombinovanou variantu nebo pล™ejdฤ›te na levnฤ›jลกรญ รบroveลˆ\n\n**Omezenรญ rychlosti**\n\n- Kvรณta pล™edplatnรฉho vyฤerpรกna โ†’ Pล™echod na GLM/MiniMax\n- Pล™idat kombo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vyprลกela**\n\n- Automaticky aktualizovรกno sluลพbou OmniRoute\n- Pokud problรฉmy pล™etrvรกvajรญ: Ovlรกdacรญ panel โ†’ Poskytovatel โ†’ Znovu pล™ipojit\n\n**Vysokรฉ nรกklady**\n\n- Zkontrolujte statistiky vyuลพitรญ v sekci Nรกstฤ›nka โ†’ Nรกklady\n- Pล™epnout primรกrnรญ model na GLM/MiniMax\n- Pro nekritickรฉ รบlohy pouลพijte bezplatnou รบroveลˆ (Gemini CLI, iFlow).\n\n**Porty ล™รญdicรญho panelu/API jsou nesprรกvnรฉ**\n\n- `PORT` je kanonickรฝ zรกkladnรญ port (a standardnฤ› port API)\n- `API_PORT` pล™episuje pouze posluchaฤ API kompatibilnรญ s OpenAI.\n- `DASHBOARD_PORT` pล™episuje pouze posluchaฤ dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaลกi veล™ejnou URL adresu ล™รญdicรญho panelu (pro zpฤ›tnรก volรกnรญ OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ovฤ›ล™te, zda `BASE_URL` odkazuje na vaลกi spuลกtฤ›nou instanci.\n- Ovฤ›ล™te, zda `CLOUD_URL` odkazuje na vรกลก oฤekรกvanรฝ cloudovรฝ koncovรฝ bod.\n- Udrลพujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na stranฤ› serveru.\n\n**Prvnรญ pล™ihlรกลกenรญ nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud nenรญ nastaveno, zรกloลพnรญ heslo je `123456`\n\n**ลฝรกdnรฉ protokoly poลพadavkลฏ**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test pล™ipojenรญ ukazuje โ€žNeplatnรฉโ€œ pro poskytovatele kompatibilnรญ s OpenAI**\n\n- Mnoho poskytovatelลฏ nezpล™รญstupลˆuje koncovรฝ bod `/models`\n- OmniRoute v1.0.6+ zahrnuje zรกloลพnรญ ovฤ›ล™enรญ pomocรญ dokonฤenรญ chatu\n- Zajistฤ›te, aby zรกkladnรญ URL adresa obsahovala pล™รญponu `/v1`\n\n### ๐Ÿ” OAuth na vzdรกlenรฉm serveru\n\n\n\n\n> **โš ๏ธ Dลฏleลพitรฉ pro uลพivatele, kteล™รญ provozujรญ OmniRoute na VPS, Dockeru nebo jakรฉmkoli vzdรกlenรฉm serveru**\n\n#### Proฤ selhรกvรก OAuth v rozhranรญ CLI Antigravity / Gemini na vzdรกlenรฝch serverech?\n\nPoskytovatelรฉ rozhranรญ CLI **Antigravity** a **Gemini** pouลพรญvajรญ **Google OAuth 2.0** . Google vyลพaduje, aby se `redirect_uri` v toku OAuth pล™esnฤ› shodoval s jednรญm z pล™edregistrovanรฝch URI v konzoli Google Cloud Console aplikace.\n\nPล™ihlaลกovacรญ รบdaje OAuth, kterรฉ jsou souฤรกstรญ OmniRoute, jsou registrovรกny **pouze pro `localhost`** . Kdyลพ pล™istupujete k OmniRoute na vzdรกlenรฉm serveru (napล™. `https://omniroute.myserver.com` ), Google odmรญtne ovฤ›ล™enรญ pomocรญ:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### ล˜eลกenรญ: Nakonfigurujte si vlastnรญ pล™ihlaลกovacรญ รบdaje OAuth\n\nV Google Cloud Console je potล™eba vytvoล™it **ID klienta OAuth 2.0** s URI vaลกeho serveru.\n\n#### Krok za krokem\n\n**1. Otevล™ete konzoli Google Cloud**\n\nPล™ejdฤ›te na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvoล™te novรฉ ID klienta OAuth 2.0**\n\n- Kliknฤ›te na **โ€ž+ Vytvoล™it pล™ihlaลกovacรญ รบdajeโ€œ** โ†’ **โ€žID klienta OAuthโ€œ**\n- Typ aplikace: **โ€žWebovรก aplikaceโ€œ**\n- Nรกzev: cokoli chcete (napล™. `OmniRoute Remote` )\n\n**3. Pล™idejte autorizovanรฉ URI pro pล™esmฤ›rovรกnรญ**\n\nDo pole **โ€žAutorizovanรฉ identifikรกtory URI pro pล™esmฤ›rovรกnรญโ€œ** pล™idejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraฤte `your-server.com` domรฉnou nebo IP adresou vaลกeho serveru (v pล™รญpadฤ› potล™eby uveฤte i port, napล™. `http://45.33.32.156:20128/callback` ).\n\n**4. Uloลพte a zkopรญrujte pล™ihlaลกovacรญ รบdaje**\n\nPo vytvoล™enรญ Google zobrazรญ **ID klienta** a **tajnรฝ kรณd klienta** .\n\n**5. Nastavenรญ promฤ›nnรฝch prostล™edรญ**\n\nVe vaลกem souboru `.env` (nebo promฤ›nnรฝch prostล™edรญ Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu pล™ipojit**\n\nล˜รญdicรญ panel โ†’ Poskytovatelรฉ โ†’ Antigravity (nebo Gemini CLI) โ†’ OAuth\n\nGoogle nynรญ bude sprรกvnฤ› pล™esmฤ›rovรกvat na `https://your-server.com/callback` .\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nPokud si teฤ nechcete nastavovat vlastnรญ pล™ihlaลกovacรญ รบdaje, mลฏลพete stรกle pouลพรญt **ruฤnรญ postup pro URL** :\n\n1. OmniRoute otevรญrรก autorizaฤnรญ URL od Googlu\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru).\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe (i kdyลพ se strรกnka nenaฤte)\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute.\n5. Kliknฤ›te na **โ€žPล™ipojitโ€œ**\n\n> To funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na to, zda se naฤetla pล™esmฤ›rovacรญ strรกnka.\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nChcete-li zรญskat pล™รญstup k pล™ihlaลกovacรญm รบdajลฏm bez vlastnรญ konfigurace, mลฏลพete pouลพรญt nรกsledujรญcรญ postup:\n\n1. OmniRoute otevล™e URL autorizace Google\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru)\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute\n5. Kliknฤ›te na **โ€žPล™ipojit\"**\n\n> Toto ล™eลกenรญ funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na naฤtenรญ pล™esmฤ›rovacรญ strรกnky.\n\n---\n\n## ๐Ÿ› ๏ธ Technologickรฝ stack\n\n
\nKliknutรญm rozbalรญte podrobnosti o technologickรฉm stacku\n
\n\n- **Runtime** : Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ **nenรญ podporovรกn** โ€” nativnรญ binรกrnรญ soubory `better-sqlite3` jsou nekompatibilnรญ)\n- **Jazyk** : TypeScript 5.9 โ€” **100% TypeScript** napล™รญฤ `src/` a `open-sse/` ( `any` v zรกkladnรญch modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databรกze** : LowDB (JSON) + SQLite (stav domรฉny + protokoly proxy + audit MCP + rozhodnutรญ o smฤ›rovรกnรญ)\n- **Schรฉmata** : Zod (validace I/O nรกstrojลฏ MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamovรกnรญ** : Udรกlosti odeslanรฉ serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klรญฤe + autorizace s rozsahem MCP\n- **Testovรกnรญ** : Node.js test runner + Vitest (900+ testลฏ vฤetnฤ› unit, integraฤnรญch, E2E)\n- **CI/CD** : Akce GitHubu (automatickรฉ publikovรกnรญ v npm + Docker Hub pล™i vydรกnรญ)\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **Balรญฤek** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistiฤ, exponenciรกlnรญ odstavenรญ, ochrana proti hromลฏm, faleลกnรฉ TLS, automatickรฉ kombinovanรฉ samoopravovรกnรญ\n\n---\n\n## ๐Ÿ“– Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uลพivatelskรก pล™รญruฤka](docs/USER_GUIDE.md) | Poskytovatelรฉ, kombinace, integrace CLI, nasazenรญ |\n| [Referenฤnรญ informace k API](docs/API_REFERENCE.md) | Vลกechny koncovรฉ body s pล™รญklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nรกstrojลฏ MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamovรกnรญ, sprรกva รบloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorovรฉ bodovรกnรญ, balรญฤky reลพimลฏ, samolรฉฤba |\n| [Odstraลˆovรกnรญ problรฉmลฏ](docs/TROUBLESHOOTING.md) | Bฤ›ลพnรฉ problรฉmy a jejich ล™eลกenรญ |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a internรญ prvky systรฉmu |\n| [Pล™ispรญvรกnรญ](CONTRIBUTING.md) | Nastavenรญ a pokyny pro vรฝvoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpeฤnostnรญ zรกsady](SECURITY.md) | Hlรกลกenรญ zranitelnostรญ a bezpeฤnostnรญ postupy |\n| [Nasazenรญ virtuรกlnรญho poฤรญtaฤe](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletnรญ prลฏvodce: Nastavenรญ virtuรกlnรญho poฤรญtaฤe + nginx + Cloudflare |\n| [Galerie funkcรญ](docs/FEATURES.md) | Vizuรกlnรญ prohlรญdka ล™รญdicรญho panelu se snรญmky obrazovky |\n| [Kontrolnรญ seznam vydรกnรญ](docs/RELEASE_CHECKLIST.md) | Kroky ovฤ›ล™enรญ pล™ed vydรกnรญm |\n\n---\n\n## ๐Ÿ—บ๏ธ Plรกn\n\nOmniRoute mรก **v plรกnu vรญce neลพ 210 funkcรญ** v nฤ›kolika fรกzรญch vรฝvoje. Zde jsou klรญฤovรฉ oblasti:\n\n| Kategorie | Plรกnovanรฉ funkce | Hlavnรญ body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| ๐Ÿง  **Smฤ›rovรกnรญ a inteligence** | 25+ | Smฤ›rovรกnรญ s nejniลพลกรญ latencรญ, smฤ›rovรกnรญ zaloลพenรฉ na tagech, kontrola kvรณt pล™ed vรฝstupem, vรฝbฤ›r รบฤtu P2C |\n| ๐Ÿ”’ **Zabezpeฤenรญ a dodrลพovรกnรญ pล™edpisลฏ** | 20+ | Zpevnฤ›nรญ SSRF, maskovรกnรญ pล™ihlaลกovacรญch รบdajลฏ, limit rychlosti pro kaลพdรฝ koncovรฝ bod, stanovenรญ rozsahu klรญฤลฏ pro sprรกvu |\n| ๐Ÿ“Š **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledovรกnรญ kvรณt v reรกlnรฉm ฤase, sledovรกnรญ nรกkladลฏ podle modelu |\n| ๐Ÿ”„ **Integrace poskytovatelลฏ** | 20+ | Dynamickรฝ registr modelลฏ, doba zchlazenรญ poskytovatelลฏ, Codex pro vรญce รบฤtลฏ, analรฝza kvรณt Copilota |\n| โšก **Vรฝkon** | 15+ | Dvojitรก vrstva mezipamฤ›ti, mezipamฤ›ลฅ vรฝzev, mezipamฤ›ลฅ odpovฤ›dรญ, udrลพovรกnรญ streamovรกnรญ, dรกvkovรฉ API |\n| ๐ŸŒ **Ekosystรฉm** | 10+ | WebSocket API, horkรฉ opฤ›tovnรฉ naฤรญtรกnรญ konfigurace, distribuovanรฉ รบloลพiลกtฤ› konfigurace, komerฤnรญ reลพim |\n\n### ๐Ÿ”œ Jiลพ brzy\n\n- ๐Ÿ”— **Integrace OpenCode** โ€” Nativnรญ podpora poskytovatelลฏ pro IDE kรณdovรกnรญ s AI v OpenCode\n- ๐Ÿ”— **Integrace TRAE** โ€” Plnรก podpora vรฝvojovรฉho rรกmce TRAE pro umฤ›lou inteligenci\n- ๐Ÿ“ฆ **Dรกvkovรฉ API** โ€” Asynchronnรญ dรกvkovรฉ zpracovรกnรญ hromadnรฝch poลพadavkลฏ\n- ๐ŸŽฏ **Smฤ›rovรกnรญ na zรกkladฤ› tagลฏ** โ€” Smฤ›rovรกnรญ poลพadavkลฏ na zรกkladฤ› vlastnรญch tagลฏ a metadat\n- ๐Ÿ’ฐ **Strategie nejniลพลกรญch nรกkladลฏ** โ€“ Automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n> ๐Ÿ“ รšplnรฉ specifikace funkcรญ jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobnรฝch specifikacรญ)\n\n---\n\n## ๐Ÿ‘ฅ Pล™ispฤ›vatelรฉ\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Pล™ispฤ›vatelรฉ](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak pล™ispฤ›t\n\n1. Vytvoล™enรญ forku repozitรกล™e\n2. Vytvoล™te si vlastnรญ vฤ›tev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrฤte zmฤ›ny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do vฤ›tve ( `git push origin feature/amazing-feature` )\n5. Otevล™รญt ลพรกdost o zmฤ›ny (pull request)\n\nPodrobnรฉ pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydรกnรญ novรฉ verze\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Hvฤ›zdnรก historie\n\n## Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## ๐Ÿ™ Podฤ›kovรกnรญ\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** โ€“ pลฏvodnรญmu projektu, kterรฝ inspiroval tento fork. OmniRoute stavรญ na tomto neuvฤ›ล™itelnรฉm zรกkladu s dalลกรญmi funkcemi, multimodรกlnรญmi API a kompletnรญm pล™epsรกnรญm TypeScriptu.\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€“ pลฏvodnรญ implementaci Go, kterรก inspirovala tento JavaScriptovรฝ port.\n\n---\n\n## ๐Ÿ“„ Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n
\n Vytvoล™eno s โค๏ธ pro vรฝvojรกล™e, kteล™รญ programujรญ 24 hodin dennฤ›, 7 dnรญ v tรฝdnu\n
\n

omniroute.online

\n
\n\n"}, "88705bb6e97969fa101d0a49fa035a791a5e3bdb": {"t": 1785764466.182805, "n": 91323, "h": "843e088bf02ee23c", "c": "# ๐Ÿš€ OmniRoute โ€” Bezplatnรก brรกna umฤ›lรฉ inteligence\n\n### Nikdy nepล™estรกvejte s kรณdovรกnรญm. Chytrรฉ smฤ›rovรกnรญ k **BEZPLATNรM a levnรฝm modelลฏm AI** s automatickรฝm pล™epรญnรกnรญm mezi zรกloลพnรญmi systรฉmy.\n\n_Vรกลก univerzรกlnรญ API proxy โ€“ jeden endpoint, vรญce neลพ 44 poskytovatelลฏ, nulovรฉ vรฝpadky. Nynรญ s orchestracรญ agentลฏ **MCP a A2A** ._\n\n**Dokonฤenรญ chatu โ€ข Vklรกdรกnรญ โ€ข Generovรกnรญ obrรกzkลฏ โ€ข Video โ€ข Hudba โ€ข Audio โ€ข Zmฤ›na poล™adรญ โ€ข **Vyhledรกvรกnรญ na webu** โ€ข MCP server โ€ข A2A protokol โ€ข 100% TypeScript**\n\n---\n\n
\n
\n

\"verze\"Docker\"Licence\"\"Webovรฉ\"WhatsApp\"

\n

๐ŸŒ Webovรฉ strรกnky โ€ข ๐Ÿš€ Rychlรฝ start โ€ข ๐Ÿ’ก Funkce โ€ข ๐Ÿ“– Dokumentace โ€ข ๐Ÿ’ฐ Cenรญk โ€ข ๐Ÿ’ฌ WhatsApp

\n
\n\n๐ŸŒ **Dostupnรฉ v:** ๐Ÿ‡บ๐Ÿ‡ธ [Angliฤtina](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n### ๐Ÿ†• What's New in v3.0.0\n\n| Area | Change |\n| --- | --- |\n| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| โœ… **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |\n| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| ๐ŸŒ **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| ๐Ÿ”ง **926 Tests** | Full test suite passes with 0 failures |\n\n\n\n### ๐Ÿ†• What's New in v3.0.0\n\n| Area | Change |\n| --- | --- |\n| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| โœ… **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |\n| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| ๐ŸŒ **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| ๐Ÿ”ง **926 Tests** | Full test suite passes with 0 failures |\n\n---\n\n\n\n## ๐Ÿ–ผ๏ธ Hlavnรญ ovlรกdacรญ panel\n\n
\"ล˜รญdicรญ
\n\n---\n\n## ๐Ÿ“ธ Nรกhled ล™รญdicรญho panelu\n\n
\nKliknutรญm zobrazรญte snรญmky obrazovky z ล™รญdicรญho panelu\n
\n\n| Strana | Snรญmek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelรฉ** | ![Poskytovatelรฉ](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdravรญ** | ![Zdravรญ](docs/screenshots/04-health.png) |\n| **Pล™ekladatel** | ![Pล™ekladatel](docs/screenshots/05-translator.png) |\n| **Nastavenรญ** | ![Nastavenรญ](docs/screenshots/06-settings.png) |\n| **Nรกstroje CLI** | ![Nรกstroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly pouลพรญvรกnรญ** | ![Pouลพรญvรกnรญ](docs/screenshots/08-usage.png) |\n| **Koncovรฉ body** | ![Koncovรฉ body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### ๐Ÿค– Bezplatnรฝ poskytovatel umฤ›lรฉ inteligence pro vaลกe oblรญbenรฉ programรกtory\n\n_Pล™ipojte libovolnรฝ nรกstroj IDE nebo CLI s umฤ›lou inteligencรญ pล™es OmniRoute โ€” bezplatnou API brรกnu pro neomezenรฉ kรณdovรกnรญ._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\"OpenClaw\"
OpenClaw
โญ 205 tisรญc 		\"NanoBot\"
NanoBot
โญ 20,9 tisรญc 		\"PicoClaw\"
PicoClaw
โญ 14,6 tisรญc 		\"ZeroClaw\"
ZeroClaw
โญ 9,9 tisรญc 		\"ลฝeleznรฝ
ลฝeleznรฝ drรกp
โญ 2,1 tisรญce
\"OpenCode\"
OpenCode
โญ 106 tisรญc 		\"Codex
Codex CLI
โญ 60,8 tisรญc 		\"Claude
Claude Code
โญ 67,3 tisรญc 		\"Gemini
Gemini CLI
โญ 94,7 tisรญc 		\"Kilo
Kilo kรณd
โญ 15,5 tisรญc
\n\n๐Ÿ“ก Vลกichni agenti se pล™ipojujรญ pล™es http://localhost:20128/v1 nebo http://cloud.omniroute.online/v1 โ€” jedna konfigurace, neomezenรฉ modely a kvรณty\n\n---\n\n## ๐Ÿค” Proฤ OmniRoute?\n\n**Pล™estaลˆte plรฝtvat penฤ›zi a narรกลพet na limity:**\n\n- Kvรณta pล™edplatnรฉho vyprลกรญ kaลพdรฝ mฤ›sรญc\n- Limity rychlosti vรกm zabrรกnรญ v kรณdovรกnรญ\n- Drahรก API (20โ€“50 USD/mฤ›sรญc na poskytovatele)\n- Ruฤnรญ pล™epรญnรกnรญ mezi poskytovateli\n\n**OmniRoute to ล™eลกรญ:**\n\n- โœ… **Maximalizujte pล™edplatnรฉ** โ€“ Sledujte kvรณtu, vyuลพijte kaลพdou ฤรกstku pล™ed resetovรกnรญm\n- โœ… **Automatickรฉ zรกloลพnรญ** โ€“ Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma, ลพรกdnรฉ vรฝpadky\n- โœ… **Vรญce รบฤtลฏ** โ€“ Round-robin mezi รบฤty u jednotlivรฝch poskytovatelลฏ\n- โœ… **Univerzรกlnรญ** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakรฝmkoli nรกstrojem CLI\n\n---\n\n## ๐Ÿ“ง Podpora\n\n> ๐Ÿ’ฌ **Pล™idejte se k naลกรญ komunitฤ›!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Zรญskejte pomoc, sdรญlejte tipy a buฤte v obraze.\n\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problรฉmy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitnรญ skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Pล™ispรญvรกnรญ** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevล™ete ลพรกdost o pล™รญspฤ›vek nebo si vyberte `good first issue`\n- **Pลฏvodnรญ projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Hlรกsรญte chybu?\n\nPล™i otevรญrรกnรญ problรฉmu spusลฅte pล™รญkaz system-info a pล™iloลพte vygenerovanรฝ soubor:\n\n```bash\nnpm run system-info\n```\n\nTรญm se vygeneruje soubor `system-info.txt` s verzรญ Node.js, verzรญ OmniRoute, podrobnostmi o operaฤnรญm systรฉmu, nainstalovanรฝmi nรกstroji CLI (iflow, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systรฉmovรฝmi balรญฤky โ€“ vลกe, co potล™ebujeme k rychlรฉ reprodukci vaลกeho problรฉmu. Soubor pล™iloลพte pล™รญmo k vaลกemu problรฉmu na GitHubu.\n\n---\n\n## ๐Ÿ”„ Jak to funguje\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ Co ล™eลกรญ OmniRoute โ€” 30 skuteฤnรฝch problรฉmลฏ a pล™รญpadลฏ pouลพitรญ\n\n> **Kaลพdรฝ vรฝvojรกล™ pouลพรญvajรญcรญ nรกstroje umฤ›lรฉ inteligence se s tฤ›mito problรฉmy setkรกvรก dennฤ›.** OmniRoute byl vytvoล™en tak, aby je vลกechny vyล™eลกil โ€“ od pล™ekroฤenรญ nรกkladลฏ po regionรกlnรญ bloky, od nefunkฤnรญch tokลฏ OAuth aลพ po operace s protokoly a sledovatelnost v podniku.\n\n
\n๐Ÿ’ธ 1. โ€žPlatรญm si drahรฉ pล™edplatnรฉ, ale stรกle mฤ› ruลกรญ limityโ€œ\n
\n\nVรฝvojรกล™i platรญ za Claude Pro, Codex Pro nebo GitHub Copilot 20โ€“200 dolarลฏ mฤ›sรญฤnฤ›. I pล™i platbฤ› mรก kvรณta strop โ€“ 5 hodin pouลพรญvรกnรญ, tรฝdennรญ limity nebo limity rychlosti za minutu. Uprostล™ed kรณdovacรญ relace poskytovatel pล™estane reagovat a vรฝvojรกล™ ztrรกcรญ plynulost a produktivitu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Inteligentnรญ ฤtyล™รบrovลˆovรก zรกloลพnรญ sluลพba** โ€“ Pokud dojde kvรณta pล™edplatnรฉho, โ€‹โ€‹automaticky se pล™esmฤ›ruje na API klรญฤ โ†’ Levnรฉ โ†’ Zdarma bez manuรกlnรญho zรกsahu\n- **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** โ€“ Zobrazuje spotล™ebu tokenลฏ v reรกlnรฉm ฤase s odpoฤรญtรกvรกnรญm resetovรกnรญ (5 hodin, dennฤ›, tรฝdnฤ›)\n- **Podpora vรญce รบฤtลฏ** โ€“ Vรญce รบฤtลฏ u jednoho poskytovatele s automatickรฝm pล™epรญnรกnรญm โ€“ kdyลพ jeden dojde, pล™epne se na dalลกรญ\n- **Vlastnรญ kombinace** โ€” Pล™izpลฏsobitelnรฉ zรกloลพnรญ ล™etฤ›zce se 6 strategiemi vyvaลพovรกnรญ (fill-first, round robin, P2C, nรกhodnรฉ, nejmรฉnฤ› pouลพรญvanรฉ, nรกkladovฤ› optimalizovanรฉ)\n- **Codex Business Quotas** โ€” Sledovรกnรญ kvรณt pracovnรญho prostoru firmy/tรฝmu pล™รญmo v dashboardu\n\n
\n๐Ÿ”Œ 2. โ€žPotล™ebuji pouลพรญt vรญce poskytovatelลฏ, ale kaลพdรฝ mรก jinรฉ APIโ€œ\n
\n\nOpenAI pouลพรญvรก jeden formรกt, Claude (Anthropic) jinรฝ a Gemini jeลกtฤ› tล™etรญ. Pokud chce vรฝvojรกล™ testovat modely od rลฏznรฝch poskytovatelลฏ nebo mezi nimi pล™echรกzet, musรญ pล™ekonfigurovat SDK, zmฤ›nit koncovรฉ body a vypoล™รกdat se s nekompatibilnรญmi formรกty. Vlastnรญ poskytovatelรฉ (FriendLI, NIM) majรญ nestandardnรญ koncovรฉ body modelลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sjednocenรฝ koncovรฝ bod** โ€” Jeden `http://localhost:20128/v1` slouลพรญ jako proxy pro vลกech 67+ poskytovatelลฏ.\n- **Pล™eklad formรกtu** โ€” Automatickรฝ a transparentnรญ: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Sanitizace odpovฤ›dรญ** โ€” Odstraลˆuje nestandardnรญ pole ( `x_groq` , `usage_breakdown` , `service_tier` ), kterรก poruลกujรญ OpenAI SDK v1.83+\n- **Normalizace rolรญ** โ€” Pล™evรกdรญ `developer` โ†’ `system` pro poskytovatele bez OpenAI; `system` โ†’ `user` pro GLM/ERNIE\n- **Extrakce tagลฏ Think** โ€” Extrahuje bloky `` z modelลฏ, jako je DeepSeek R1, do standardizovanรฉho `reasoning_content`\n- **Strukturovanรฝ vรฝstup pro Gemini** โ€” `json_schema` โ†’ automatickรก konverze `responseMimeType` / `responseSchema`\n- **Vรฝchozรญ hodnota `stream` je `false`** โ€“ Odpovรญdรก specifikaci OpenAI, ฤรญmลพ se zabrรกnรญ neoฤekรกvanรฉmu SSE v Python/Rust/Go SDK.\n\n
\n๐ŸŒ 3. โ€žMลฏj poskytovatel AI blokuje mลฏj region/zemiโ€œ\n
\n\nPoskytovatelรฉ jako OpenAI/Codex blokujรญ pล™รญstup z urฤitรฝch geografickรฝch oblastรญ. Uลพivatelรฉ se bฤ›hem pล™ipojenรญ OAuth a API dostรกvajรญ k chybรกm jako `unsupported_country_region_territory` . To je obzvlรกลกtฤ› frustrujรญcรญ pro vรฝvojรกล™e z rozvojovรฝch zemรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **3รบrovลˆovรก konfigurace proxy** โ€“ Konfigurovatelnรก proxy na 3 รบrovnรญch: globรกlnรญ (veลกkerรฝ provoz), pro jednotlivรฉ poskytovatele (pouze jeden poskytovatel) a pro jednotlivรฉ pล™ipojenรญ/klรญฤ\n- **Barevnฤ› kรณdovanรฉ odznaky proxy** โ€“ Vizuรกlnรญ indikรกtory: ๐ŸŸข globรกlnรญ proxy, ๐ŸŸก proxy poskytovatele, ๐Ÿ”ต proxy pล™ipojenรญ, vลพdy zobrazujรญcรญ IP adresu\n- **Vรฝmฤ›na tokenลฏ OAuth prostล™ednictvรญm proxy** โ€“ tok OAuth takรฉ prochรกzรญ pล™es proxy, ฤรญmลพ se ล™eลกรญ `unsupported_country_region_territory`\n- **Testy pล™ipojenรญ pล™es proxy** โ€“ Testy pล™ipojenรญ pouลพรญvajรญ nakonfigurovanรฝ proxy (jiลพ ลพรกdnรฉ pล™รญmรฉ obchรกzenรญ)\n- **Podpora SOCKS5** โ€” Plnรก podpora proxy SOCKS5 pro odchozรญ smฤ›rovรกnรญ\n- **TLS Fingerprint Spoofing** โ€” Otisk prstu TLS podobnรฝ prohlรญลพeฤi pomocรญ `wreq-js` pro obchรกzenรญ detekce botลฏ\n- **๐Ÿ” Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** โ€” Zmฤ›nรญ poล™adรญ zรกhlavรญ a polรญ v tฤ›le serveru tak, aby odpovรญdala nativnรญm binรกrnรญm podpisลฏm v CLI, ฤรญmลพ drasticky sniลพuje riziko nahlaลกovรกnรญ รบฤtu. IP adresa proxy je zachovรกna โ€” zรญskรกte souฤasnฤ› stealth **i** maskovรกnรญ IP adresy.\n\n
\n๐Ÿ†“ 4. โ€žChci pouลพรญvat umฤ›lou inteligenci pro kรณdovรกnรญ, ale nemรกm penรญzeโ€œ\n
\n\nNe kaลพdรฝ si mลฏลพe dovolit zaplatit 20โ€“200 dolarลฏ mฤ›sรญฤnฤ› za pล™edplatnรฉ AI. Studenti, vรฝvojรกล™i z rozvรญjejรญcรญch se zemรญ, amatรฉล™i a freelanceล™i potล™ebujรญ pล™รญstup ke kvalitnรญm modelลฏm za nulovou cenu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vestavฤ›nรญ poskytovatelรฉ bezplatnรฉ รบrovnฤ›** โ€” Nativnรญ podpora pro 100% bezplatnรฉ poskytovatele: iFlow (5 neomezenรฝch modelลฏ pล™es OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezenรฉ modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisรญc tokenลฏ/mฤ›sรญc zdarma)\n- **Ollama Cloud** โ€” Cloudovฤ› hostovanรฉ modely Ollama na `api.ollama.com` s bezplatnou รบrovnรญ โ€žLight usageโ€œ; pouลพijte prefix `ollamacloud/`\n- **Kombinace pouze zdarma** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = 0 $/mฤ›sรญc s nulovรฝmi prostoji\n- **NVIDIA NIM Free Access** โ€” ~40 RPM developerskรฝ pล™รญstup k vรญce neลพ 70 modelลฏm na build.nvidia.com (pล™echod z kreditลฏ na ฤistรฉ limity rychlosti)\n- **Strategie optimalizace nรกkladลฏ** โ€“ Strategie smฤ›rovรกnรญ, kterรก automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n
\n๐Ÿ”’ 5. โ€žPotล™ebuji chrรกnit svou brรกnu umฤ›lรฉ inteligence pล™ed neoprรกvnฤ›nรฝm pล™รญstupemโ€œ\n
\n\nPล™i zpล™รญstupnฤ›nรญ brรกny umฤ›lรฉ inteligence sรญti (LAN, VPS, Docker) mลฏลพe kdokoli s adresou spotล™ebovat tokeny/kvรณtu vรฝvojรกล™e. Bez ochrany jsou API zranitelnรก vลฏฤi zneuลพitรญ, prompt injection a dalลกรญmu zneuลพitรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sprรกva klรญฤลฏ API** โ€“ generovรกnรญ, rotace a vymezovรกnรญ rozsahu pro kaลพdรฉho poskytovatele s vyhrazenou strรกnkou `/dashboard/api-manager`\n- **Oprรกvnฤ›nรญ na รบrovni modelu** โ€“ Omezenรญ klรญฤลฏ API na konkrรฉtnรญ modely ( `openai/*` , zรกstupnรฉ znaky) pomocรญ pล™epรญnaฤe Povolit vลกe/Omezit\n- **Ochrana koncovรฝch bodลฏ API** โ€“ Vyลพaduje klรญฤ pro `/v1/models` a blokuje konkrรฉtnรญ poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** โ€” Vลกechny trasy dashboardu chrรกnฤ›nรฉ middlewarem `withAuth` + tokeny CSRF\n- **Omezovaฤ rychlosti** โ€” Omezovรกnรญ rychlosti na IP s konfigurovatelnรฝmi okny\n- **Filtrovรกnรญ IP adres** โ€” Seznam povolenรฝch/blokovanรฝch adres pro ล™รญzenรญ pล™รญstupu\n- **Ochrana proti vklรกdรกnรญ vรฝzev** โ€“ Sanitizace proti ลกkodlivรฝm vzorcลฏm vรฝzev\n- **ล ifrovรกnรญ AES-256-GCM** โ€“ pล™ihlaลกovacรญ รบdaje jsou v klidovรฉm stavu ลกifrovรกny\n\n
\n๐Ÿ›‘ 6. โ€žMลฏj poskytovatel selhal a jรก ztratil/a programovacรญ tokโ€œ\n
\n\nPoskytovatelรฉ umฤ›lรฉ inteligence se mohou stรกt nestabilnรญmi, vracet chyby 5xx nebo dosรกhnout doฤasnรฝch limitลฏ rychlosti. Pokud je vรฝvojรกล™ zรกvislรฝ na jedinรฉm poskytovateli, je jeho prรกce pล™eruลกena. Bez jistiฤลฏ mลฏลพe opakovanรฉ pokusy vรฉst k pรกdu aplikace.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Jistiฤ pro kaลพdรฝ model** โ€“ Automatickรฉ otevรญrรกnรญ/zavรญrรกnรญ s konfigurovatelnรฝmi prahovรฝmi hodnotami a dobou ochlazovรกnรญ (Zavล™eno/Otevล™eno/Poloviฤnรญ otevล™enรญ), rozsah definovanรฝ pro kaลพdรฝ model, aby se zabrรกnilo kaskรกdovรกnรญ blokลฏ\n- **Exponenciรกlnรญ odklad** โ€” Progresivnรญ zpoลพdฤ›nรญ opakovรกnรญ\n- **Anti-Thundering Herd** โ€” ochrana Mutex + semafor proti soubฤ›ลพnรฝm bouล™รญm s opakovanรฝmi pokusy\n- **Kombinovanรฉ zรกloลพnรญ ล™etฤ›zce** โ€“ Pokud primรกrnรญ poskytovatel selลพe, automaticky se propadne ล™etฤ›zcem bez zรกsahu.\n- **Kombinovanรฝ jistiฤ** โ€“ Automaticky deaktivuje selhรกvajรญcรญho poskytovatele v rรกmci kombinovanรฉho ล™etฤ›zce\n- **Dashboard stavu** โ€” Monitorovรกnรญ provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti, latence p50/p95/p99\n\n
\n๐Ÿ”ง 7. โ€žKonfigurace kaลพdรฉho nรกstroje umฤ›lรฉ inteligence je zdlouhavรก a opakujรญcรญ seโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Kaลพdรฝ nรกstroj potล™ebuje jinou konfiguraci (API endpoint, klรญฤ, model). Pล™ekonfigurovรกnรญ pล™i zmฤ›nฤ› poskytovatele nebo modelu je ztrรกta ฤasu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel nรกstrojลฏ CLI** โ€” Vyhrazenรก strรกnka s nastavenรญm jednรญm kliknutรญm pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generรกtor konfigurace GitHub Copilot** โ€“ Generuje `chatLanguageModels.json` pro VS Code s hromadnรฝm vรฝbฤ›rem modelu\n- **Prลฏvodce zavรกdฤ›nรญm** โ€“ 4krokovรฉ nastavenรญ pro zaฤรญnajรญcรญ uลพivatele\n- **Jeden koncovรฝ bod, vลกechny modely** โ€“ jednou nakonfigurujte `http://localhost:20128/v1` a zรญskejte pล™รญstup k vรญce neลพ 44 poskytovatelลฏm\n\n
\n๐Ÿ”‘ 8. โ€žSprรกva OAuth tokenลฏ od vรญce poskytovatelลฏ je pekloโ€œ\n
\n\nClaude Code, Codex, Gemini CLI, Copilot โ€“ vลกechny pouลพรญvajรญ OAuth 2.0 s tokeny s vyprลกenรญm platnosti. Vรฝvojรกล™i se musรญ neustรกle znovu autentizovat, ล™eลกit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdรกlenรฝch serverech. Obzvlรกลกtฤ› problematickรฝ je OAuth v LAN/VPS.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Automatickรก aktualizace tokenลฏ** โ€“ Tokeny OAuth se obnovujรญ na pozadรญ pล™ed vyprลกenรญm platnosti.\n- **Vestavฤ›nรฝ OAuth 2.0 (PKCE)** โ€“ Automatickรฝ tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow\n- **Multi-Account OAuth** โ€” Vรญce รบฤtลฏ na poskytovatele prostล™ednictvรญm extrakce tokenลฏ JWT/ID\n- **OAuth LAN/Remote Fix** โ€” Detekce privรกtnรญ IP adresy pro `redirect_uri` + manuรกlnรญ reลพim URL pro vzdรกlenรฉ servery\n- **OAuth Behind Nginx** โ€” Pouลพรญvรก `window.location.origin` pro kompatibilitu s reverznรญ proxy\n- **Prลฏvodce vzdรกlenรฝm OAuth** โ€“ Podrobnรฝ nรกvod k pล™ihlaลกovacรญm รบdajลฏm Google Cloud na VPS/Dockeru\n\n
\n๐Ÿ“Š 9. โ€žNevรญm, kolik utrรกcรญm ani kdeโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ vรญce placenรฝch poskytovatelลฏ, ale nemajรญ jednotnรฝ pล™ehled o vรฝdajรญch. Kaลพdรฝ poskytovatel mรก svลฏj vlastnรญ fakturaฤnรญ panel, ale neexistuje ลพรกdnรฝ konsolidovanรฝ pล™ehled. Mohou se hromadit neoฤekรกvanรฉ nรกklady.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard pro analรฝzu nรกkladลฏ** โ€“ Sledovรกnรญ nรกkladลฏ na token a sprรกva rozpoฤtu pro kaลพdรฉho poskytovatele\n- **Rozpoฤtovรฉ limity na รบroveลˆ** โ€“ Strop vรฝdajลฏ na รบroveลˆ, kterรฝ spouลกtรญ automatickรฝ zรกloลพnรญ reลพim\n- **Konfigurace cen podle modelu** โ€“ Konfigurovatelnรฉ ceny podle modelu\n- **Statistiky pouลพitรญ pro kaลพdรฝ klรญฤ API** โ€” Poฤet poลพadavkลฏ a ฤasovรฉ razรญtko poslednรญho pouลพitรญ pro kaลพdรฝ klรญฤ\n- **Analytickรฝ panel** โ€“ Statistickรฉ karty, graf vyuลพitรญ modelu, tabulka poskytovatelลฏ s mรญrou รบspฤ›ลกnosti a latencรญ\n\n
\n๐Ÿ› 10. โ€žNedokรกลพu diagnostikovat chyby a problรฉmy ve volรกnรญ umฤ›lรฉ inteligence.โ€œ\n
\n\nKdyลพ volรกnรญ selลพe, vรฝvojรกล™ nevรญ, zda se jednalo o limit rychlosti, vyprลกelรฝ token, ลกpatnรฝ formรกt nebo chybu poskytovatele. Fragmentovanรฉ protokoly napล™รญฤ rลฏznรฝmi terminรกly. Bez sledovatelnosti je ladฤ›nรญ metodou pokus-omyl.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel jednotnรฝch protokolลฏ** โ€“ 4 karty: Protokoly poลพadavkลฏ, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlรญลพeฤ protokolลฏ konzole** โ€” Prohlรญลพeฤ protokolลฏ v reรกlnรฉm ฤase ve stylu terminรกlu s barevnฤ› kรณdovanรฝmi รบrovnฤ›mi, automatickรฝm posouvรกnรญm, vyhledรกvรกnรญm a filtrovรกnรญm\n- **Protokoly proxy SQLite** โ€“ trvalรฉ protokoly, kterรฉ pล™eลพijรญ restart serveru\n- **Pล™ekladaฤskรฉ hล™iลกtฤ›** โ€” 4 reลพimy ladฤ›nรญ: Hล™iลกtฤ› (pล™eklad formรกtu), Tester chatu (okruลพnรญ), Testovacรญ stลฏl (dรกvkovรฝ), ลฝivรฝ monitor (v reรกlnรฉm ฤase)\n- **Telemetrie poลพadavkลฏ** โ€” latence p50/p95/p99 + trasovรกnรญ X-Request-Id\n- **Souborovรฉ protokolovรกnรญ s rotacรญ** โ€“ Konzolovรฝ interceptor zachycuje vลกe do protokolu JSON s rotacรญ na zรกkladฤ› velikosti\n- **Zprรกva o systรฉmovรฝch informacรญch** โ€” pล™รญkaz `npm run system-info` vygeneruje `system-info.txt` s kompletnรญm popisem vaลกeho prostล™edรญ (verze uzlu, verze OmniRoute, operaฤnรญ systรฉm, nรกstroje CLI, stav Dockeru/PM2). Pล™iloลพte jej pล™i hlรกลกenรญ problรฉmลฏ pro okamลพitรฉ tล™รญdฤ›nรญ.\n\n
\n๐Ÿ—๏ธ 11. โ€žNasazenรญ a รบdrลพba brรกny je sloลพitรกโ€œ\n
\n\nInstalace, konfigurace a รบdrลพba AI proxy v rลฏznรฝch prostล™edรญch (lokรกlnรญ, VPS, Docker, cloud) je pracnรก. Problรฉmy, jako jsou pevnฤ› zakรณdovanรฉ cesty, `EACCES` u adresรกล™ลฏ, konflikty portลฏ a multiplatformnรญ sestavenรญ, pล™ispรญvajรญ k obtรญลพรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **npm globรกlnรญ instalace** โ€” `npm install -g omniroute && omniroute` โ€” hotovo\n- **Docker Multi-Platform** โ€” AMD64 + nativnรญ ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** โ€” `base` (bez nรกstrojลฏ CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopovรก aplikace Electron** โ€” Nativnรญ aplikace pro Windows/macOS/Linux se systรฉmovou liลกtou, automatickรฝm spuลกtฤ›nรญm a offline reลพimem\n- **Reลพim rozdฤ›lenรฝch portลฏ** โ€“ API a ล™รญdicรญ panel na samostatnรฝch portech pro pokroฤilรฉ scรฉnรกล™e (reverznรญ proxy, sรญลฅovรกnรญ kontejnerลฏ)\n- **Cloud Sync** โ€“ Konfigurace synchronizace mezi zaล™รญzenรญmi pomocรญ Cloudflare Workers\n- **Zรกlohy databรกzรญ** โ€” Automatickรฉ zรกlohovรกnรญ, obnovenรญ, export a import vลกech nastavenรญ\n\n
\n๐ŸŒ 12. โ€žRozhranรญ je pouze v angliฤtinฤ› a mลฏj tรฝm nemluvรญ anglickyโ€œ\n
\n\nTรฝmy v neanglicky mluvรญcรญch zemรญch, zejmรฉna v Latinskรฉ Americe, Asii a Evropฤ›, se potรฝkajรญ s rozhranรญmi pouze v angliฤtinฤ›. Jazykovรฉ bariรฉry sniลพujรญ mรญru pล™ijetรญ a zvyลกujรญ chyby v konfiguraci.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard i18n โ€” 30 jazykลฏ** โ€” Vลกech 500+ klรกves je pล™eloลพeno vฤetnฤ› arabลกtiny, bulharลกtiny, dรกnลกtiny, nฤ›mฤiny, ลกpanฤ›lลกtiny, finลกtiny, francouzลกtiny, hebrejลกtiny, hindลกtiny, maฤarลกtiny, indonรฉลกtiny, italลกtiny, japonลกtiny, korejลกtiny, malajลกtiny, holandลกtiny, norลกtiny, polลกtiny, portugalลกtiny (PT/BR), rumunลกtiny, ruลกtiny, slovenลกtiny, ลกvรฉdลกtiny, thajลกtiny, ukrajinลกtiny, vietnamลกtiny, ฤรญnลกtiny, filipรญnลกtiny a angliฤtiny\n- **Podpora RTL** โ€“ Podpora psanรญ zprava doleva pro arabลกtinu a hebrejลกtinu\n- **Vรญcejazyฤnรฉ soubory README** โ€” 30 kompletnรญch pล™ekladลฏ dokumentace\n- **Vรฝbฤ›r jazyka** โ€” Ikona glรณbu v zรกhlavรญ pro pล™epรญnรกnรญ v reรกlnรฉm ฤase\n\n
\n๐Ÿ”„ 13. โ€žPotล™ebuji vรญc neลพ jen chat โ€“ potล™ebuji vloลพenรฉ soubory, obrรกzky, zvuk.โ€œ\n
\n\nUmฤ›lรก inteligence nenรญ jen dokonฤovรกnรญ chatu. Vรฝvojรกล™i potล™ebujรญ generovat obrรกzky, pล™episovat zvuk, vytvรกล™et embeddedy pro RAG, mฤ›nit poล™adรญ dokumentลฏ a moderovat obsah. Kaลพdรฉ API mรก jinรฝ koncovรฝ bod a formรกt.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vklรกdรกnรญ** โ€” `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generovรกnรญ obrรกzkลฏ** โ€” `/v1/images/generations` s 10 poskytovateli a vรญce neลพ 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Pล™evod textu na video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Pล™evod textu na hudbu** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Pล™epis zvuku** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Pล™evod textu na ล™eฤ** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a dalลกรญ stรกvajรญcรญ poskytovatelรฉ\n- **Moderovรกnรญ** โ€” `/v1/moderations` โ€” Kontroly bezpeฤnosti obsahu\n- **Zmฤ›na poล™adรญ** โ€” `/v1/rerank` โ€” Zmฤ›na poล™adรญ relevance dokumentu\n- **Responses API** โ€” Plnรก podpora `/v1/responses` pro Codex\n\n
\n๐Ÿงช 14. โ€žNemรกm zpลฏsob, jak testovat a porovnรกvat kvalitu napล™รญฤ modely.โ€œ\n
\n\nVรฝvojรกล™i chtฤ›jรญ vฤ›dฤ›t, kterรฝ model je pro jejich pล™รญpad pouลพitรญ nejlepลกรญ โ€“ kรณd, pล™eklad, uvaลพovรกnรญ โ€“ ale ruฤnรญ porovnรกvรกnรญ je pomalรฉ. Neexistujรญ ลพรกdnรฉ integrovanรฉ nรกstroje pro vyhodnocovรกnรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Hodnocenรญ LLM** โ€” Testovรกnรญ Golden setu s 10 pล™edinstalovanรฝmi pล™รญpady zahrnujรญcรญmi pozdravy, matematiku, geografii, generovรกnรญ kรณdu, dodrลพovรกnรญ JSON, pล™eklad, markdown, odmรญtnutรญ bezpeฤnostnรญch poลพadavkลฏ\n- **4 strategie shody** โ€” `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovacรญ lavice pro pล™ekladatelskรฉ hล™iลกtฤ›** โ€” Dรกvkovรฉ testovรกnรญ s vรญce vstupy a oฤekรกvanรฝmi vรฝstupy, porovnรกnรญ napล™รญฤ poskytovateli\n- **Tester chatu** โ€” Kompletnรญ okruลพnรญ cesta s vizuรกlnรญm vykreslovรกnรญm odpovฤ›dรญ\n- **ลฝivรฝ monitor** โ€” Stream vลกech poลพadavkลฏ prochรกzejรญcรญch proxy serverem v reรกlnรฉm ฤase\n\n
\n๐Ÿ“ˆ 15. โ€žPotล™ebuji ลกkรกlovat bez ztrรกty vรฝkonuโ€œ\n
\n\nS rostoucรญm objemem poลพadavkลฏ generujรญ stejnรฉ otรกzky bez uklรกdรกnรญ do mezipamฤ›ti duplicitnรญ nรกklady. Bez idempotence duplicitnรญ poลพadavky plรฝtvajรญ zpracovรกnรญm. Je nutnรฉ dodrลพovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sรฉmantickรก mezipamฤ›ลฅ** โ€” Dvouvrstvรก mezipamฤ›ลฅ (signatura + sรฉmantika) sniลพuje nรกklady a latenci\n- **Idempotence poลพadavku** โ€” 5s deduplikaฤnรญ okno pro identickรฉ poลพadavky\n- **Detekce limitu rychlosti** โ€“ sledovรกnรญ otรกฤek za minutu (RPM), minimรกlnรญ mezera a maximรกlnรญ soubฤ›ลพnรฉ sledovรกnรญ pro kaลพdรฉho poskytovatele\n- **Upravitelnรฉ limity rychlosti** โ€” Konfigurovatelnรฉ vรฝchozรญ hodnoty v Nastavenรญ โ†’ Odolnost s perzistencรญ\n- **Mezipamฤ›ลฅ pro ovฤ›ล™enรญ klรญฤลฏ API** โ€” tล™รญvrstvรก mezipamฤ›ลฅ pro vรฝkon produkฤnรญho prostล™edรญ\n- **Dashboard s telemetriรญ** โ€“ latence p50/p95/p99, statistiky mezipamฤ›ti, dostupnost\n\n
\n๐Ÿค– 16. โ€žChci mรญt chovรกnรญ modelลฏ globรกlnฤ› pod kontrolouโ€œ\n
\n\nVรฝvojรกล™i, kteล™รญ chtฤ›jรญ vลกechny odpovฤ›di v urฤitรฉm jazyce, se specifickรฝm tรณnem nebo chtฤ›jรญ omezit tokeny pro uvaลพovรกnรญ. Konfigurace tรฉto funkce v kaลพdรฉm nรกstroji/poลพadavku je nepraktickรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vloลพenรญ systรฉmovรฉho prompt** โ€“ Globรกlnรญ prompt aplikovanรฝ na vลกechny poลพadavky\n- **Validace rozpoฤtu Thinking** โ€” ล˜รญzenรญ alokace tokenลฏ na poลพadavek (prลฏchozรญ, automatickรฉ, vlastnรญ, adaptivnรญ)\n- **6 strategiรญ smฤ›rovรกnรญ** โ€“ Globรกlnรญ strategie, kterรฉ urฤujรญ, jak jsou poลพadavky distribuovรกny\n- **Smฤ›rovaฤ se zรกstupnรฝmi znaky** โ€” vzory `provider/*` dynamicky smฤ›rujรญ k libovolnรฉmu poskytovateli\n- **Pล™epรญnรกnรญ povolenรญ/zakรกzรกnรญ kombinacรญ** โ€“ Pล™epรญnรกnรญ kombinacรญ pล™รญmo z ล™รญdicรญho panelu\n- **Pล™epรญnรกnรญ poskytovatele** โ€“ Povolenรญ/zakรกzรกnรญ vลกech pล™ipojenรญ pro poskytovatele jednรญm kliknutรญm\n- **Blokovanรญ poskytovatelรฉ** โ€“ Vylouฤenรญ konkrรฉtnรญch poskytovatelลฏ ze seznamu `/v1/models`\n\n
\n๐Ÿงฐ 17. โ€žPotล™ebuji nรกstroje MCP jako prvotล™รญdnรญ produktovรฉ funkce.โ€œ\n
\n\nMnoho bran umฤ›lรฉ inteligence odhaluje MCP pouze jako skrytรฝ implementaฤnรญ detail. Tรฝmy potล™ebujรญ viditelnou a spravovatelnou operaฤnรญ vrstvu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- MCP se zobrazuje v navigaci na ล™รญdicรญm panelu a na kartฤ› protokolu koncovรฉho bodu.\n- Vyhrazenรก strรกnka pro sprรกvu MCP s procesy, nรกstroji, rozsahy a auditem\n- Vestavฤ›nรฝ rychlรฝ start pro `omniroute --mcp` a onboarding klienta\n\n
\n๐Ÿง  18. โ€žPotล™ebuji orchestraci A2A se synchronizacรญ a cestami รบloh streamu.โ€œ\n
\n\nPracovnรญ postupy agentลฏ vyลพadujรญ jak pล™รญmรฉ odpovฤ›di, tak dlouhodobรฉ streamovanรฉ provรกdฤ›nรญ s kontrolou ลพivotnรญho cyklu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Koncovรฝ bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamovรกnรญ SSE s ลกรญล™enรญm stavu terminรกlu\n- Rozhranรญ API ลพivotnรญho cyklu รบloh pro `tasks/get` a `tasks/cancel`\n\n
\n๐Ÿ›ฐ๏ธ 19. โ€žPotล™ebuji skuteฤnรฝ stav procesu MCP, ne odhadovanรฝ stav.โ€œ\n
\n\nProvoznรญ tรฝmy potล™ebujรญ vฤ›dฤ›t, zda je MCP skuteฤnฤ› aktivnรญ, nejen zda je API dosaลพitelnรฉ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Soubor bฤ›hovรฉho heartbeatu s PID, ฤasovรฝmi razรญtky, transportem, poฤtem nรกstrojลฏ a reลพimem rozsahu\n- API stavu MCP kombinujรญcรญ prezenฤnรญ signรกl a nedรกvnou aktivitu\n- Karty stavu uลพivatelskรฉho rozhranรญ pro zobrazenรญ aktuรกlnosti procesลฏ/provozuschopnosti/prezenฤnรญho signรกlu\n\n
\n๐Ÿ“‹ 20. โ€žPotล™ebuji auditovatelnรฉ provedenรญ nรกstroje MCPโ€œ\n
\n\nKdyลพ nรกstroje mฤ›nรญ konfiguraci nebo spouลกtฤ›jรญ operaฤnรญ akce, tรฝmy potล™ebujรญ forenznรญ sledovatelnost.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Protokolovรกnรญ auditu pro volรกnรญ nรกstrojลฏ MCP s podporou SQLite\n- Filtruje podle nรกstroje, รบspฤ›chu/neรบspฤ›chu, klรญฤe API a strรกnkovรกnรญ\n- Tabulka auditu dashboardu + koncovรฉ body statistik pro automatizaci\n\n
\n๐Ÿ” 21. โ€žPotล™ebuji omezenรก oprรกvnฤ›nรญ MCP pro kaลพdou integraci.โ€œ\n
\n\nRลฏznรญ klienti by mฤ›li mรญt pล™รญstup ke kategoriรญm nรกstrojลฏ s nejniลพลกรญmi oprรกvnฤ›nรญmi.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- 9 detailnรญch MCP sond pro kontrolovanรฝ pล™รญstup k nรกstrojลฏm\n- Vynucenรญ rozsahu a viditelnost v uลพivatelskรฉm rozhranรญ sprรกvy MCP\n- Bezpeฤnรก vรฝchozรญ poloha pro provoznรญ nรกstroje\n\n
\nโš™๏ธ 22. โ€žPotล™ebuji provoznรญ kontroly bez nutnosti pล™esouvรกnรญโ€œ\n
\n\nTรฝmy potล™ebujรญ rychlรฉ zmฤ›ny v bฤ›hovรฉm prostล™edรญ bฤ›hem incidentลฏ nebo nรกkladovรฝch udรกlostรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Pล™epnฤ›te aktivaci komba pล™รญmo z ล™รญdicรญho panelu MCP\n- Pouลพรญvejte profily odolnosti z pล™eddefinovanรฝch balรญฤkลฏ zรกsad\n- Resetujte stav jistiฤe ze stejnรฉho ovlรกdacรญho panelu\n\n
\n๐Ÿ”„ 23. โ€žPotล™ebuji ลพivรฝ pล™ehled o ลพivotnรญm cyklu รบkolลฏ A2A a jejich zruลกenรญ.โ€œ\n
\n\nBez pล™ehledu o ลพivotnรญm cyklu je obtรญลพnรฉ tล™รญdit incidenty รบkolลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Vรฝpis/filtrovรกnรญ รบkolลฏ podle stรกtu/dovednosti s strรกnkovรกnรญm\n- Podrobnรฝ pล™ehled metadat รบloh, udรกlostรญ a artefaktลฏ\n- Koncovรฝ bod zruลกenรญ รบlohy a akce uลพivatelskรฉho rozhranรญ s potvrzenรญm\n\n
\n๐ŸŒŠ 24. โ€žPotล™ebuji metriky aktivnรญho streamu pro A2A zรกtฤ›ลพโ€œ\n
\n\nStreamovacรญ pracovnรญ postupy vyลพadujรญ provoznรญ pล™ehled o soubฤ›ลพnosti a ลพivรฝch pล™ipojenรญch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- ฤŒรญtaฤe aktivnรญch streamลฏ integrovanรฉ do stavu A2A\n- ฤŒasovรฉ razรญtko poslednรญho รบkolu a poฤty pro jednotlivรฉ stavy\n- Karty A2A dashboardu pro monitorovรกnรญ provozu v reรกlnรฉm ฤase\n\n
\n๐Ÿชช 25. โ€žPotล™ebuji standardnรญ vyhledรกvรกnรญ agentลฏ pro klientyโ€œ\n
\n\nExternรญ klienti a orchestratoล™i potล™ebujรญ pro onboarding strojovฤ› ฤitelnรก metadata.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazenรฉ v uลพivatelskรฉm rozhranรญ pro sprรกvu\n- API pro stav A2A zahrnuje metadata pro zjiลกลฅovรกnรญ pro automatizaci\n\n
\n๐Ÿงญ 26. โ€žPotล™ebuji v uลพivatelskรฉm rozhranรญ produktu zjistitelnost protokolu.โ€œ\n
\n\nPokud uลพivatelรฉ nemohou objevit protokolovรฉ povrchy, kvalita pล™ijetรญ a podpory klesรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Strรกnka Konsolidovanรฉ **koncovรฉ body** s kartami pro koncovรฉ body Proxy, MCP, A2A a API\n- Pล™epรญnรกnรญ stavu inline sluลพby (Online/Offline) pro MCP a A2A\n- Odkazy z pล™ehledu na vyhrazenรฉ karty pro sprรกvu\n\n
\n๐Ÿงช 27. โ€žPotล™ebuji komplexnรญ ovฤ›ล™enรญ protokolu se skuteฤnรฝmi klienty.โ€œ\n
\n\nSimulovanรฉ testy nestaฤรญ k ovฤ›ล™enรญ kompatibility protokolu pล™ed vydรกnรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sada E2E, kterรก spouลกtรญ aplikaci a pouลพรญvรก skuteฤnรฝ transport klienta MCP SDK.\n- Klientskรฉ testy A2A pro toky zjiลกลฅovรกnรญ, odesรญlรกnรญ, streamovรกnรญ, naฤรญtรกnรญ a zruลกenรญ\n- Kล™รญลพovรก kontrola tvrzenรญ oproti API pro audit MCP a รบkoly A2A\n\n
\n๐Ÿ“ก 28. โ€žPotล™ebuji jednotnou pozorovatelnost napล™รญฤ vลกemi rozhranรญmiโ€œ\n
\n\nRozdฤ›lenรญ pozorovatelnosti podle protokolu vytvรกล™รญ slepรก mรญsta a delลกรญ MTTR.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรฉ dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie poลพadavkลฏ napล™รญฤ vrstvami OpenAI, MCP a A2A\n- Provoznรญ API pro stav a automatizaci\n\n
\n๐Ÿ’ผ 29. โ€žPotล™ebuji jeden runtime pro proxy + nรกstroje + orchestraci agentลฏโ€œ\n
\n\nSpouลกtฤ›nรญ mnoha samostatnรฝch sluลพeb zvyลกuje provoznรญ nรกklady a poฤet poruch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Proxy, MCP server a A2A server kompatibilnรญ s OpenAI v jednom balรญฤku\n- Sdรญlenรฉ ovฤ›ล™ovรกnรญ, odolnost, รบloลพiลกtฤ› dat a pozorovatelnost\n- Konzistentnรญ model politik napล™รญฤ vลกemi interakฤnรญmi plochami\n\n
\n๐Ÿš€ 30. โ€žPotล™ebuji agentskรฉ pracovnรญ postupy bez slepenรญ kรณdu.โ€œ\n
\n\nTรฝmy ztrรกcejรญ rychlost pล™i spojovรกnรญ vรญce ad-hoc sluลพeb a skriptลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรก strategie koncovรฝch bodลฏ pro klienty a agenty\n- Vestavฤ›nรก uลพivatelskรก rozhranรญ pro sprรกvu protokolลฏ a cesty pro ovฤ›ล™ovรกnรญ kouล™e\n- Zรกklady pล™ipravenรฉ pro produkฤnรญ prostล™edรญ (zabezpeฤenรญ, protokolovรกnรญ, odolnost, zรกlohovรกnรญ)\n\n### Pล™รญklady hernรญch plรกnลฏ (integrovanรฉ pล™รญpady uลพitรญ)\n\n**Pล™รญruฤka A: Maximalizace placenรฉho pล™edplatnรฉho + levnรฉ zรกlohovรกnรญ**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Pล™รญruฤka B: Kรณdovacรญ stack s nulovรฝmi nรกklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Pล™รญruฤka C: Nonstop zรกloลพnรญ ล™etฤ›zec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Pล™รญruฤka D: Operace agentลฏ s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Zaฤnฤ›te zdarma โ€” Nulovรฉ nรกklady na konfiguraci\n\n> Nastavte si kรณdovรกnรญ s umฤ›lou inteligencรญ bฤ›hem nฤ›kolika minut za **0 $/mฤ›sรญc** . Propojte tyto bezplatnรฉ รบฤty a vyuลพijte vestavฤ›nou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelรฉ odemฤeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Pล™ipojenรญ **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€“ **neomezenฤ›** |\n| 2 | Pล™ipojenรญ k **iFlow** (Google OAuth) | kimi-k2-myลกlenรญ, qwen3-coder-plus, deepseek-r1... โ€” **neomezenฤ›** |\n| 3 | Pล™ipojenรญ **Qwen** (kรณd zaล™รญzenรญ) | qwen3-coder-plus, qwen3-coder-flash... โ€” **neomezenฤ›** |\n| 4 | Pล™ipojenรญ **rozhranรญ pล™รญkazovรฉho ล™รกdku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180 000 GBP/mฤ›sรญc zdarma** |\n| 5 | `/dashboard/combos` โ†’ ล ablona **Free Stack (0 $)** | Automatickรฉ zaล™azenรญ vลกech bezplatnรฝch poskytovatelลฏ do routingu |\n\n**V libovolnรฉm IDE/CLI naveฤte:** `http://localhost:20128/v1` ยท Klรญฤ API: `any-string` ยท Hotovo.\n\n> **Volitelnรฉ doplลˆkovรฉ krytรญ (takรฉ zdarma):** Groq API klรญฤ (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelลฏ), Cerebras (1 milion tok/den).\n\n## โšก Rychlรฝ start\n\n### 1) Nainstalujte a spusลฅte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uลพivatelรฉ pnpm:** Po instalaci spusลฅte `pnpm approve-builds -g` , abyste povolili nativnรญ skripty pro sestavenรญ vyลพadovanรฉ programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard se otevรญrรก na `http://localhost:20128` a zรกkladnรญ URL API je `http://localhost:20128/v1` .\n\n| Pล™รญkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuลกtฤ›nรญ serveru ( `PORT=20128` , API a dashboard na stejnรฉm portu) |\n| `omniroute --port 3000` | Nastavte kanonickรฝ/API port na 3000 |\n| `omniroute --mcp` | Spuลกtฤ›nรญ MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevรญrat prohlรญลพeฤ automaticky |\n| `omniroute --help` | Zobrazit nรกpovฤ›du |\n\nVolitelnรฝ reลพim s rozdฤ›lenรฝm portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Pล™ipojte poskytovatele a vytvoล™te si klรญฤ API\n\n1. Otevล™ete Dashboard โ†’ `Providers` a pล™ipojte alespoลˆ jednoho poskytovatele (klรญฤ OAuth nebo API).\n2. Otevล™ete Dashboard โ†’ `Endpoints` a vytvoล™te API klรญฤ.\n3. (Volitelnรฉ) Otevล™ete Dashboard โ†’ `Combos` a nastavte zรกloลพnรญ ล™etฤ›zec.\n\n### 3) Nasmฤ›rujte svลฏj kรณdovacรญ nรกstroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilnรญmi s OpenAI.\n\n### 4) Povolenรญ a ovฤ›ล™enรญ protokolลฏ (v2.0)\n\n**MCP (pro operace ล™รญzenรฉ nรกstroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak pล™ipojte svรฉho MCP klienta pล™es `stdio` a otestujte nรกstroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovnรญ postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ovฤ›ล™te vลกe od zaฤรกtku do konce (doporuฤeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ovฤ›ล™uje skuteฤnรฉ toky klientลฏ MCP a A2A v porovnรกnรญ se spuลกtฤ›nou aplikacรญ.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute je k dispozici jako veล™ejnรฝ obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlรฝ bฤ›h:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostล™edรญ:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Pouลพรญvรกnรญ Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | ล tรญtek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovฤ›jลกรญ stabilnรญ verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuรกlnรญ verze |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktopovรก aplikace โ€“ offline a vลพdy zapnutรก\n\n> ๐Ÿ†• **NOVINKA!** OmniRoute je nynรญ k dispozici jako **nativnรญ desktopovรก aplikace** pro Windows, macOS a Linux.\n\nSpusลฅte OmniRoute jako samostatnou desktopovou aplikaci โ€“ pro lokรกlnรญ modely nenรญ potล™eba ลพรกdnรฝ terminรกl, prohlรญลพeฤ ani internet. Aplikace zaloลพenรก na platformฤ› Electron obsahuje:\n\n- ๐Ÿ–ฅ๏ธ **Nativnรญ okno** โ€” Vyhrazenรฉ okno aplikace s integracรญ do systรฉmovรฉ liลกty\n- ๐Ÿ”„ **Automatickรฉ spuลกtฤ›nรญ** โ€” Spuลกtฤ›nรญ OmniRoute po pล™ihlรกลกenรญ do systรฉmu\n- ๐Ÿ”” **Nativnรญ oznรกmenรญ** โ€“ Zรญskejte upozornฤ›nรญ na vyฤerpรกnรญ kvรณty nebo problรฉmy s poskytovateli\n- โšก **Instalace jednรญm kliknutรญm** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline reลพim** โ€” Funguje plnฤ› offline s pล™iloลพenรฝm serverem\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systรฉmovรฝ zรกsobnรญk\n\nPo minimalizaci se OmniRoute nachรกzรญ v systรฉmovรฉ liลกtฤ› a nabรญzรญ rychlรฉ akce:\n\n- Otevล™รญt ล™รญdicรญ panel\n- Zmฤ›nit port serveru\n- Ukonฤit aplikaci\n\n๐Ÿ“– รšplnรก dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pล™ehled cen\n\n| รšroveลˆ | Poskytovatel | Nรกklady | Obnovenรญ kvรณty | Nejlepลกรญ pro |\n| --------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **๐Ÿ’ณ Pล˜EDPLATNร‰** | Claude Code (profesionรกl) | 20 dolarลฏ mฤ›sรญฤnฤ› | 5 hodin + tรฝdnฤ› | Jiลพ pล™ihlรกลกen/a k odbฤ›ru |\n| Kodex (Plus/Pro) | 20โ€“200 USD/mฤ›sรญc | 5 hodin + tรฝdnฤ› | Uลพivatelรฉ OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisรญc mฤ›sรญฤnฤ› + 1 tisรญc dennฤ› | Kaลพdรฝ! |\n| GitHub Copilot | 10โ€“19 USD/mฤ›sรญc | Mฤ›sรญฤnรญ | Uลพivatelรฉ GitHubu |\n| **๐Ÿ”‘ KLรฤŒ API** | NVIDIA NIM | **ZDARMA** (vรฝvoj navลพdy) | ~40 ot./min | 70+ otevล™enรฝch modelลฏ |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ na svฤ›tฤ› |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisรญc otรกฤek za minutu | Ultrarychlรก lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | ลฝรกdnรฝ | Nejlepลกรญ zdลฏvodnฤ›nรญ ceny a kvality |\n| xAI Grok-4 Rychlรฝ | **0,20/0,50 USD za 1 milion** ๐Ÿ†• | ลฝรกdnรฝ | Nejrychlejลกรญ + volรกnรญ nรกstroje, ultranรญzkรฉ |\n| xAI Grok-4 (standardnรญ) | 0,20/1,50 USD za 1 milion ๐Ÿ†• | ลฝรกdnรฝ | Vlajkovรก loฤ Reasoning od xAI |\n| Mistral | Zkuลกebnรญ verze zdarma + placenรฉ | Omezenรก sazba | Evropskรก umฤ›lรก inteligence |\n| OpenRouter | Platba za pouลพitรญ | ลฝรกdnรฝ | Vรญce neลพ 100 modelลฏ agregovรกno. |\n| **๐Ÿ’ฐ LEVNร‰** | GLM-5 (pล™es Z.AI) ๐Ÿ†• | 0,5 USD/1 milion | Dennฤ› v 10:00 | Vรฝstup 128 tisรญc obrazovรฝch bodลฏ, nejnovฤ›jลกรญ vlajkovรก loฤ |\n| GLM-4.7 | 0,6 USD/1 milion | Dennฤ› v 10:00 | Zรกloha rozpoฤtu |\n| MiniMax M2.5 ๐Ÿ†• | Vstup 0,3 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | รšvaha + agentnรญ รบkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | Nejlevnฤ›jลกรญ varianta |\n| Kimi K2.5 (Moonshot API) ๐Ÿ†• | Platba za pouลพitรญ | ลฝรกdnรฝ | Pล™รญmรฝ pล™รญstup k Moonshot API |\n| Kimi K2 | 9 dolarลฏ mฤ›sรญฤnฤ› bez zรกvazkลฏ | 10 milionลฏ tokenลฏ/mฤ›sรญc | Pล™edvรญdatelnรฉ nรกklady |\n| **๐Ÿ†“ ZDARMA** | iFlow | **0 dolarลฏ** | Neomezenรฝ | 5 modelลฏ neomezenฤ› |\n| Qwen | **0 dolarลฏ** | Neomezenรฝ | 4 modely neomezenฤ› |\n| Kiro | **0 dolarลฏ** | Neomezenรฝ | Claude Sonnet/Haiku (tvorce AWS) |\n\n> ๐Ÿ†• **Pล™idรกny novรฉ modely (bล™ezen 2026):** ล™ada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkovรกno na 1143 ms โ€“ o 30 % rychlejลกรญ neลพ Gemini 2.5 Flash), GLM-5 pล™es Z.AI s vรฝstupem 128K, uvaลพovรกnรญ MiniMax M2.5, aktualizovanรฉ ceny DeepSeek V3.2, Kimi K2.5 pล™es Moonshot Direct API.\n\n**๐Ÿ’ก Kombinovanรฝ balรญk za 0 $ โ€” Kompletnรญ bezplatnรก instalace:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\niFlow (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Nulovรฉ nรกklady. Nikdy nepล™estรกvejte s kรณdovรกnรญm.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a vลกechny zรกloลพnรญ reลพimy se provede automaticky โ€“ ลพรกdnรฉ ruฤnรญ pล™epรญnรกnรญ.\n\n---\n\n---\n\n## ๐Ÿ†“ Bezplatnรฉ modely โ€“ Co skuteฤnฤ› zรญskรกte\n\n> Vลกechny nรญลพe uvedenรฉ modely jsou **100% zdarma a nevyลพadujรญ ลพรกdnou kreditnรญ kartu** . OmniRoute mezi nimi automaticky propojรญ trasy, kdyลพ dojde jedna kvรณta โ€“ zkombinujte je vลกechny a zรญskejte tak nerozluฤnou kombinaci za 0 dolarลฏ.\n\n### ๐Ÿ”ต CLAUDE MODELS (pล™es Kiro โ€” AWS Builder ID)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-opus-4.6` | `kr/` | **Neomezenรฝ** | Nejnovฤ›jลกรญ opus od Kira |\n\n### ๐ŸŸข MODELY IFLOW (Bezplatnรฉ OAuth โ€” bez nutnosti platit kreditnรญ kartou)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-plus` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `deepseek-r1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `minimax-m2.1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `kimi-k2` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n\n### ๐ŸŸก MODELY QWEN (Ovฤ›ล™enรญ kรณdu zaล™รญzenรญ)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-next` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `vision-model` | `qw/` | **Neomezenรฝ** | Multimodรกlnรญ (obrรกzky) |\n\n### ๐ŸŸฃ Rozhranรญ GEMINI CLI (Google OAuth)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisรญc tok/mฤ›sรญc** + 1 tisรญc/den | Mฤ›sรญฤnรญ reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisรญc mฤ›sรญฤnฤ› (sdรญlenรฝ bazรฉn) | Vysokรก kvalita |\n\n### โšซ NVIDIA NIM (Bezplatnรฝ klรญฤ API โ€” build.nvidia.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vรฝvojรกล™) | ลฝรกdnรฝ limit tokenลฏ | **~40 ot./min** | Vรญce neลพ 70 modelลฏ; pล™echod na ฤistรฉ limity sazeb v polovinฤ› roku 2025 |\n\nOblรญbenรฉ bezplatnรฉ modely: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct` , `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Bezplatnรฝ klรญฤ API โ€” inference.cerebras.ai)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenลฏ/den** | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ inference LLM na svฤ›tฤ›; dennฤ› se resetuje |\n\nDostupnรฉ zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Bezplatnรฝ API klรญฤ โ€” console.groq.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisรญc otรกฤek za minutu** | 30 ot./min na model | ลฝรกdnรก kreditnรญ karta; limit 429, neรบฤtovรกno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **๐Ÿ’ก Ultimรกtnรญ bezplatnรฝ zรกsobnรญk:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> โ†’ iFlow (5 models, unlimited)\n> โ†’ Qwen (4 models, unlimited)\n> โ†’ Gemini CLI (180K/mo)\n> โ†’ Cerebras (1M tok/day)\n> โ†’ Groq (14.4K req/day)\n> โ†’ NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a uลพ nikdy nebudete platit za umฤ›lou inteligenci.\n\n## ๐ŸŽ™๏ธ Kombinovanรก transkripce zdarma\n\n> Pล™episujte libovolnรฉ audio/video za **0 $** โ€“ Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako zรกloลพnรญ nรกstroj, Groq Whisper jako neomezenรก nouzovรก zรกloha.\n\n| Poskytovatel | Bezplatnรฉ kredity | Nejlepลกรญ model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| ๐ŸŸข **Deepgram** | **200 dolarลฏ zdarma** (registrace) | `nova-3` โ€” nejvyลกลกรญ pล™esnost, vรญce neลพ 30 jazykลฏ | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ต **AssemblyAI** | **50 dolarลฏ zdarma** (registrace) | `universal-3-pro` โ€” kapitoly, sentiment, osobnรญ รบdaje | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ด **Groq** | **Navลพdy zdarma** | `whisper-large-v3` โ€” OpenAI ล epot | 30 ot./min (omezenรก rychlost) |\n\n**Navrhovanรก kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nPak v `/dashboard/media` โ†’ zรกloลพka **Pล™epis** : nahrajte libovolnรฝ zvukovรฝ nebo video soubor โ†’ vyberte kombinovanรฝ koncovรฝ bod โ†’ zรญskejte pล™epis v podporovanรฝch formรกtech.\n\n## ๐Ÿ’ก Klรญฤovรฉ vlastnosti\n\nOmniRoute v2.0 je navrลพen jako operaฤnรญ platforma, nikoli pouze jako proxy pro relรฉ.\n\n### ๐Ÿค– Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dฤ›lรก |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (16 nรกstrojลฏ)** | Nรกstroje IDE/agent prostล™ednictvรญm 3 transportลฏ: stdio, SSE ( `/api/mcp/sse` ), Streamovatelnรฝ HTTP ( `/api/mcp/stream` ) |\n| ๐Ÿค **A2A server (JSON-RPC + SSE)** | Spouลกtฤ›nรญ รบloh mezi agenty se synchronizacรญ a streamovรกnรญm |\n| ๐Ÿงญ **Konsolidovanรก strรกnka koncovรฝch bodลฏ** | Strรกnka pro sprรกvu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| ๐ŸŽš๏ธ **Pล™epรญnaฤe pro povolenรญ/zakรกzรกnรญ sluลพby** | Pล™epรญnaฤe ZAP/VYP pro MCP a A2A s trvalรฝm nastavenรญm (vรฝchozรญ: VYP) |\n| ๐Ÿ›ฐ๏ธ **Srdeฤnรญ tep za bฤ›hu MCP** | Skuteฤnรฝ stav procesu (pid, doba provozuschopnosti, stรกล™รญ heartbeatu, transport, reลพim rozsahu) |\n| ๐Ÿ“‹ **Auditnรญ zรกznam MCP** | Filtrovatelnรฉ protokoly auditu s hodnocenรญm รบspฤ›chu/neรบspฤ›chu a klรญฤovรฝm pล™iล™azenรญm |\n| ๐Ÿ” **Vynucovรกnรญ rozsahu MCP** | 9 podrobnรฝch oprรกvnฤ›nรญ pro ล™รญzenรฝ pล™รญstup k nรกstrojลฏm |\n| ๐Ÿ“ก **Sprรกva ลพivotnรญho cyklu รบkolลฏ A2A** | Seznam/filtrovรกnรญ รบloh, kontrola udรกlostรญ/artefaktลฏ, zruลกenรญ spuลกtฤ›nรฝch รบloh |\n| ๐Ÿ“‹ **Objevenรญ karty agenta** | `/.well-known/agent.json` pro automatickรฉ vyhledรกvรกnรญ klientลฏ |\n| ๐Ÿงช **Testovacรญ postroj Protocol E2E** | Skuteฤnรฉ MCP SDK + toky klientลฏ A2A v `test:protocols:e2e` |\n| โš™๏ธ **Provoznรญ kontroly** | Kombinace pล™epรญnaฤลฏ, pouลพitรญ profilลฏ odolnosti, resetovรกnรญ jistiฤลฏ z jednoho ovlรกdacรญho panelu |\n\n### ๐Ÿง  Smฤ›rovรกnรญ a inteligence\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| ๐ŸŽฏ **Inteligentnรญ ฤtyล™รบrovลˆovรฝ zรกloลพnรญ systรฉm** | Automatickรก trasa: Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma |\n| ๐Ÿ“Š **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** | Poฤet tokenลฏ v reรกlnรฉm ฤase + odpoฤet resetovรกnรญ pro kaลพdรฉho poskytovatele |\n| ๐Ÿ”„ **Pล™eklad formรกtu** | OpenAI โ†” Claude โ†” Gemini โ†” Odpovฤ›di s konverzemi bezpeฤnรฝmi pro schรฉma |\n| ๐Ÿ‘ฅ **Podpora vรญce รบฤtลฏ** | Vรญce รบฤtลฏ na poskytovatele s inteligentnรญm vรฝbฤ›rem |\n| ๐Ÿ”„ **Automatickรก aktualizace tokenลฏ** | Tokeny OAuth se automaticky obnovujรญ pล™i opakovanรฉm pokusu. |\n| ๐ŸŽจ **Vlastnรญ kombinace** | 6 vyvaลพovacรญch strategiรญ + ล™รญzenรญ zรกloลพnรญho ล™etฤ›zce |\n| ๐ŸŒ **Smฤ›rovaฤ se zรกstupnรฝmi znaky** | dynamickรฉ smฤ›rovรกnรญ `provider/*` |\n| ๐Ÿง  **Pล™emรฝลกlenรญ o rozpoฤtovรฝch kontrolรกch** | Limity pro prลฏchozรญ, automatickรฉ, vlastnรญ a adaptivnรญ uvaลพovรกnรญ |\n| ๐Ÿ”€ **Aliasy modelลฏ** | Vestavฤ›nรฉ + vlastnรญ aliasovรกnรญ modelลฏ a bezpeฤnost migrace |\n| โšก **Degradace pozadรญ** | Smฤ›rujte รบlohy na pozadรญ s nรญzkou prioritou na levnฤ›jลกรญ modely |\n| ๐Ÿงช **Chytrรฉ smฤ›rovรกnรญ s ohledem na รบkoly** | Automatickรฝ vรฝbฤ›r modelu podle typu obsahu (kรณdovรกnรญ/vize/analรฝza/sumarizace) |\n| ๐Ÿ’ฌ **Vstล™ikovรกnรญ do systรฉmu** | Globรกlnรญ kontroly chovรกnรญ uplatลˆovanรฉ konzistentnฤ› |\n| ๐Ÿ“„ **Kompatibilita API pro odpovฤ›di** | Plnรก podpora `/v1/responses` pro Codex a pokroฤilรฉ agentickรฉ pracovnรญ postupy |\n\n### ๐ŸŽต Multimodรกlnรญ API\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Generovรกnรญ obrรกzkลฏ** | `/v1/images/generations` s cloudovรฝm a lokรกlnรญm backendem |\n| ๐Ÿ“ **Vloลพenรญ** | `/v1/embeddings` pro vyhledรกvรกnรญ a RAG pipelines |\n| ๐ŸŽค **Pล™epis zvuku** | `/v1/audio/transcriptions` (Whisper a dalลกรญ poskytovatelรฉ) |\n| ๐Ÿ”Š **Pล™evod textu na ล™eฤ** | `/v1/audio/speech` (vรญce enginลฏ/poskytovatelลฏ) |\n| ๐ŸŽฌ **Generovรกnรญ videa** | `/v1/videos/generations` (pracovnรญ postupy ComfyUI + SD WebUI) |\n| ๐ŸŽต **Hudebnรญ generace** | `/v1/music/generations` (pracovnรญ postupy ComfyUI) |\n| ๐Ÿ›ก๏ธ **Moderovรกnรญ** | Bezpeฤnostnรญ kontroly `/v1/moderations` |\n| ๐Ÿ”€ **Zmฤ›na poล™adรญ** | `/v1/rerank` pro hodnocenรญ relevance |\n| ๐Ÿ” **Vyhledรกvรกnรญ na webu** ๐Ÿ†• | `/v1/search` โ€” 5 poskytovatelลฏ (Serper, Brave, Perplexity, Exa, Tavily), vรญce neลพ 6 500 zdarma/mฤ›sรญc, automatickรฉ pล™epnutรญ na zรกloลพnรญ systรฉm, mezipamฤ›ลฅ |\n\n### ๐Ÿ›ก๏ธ Odolnost, bezpeฤnost a sprรกva vฤ›cรญ veล™ejnรฝch\n\n| Funkce | Co to dฤ›lรก |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Jistiฤe** | Vypnutรญ/obnovenรญ pro kaลพdรฝ model s ovlรกdรกnรญm prahovรฝch hodnot |\n| ๐ŸŽฏ **Modely s ohledem na koncovรฉ body** | Vlastnรญ modely deklarujรญ podporovanรฉ koncovรฉ body + formรกt API |\n| ๐Ÿ›ก๏ธ **Stรกdo proti hromลฏm** | Ochrana mutexu a semaforu pล™i udรกlostech opakovรกnรญ/rychlosti |\n| ๐Ÿง  **Sรฉmantickรก + podpisovรก mezipamฤ›ลฅ** | Snรญลพenรญ nรกkladลฏ/latence dรญky dvฤ›ma vrstvรกm mezipamฤ›ti |\n| โšก **ลฝรกdost o idempotenci** | Okno ochrany proti duplikacรญm |\n| ๐Ÿ”’ **Falลกovรกnรญ otiskลฏ prstลฏ pomocรญ TLS** | Otisk TLS podobnรฝ prohlรญลพeฤi โ€“ **sniลพuje detekci botลฏ a nahlaลกovรกnรญ รบฤtลฏ** |\n| ๐Ÿ” **Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** | Shoduje se s nativnรญmi podpisy poลพadavkลฏ CLI โ€“ **sniลพuje riziko zablokovรกnรญ a zรกroveลˆ zachovรกvรก IP adresu proxy** |\n| ๐ŸŒ **Filtrovรกnรญ IP adres** | Ovlรกdรกnรญ seznamu povolenรฝch/blokovanรฝch poloลพek pro odhalenรก nasazenรญ |\n| ๐Ÿ“Š **Upravitelnรฉ limity rychlosti** | Konfigurovatelnรฉ globรกlnรญ/na รบrovni poskytovatele limity s perzistencรญ |\n| ๐Ÿ”‘ **Sprรกva klรญฤลฏ API a stanovenรญ rozsahu** | Bezpeฤnรฉ vydรกvรกnรญ/rotace klรญฤลฏ a kontroly modelu/poskytovatele |\n| ๐Ÿ›ก๏ธ **Chrรกnฤ›nรฉ `/models`** | Volitelnรฉ ovฤ›ล™ovรกnรญ a skrytรญ poskytovatele pro katalog modelลฏ |\n\n### ๐Ÿ“Š Pozorovatelnost a analytika\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| ๐Ÿ“ **ลฝรกdost + protokolovรกnรญ proxy** | รšplnรฉ protokolovรกnรญ poลพadavkลฏ/odpovฤ›dรญ a proxy |\n| ๐Ÿ“‹ **Sjednocenรฝ panel protokolลฏ** | Zobrazenรญ poลพadavkลฏ, proxy, auditu a konzole na jednรฉ strรกnce |\n| ๐Ÿ” **Vyลพรกdat si telemetrii** | Latence p50/p95/p99 a trasovรกnรญ poลพadavkลฏ |\n| ๐Ÿฅ **Panel zdravรญ** | Doba provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti |\n| ๐Ÿ’ฐ **Sledovรกnรญ nรกkladลฏ** | Kontrola rozpoฤtu a pล™ehled o cenรกch pro jednotlivรฉ modely |\n| ๐Ÿ“ˆ **Analytickรฉ vizualizace** | Pล™ehledy vyuลพitรญ modelลฏ/poskytovatelลฏ a zobrazenรญ trendลฏ |\n| ๐Ÿงช **Rรกmec hodnocenรญ** | Testovรกnรญ zlatรฉ sady s konfigurovatelnรฝmi strategiemi shody |\n\n### โ˜๏ธ Nasazenรญ a platforma\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| ๐ŸŒ **Nasazenรญ kdekoli** | Localhost, VPS, Docker, cloudovรก prostล™edรญ |\n| ๐Ÿ’พ **Synchronizace s cloudem** | Synchronizace konfigurace pล™es cloud worker |\n| ๐Ÿ”„ **Zรกlohovรกnรญ/Obnovenรญ** | Toky exportu/importu a obnovy po havรกrii |\n| ๐Ÿง™ **Prลฏvodce nรกstupem** | Prลฏvodce prvnรญm spuลกtฤ›nรญm |\n| ๐Ÿ”ง **Panel nรกstrojลฏ CLI** | Nastavenรญ oblรญbenรฝch kรณdovacรญch nรกstrojลฏ jednรญm kliknutรญm |\n| ๐ŸŽฎ **Modelovรฉ hล™iลกtฤ›** | Otestujte libovolnรฉho poskytovatele/model/koncovรฝ bod z ล™รญdicรญho panelu |\n| ๐Ÿ” **Pล™epรญnaฤ otiskลฏ prstลฏ v pล™รญkazovรฉm ล™รกdku** | Porovnรกvรกnรญ otiskลฏ prstลฏ podle poskytovatele v Nastavenรญ > Zabezpeฤenรญ |\n| ๐ŸŒ **i18n (30 jazykลฏ)** | Plnรก jazykovรก podpora dashboardu a dokumentace s psanรญm zprava doleva |\n| ๐Ÿ“‚ **Adresรกล™ vlastnรญch dat** | Pล™epsรกnรญ `DATA_DIR` pro umรญstฤ›nรญ รบloลพiลกtฤ› |\n\n### Hlubokรฝ pohled na funkce\n\n#### Chytrรก zรกloลพnรญ funkce s praktickou kontrolou nรกkladลฏ\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyลพ selลพe kvรณta, rychlost nebo stav, OmniRoute automaticky pล™ejde k dalลกรญmu kandidรกtovi bez nutnosti ruฤnรญho pล™epรญnรกnรญ.\n\n#### Sprรกva protokolลฏ, kterรก je viditelnรก a ovladatelnรก\n\n- MCP + A2A jsou viditelnรฉ v uลพivatelskรฉm rozhranรญ a dokumentaci (nejsou skrytรฉ)\n- API pro stav protokolu zpล™รญstupลˆujรญ ลพivรก provoznรญ data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnujรญ akce pro operace 2. dne (pล™epรญnรกnรญ kombinacรญ, resetovรกnรญ jistiฤลฏ, zruลกenรญ รบkolลฏ)\n\n#### Pracovnรญ postup pล™ekladatele + validace\n\nOblast pล™ekladatele zahrnuje:\n\n- **Hล™iลกtฤ›** : kontroly transformace poลพadavkลฏ\n- **Tester chatu** : kompletnรญ okruลพnรญ cesta poลพadavku/odpovฤ›di\n- **Testovacรญ stolice** : vรญce pล™รญpadลฏ v jednom bฤ›hu\n- **ลฝivรฝ monitor** : zobrazenรญ provozu v reรกlnรฉm ฤase\n\nPlus validace protokolu se skuteฤnรฝmi klienty pomocรญ `npm run test:protocols:e2e` .\n\n> ๐Ÿ“– **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** โ€” Referenฤnรญ informace o nรกstrojรญch, konfigurace IDE a pล™รญklady klientลฏ\n>\n> ๐Ÿ“– **[Soubor README pro A2A Server](src/lib/a2a/README.md)** โ€” Dovednosti, metody JSON-RPC, streamovรกnรญ a ลพivotnรญ cyklus รบloh\n\n## ๐Ÿงช Hodnocenรญ (Evals)\n\nOmniRoute obsahuje vestavฤ›nรฝ hodnotรญcรญ rรกmec pro testovรกnรญ kvality odpovฤ›dรญ LLM v porovnรกnรญ se zlatou sadou. Pล™รญstup k nฤ›mu je moลพnรฝ pล™es **Analรฝzy โ†’ Hodnocenรญ** v dashboardu.\n\n### Vestavฤ›nรก zlatรก sada\n\nPล™edinstalovanรก sada โ€žOmniRoute Golden Setโ€œ obsahuje testovacรญ pล™รญpady pro:\n\n- Zdravรญm, matematika, zemฤ›pis, generovรกnรญ kรณdu\n- Shoda s formรกtem JSON, pล™eklad, generovรกnรญ markdownลฏ\n- Bezpeฤnostnรญ odmรญtnutรญ (ลกkodlivรฝ obsah), poฤรญtรกnรญ, booleovskรก logika\n\n### Strategie hodnocenรญ\n\n| Strategie | Popis | Pล™รญklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Vรฝstup se musรญ pล™esnฤ› shodovat | `\"4\"` |\n| `contains` | Vรฝstup musรญ obsahovat podล™etฤ›zec (bez rozliลกenรญ velkรฝch a malรฝch pรญsmen) | `\"Paris\"` |\n| `regex` | Vรฝstup musรญ odpovรญdat vzoru regulรกrnรญch vรฝrazลฏ | `\"1.*2.*3\"` |\n| `custom` | Vlastnรญ JS funkce vracรญ true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Prลฏvodce nastavenรญm\n\n### Nastavenรญ protokolu (MCP + A2A)\n\n
\n๐Ÿงฉ Nastavenรญ MCP (Model Context Protocol)\n
\n\nSpuลกtฤ›nรญ MCP transportu v reลพimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporuฤenรฝ postup ovฤ›ล™enรญ:\n\n1. Pล™ipojte svรฉho MCP klienta pล™es stdio.\n2. Spusลฅte `omniroute_get_health` .\n3. Spusลฅte `omniroute_list_combos` .\n4. Otevล™ete `/dashboard/mcp` pro ovฤ›ล™enรญ prezenฤnรญho signรกlu, aktivity a auditu.\n\nUลพiteฤnรก API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n๐Ÿค Nastavenรญ A2A (Agent2Agent)\n
\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat รบkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSprรกva ลพivotnรญho cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvoznรญ uลพivatelskรฉ rozhranรญ:\n\n- `/dashboard/a2a` pro pozorovatelnost รบloh/stavลฏ/streamลฏ a akce kouล™enรญ\n\n
\n๐Ÿงช Komplexnรญ validace protokolu\n
\n\nOvฤ›ล™te oba protokoly se skuteฤnรฝmi klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTรญm se ovฤ›ล™uje:\n\n- Pล™ipojenรญ/seznam/volรกnรญ klienta MCP SDK\n- A2A objevovรกnรญ/odesรญlรกnรญ/streamovรกnรญ/zรญskรกvรกnรญ/zruลกenรญ\n- Kล™รญลพovรก kontrola dat v auditu MCP a API pro sprรกvu รบloh A2A\n\n
\n๐Ÿ’ณ Poskytovatelรฉ pล™edplatnรฉho\n
\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionรกly:** Pro sloลพitรฉ รบkoly pouลพรญvejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvรณtu pro kaลพdรฝ model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Sprรกva limitลฏ รบฤtu Codex (5h + tรฝdnฤ›)\n\nKaลพdรฝ รบฤet Codex mรก nynรญ pล™epรญnaฤe zรกsad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinovรฉho prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zรกsadu tรฝdennรญho prahu okna.\n- Prahovรฉ chovรกnรญ: kdyลพ povolenรฉ okno dosรกhne vyuลพitรญ >=90 %, je danรฝ รบฤet pล™eskoฤen.\n- Chovรกnรญ rotace: OmniRoute automaticky pล™esmฤ›ruje na dalลกรญ zpลฏsobilรฝ รบฤet Codex.\n- Chovรกnรญ pล™i resetovรกnรญ: Po `resetAt` urฤitรฉ doby se รบฤet automaticky opฤ›t stane zpลฏsobilรฝm.\n\nScรฉnรกล™e:\n\n- `5h ON` + `Weekly ON` : รบฤet je pล™eskoฤen, kdyลพ kterรฉkoli z oken dosรกhne prahovรฉ hodnoty.\n- `5h OFF` + `Weekly ON` : รบฤet mลฏลพe bรฝt zablokovรกn pouze tรฝdennรญm pouลพรญvรกnรญm.\n- `5h ON` + `Weekly OFF` : รบฤet mลฏลพe bรฝt zablokovรกn pouze pล™i 5hodinovรฉm pouลพรญvรกnรญ.\n- `resetAt` passed: รบฤet se automaticky znovu zapne (bez ruฤnรญho opฤ›tovnรฉho povolenรญ).\n\n### Gemini CLI (ZDARMA 180 000/mฤ›sรญc!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepลกรญ hodnota:** Obrovskรก bezplatnรก รบroveลˆ! Pouลพijte ji pล™ed placenรฝmi รบrovnฤ›mi.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n
\n๐Ÿ”‘ Poskytovatelรฉ klรญฤลฏ API\n
\n\n### NVIDIA NIM (BEZPLATNร pล™รญstup pro vรฝvojรกล™e โ€” vรญce neลพ 70 modelลฏ)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Zรญskejte zdarma klรญฤ API (vฤetnฤ› 1000 inferenฤnรญch kreditลฏ)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ NVIDIA NIM:\n - Klรญฤ API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a vรญce neลพ 50 dalลกรญch\n\n**Tip pro profesionรกly:** API kompatibilnรญ s OpenAI โ€“ funguje bez problรฉmลฏ s pล™ekladem formรกtลฏ OmniRoute!\n\n### Hlubokรฉ vyhledรกvรกnรญ\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatnรก รบroveลˆ!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Zรญskejte klรญฤ API (vฤetnฤ› bezplatnรฉ รบrovnฤ›)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionรกly:** Ultrarychlรก inference โ€“ nejlepลกรญ pro kรณdovรกnรญ v reรกlnรฉm ฤase!\n\n### OpenRouter (100+ modelลฏ)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ OpenRouter\n\n**Modely:** Zรญskejte pล™รญstup k vรญce neลพ 100 modelลฏm od vลกech hlavnรญch poskytovatelลฏ prostล™ednictvรญm jedinรฉho klรญฤe API.\n\n
\n๐Ÿ’ฐ Levnรญ poskytovatelรฉ (zรกloลพnรญ)\n
\n\n### GLM-4.7 (Dennรญ reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Zรญskejte klรญฤ API z kรณdovacรญho plรกnu\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API:\n - Poskytovatel: `glm`\n - Klรญฤ API: `your-key`\n\n**Pouลพitรญ:** `glm/glm-4.7`\n\n**Tip pro profesionรกly:** Programovacรญ plรกn nabรญzรญ 3ร— kvรณtu za cenu 1/7! Obnovuje se dennฤ› v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionรกly:** Nejlevnฤ›jลกรญ varianta pro dlouhรฝ kontext (1 milion tokenลฏ)!\n\n### Kimi K2 (pauลกรกlnรญ poplatek 9 dolarลฏ mฤ›sรญฤnฤ›)\n\n1. Odebรญrat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `kimi/kimi-latest`\n\n**Tip pro profesionรกly:** Fixnรญch 9 $/mฤ›sรญc za 10 milionลฏ tokenลฏ = efektivnรญ nรกklady 0,90 $/1 milion!\n\n
\n๐Ÿ†“ BEZPLATNร poskytovatelรฉ (nouzovรฉ zรกlohovรกnรญ)\n
\n\n### iFlow (5 BEZPLATNรCH modelลฏ pล™es OAuth)\n\n```bash\nDashboard โ†’ Connect iFlow\nโ†’ iFlow OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kรณdem zaล™รญzenรญ)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n๐ŸŽจ Vytvoล™te kombinace\n
\n\n### Pล™รญklad 1: Maximalizace pล™edplatnรฉho โ†’ Levnรฉ zรกlohovรกnรญ\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Pล™รญklad 2: Pouze zdarma (nulovรฉ nรกklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n๐Ÿ”ง Integrace s rozhranรญm pล™รญkazovรฉho ล™รกdku\n
\n\n### IDE kurzoru\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jednรญm kliknutรญm pouลพijte strรกnku **Nรกstroje CLI** na ล™รญdicรญm panelu nebo ruฤnฤ› upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Moลพnost 1 โ€“ Dashboard (doporuฤeno):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Moลพnost 2 โ€“ Manuรกlnรญ รบprava:** รšprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznรกmka:** OpenClaw funguje pouze s lokรกlnรญm OmniRoute. Mรญsto `localhost` pouลพijte `127.0.0.1` , abyste se vyhnuli problรฉmลฏm s rozliลกenรญm IPv6.\n\n### Cline / Pokraฤovat / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Pล™idรกnรญ OmniRoute jako vlastnรญho poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvoล™te/upravte `opencode.json` v koล™enovรฉm adresรกล™i projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` pล™idejte jakรฝkoli model dostupnรฝ ve vaลกem koncovรฉm bodu OmniRoute `/v1/models` . Pouลพijte formรกt `provider/model-id` z vaลกeho dashboardu OmniRoute.\n\n---\n\n## ๐Ÿ› ล˜eลกenรญ problรฉmลฏ\n\n
\nKliknutรญm rozbalรญte prลฏvodce ล™eลกenรญm problรฉmลฏ\n
\n\n**\"Jazykovรฝ model neposkytoval zprรกvy\"**\n\n- Kvรณta poskytovatele vyฤerpรกna โ†’ Zkontrolujte sledovรกnรญ kvรณt na ล™รญdicรญm panelu\n- ล˜eลกenรญ: Pouลพijte zรกloลพnรญ kombinovanou variantu nebo pล™ejdฤ›te na levnฤ›jลกรญ รบroveลˆ\n\n**Omezenรญ rychlosti**\n\n- Kvรณta pล™edplatnรฉho vyฤerpรกna โ†’ Pล™echod na GLM/MiniMax\n- Pล™idat kombo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vyprลกela**\n\n- Automaticky aktualizovรกno sluลพbou OmniRoute\n- Pokud problรฉmy pล™etrvรกvajรญ: Ovlรกdacรญ panel โ†’ Poskytovatel โ†’ Znovu pล™ipojit\n\n**Vysokรฉ nรกklady**\n\n- Zkontrolujte statistiky vyuลพitรญ v sekci Nรกstฤ›nka โ†’ Nรกklady\n- Pล™epnout primรกrnรญ model na GLM/MiniMax\n- Pro nekritickรฉ รบlohy pouลพijte bezplatnou รบroveลˆ (Gemini CLI, iFlow).\n\n**Porty ล™รญdicรญho panelu/API jsou nesprรกvnรฉ**\n\n- `PORT` je kanonickรฝ zรกkladnรญ port (a standardnฤ› port API)\n- `API_PORT` pล™episuje pouze posluchaฤ API kompatibilnรญ s OpenAI.\n- `DASHBOARD_PORT` pล™episuje pouze posluchaฤ dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaลกi veล™ejnou URL adresu ล™รญdicรญho panelu (pro zpฤ›tnรก volรกnรญ OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ovฤ›ล™te, zda `BASE_URL` odkazuje na vaลกi spuลกtฤ›nou instanci.\n- Ovฤ›ล™te, zda `CLOUD_URL` odkazuje na vรกลก oฤekรกvanรฝ cloudovรฝ koncovรฝ bod.\n- Udrลพujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na stranฤ› serveru.\n\n**Prvnรญ pล™ihlรกลกenรญ nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud nenรญ nastaveno, zรกloลพnรญ heslo je `123456`\n\n**ลฝรกdnรฉ protokoly poลพadavkลฏ**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test pล™ipojenรญ ukazuje โ€žNeplatnรฉโ€œ pro poskytovatele kompatibilnรญ s OpenAI**\n\n- Mnoho poskytovatelลฏ nezpล™รญstupลˆuje koncovรฝ bod `/models`\n- OmniRoute v1.0.6+ zahrnuje zรกloลพnรญ ovฤ›ล™enรญ pomocรญ dokonฤenรญ chatu\n- Zajistฤ›te, aby zรกkladnรญ URL adresa obsahovala pล™รญponu `/v1`\n\n### ๐Ÿ” OAuth na vzdรกlenรฉm serveru\n\n\n\n\n> **โš ๏ธ Dลฏleลพitรฉ pro uลพivatele, kteล™รญ provozujรญ OmniRoute na VPS, Dockeru nebo jakรฉmkoli vzdรกlenรฉm serveru**\n\n#### Proฤ selhรกvรก OAuth v rozhranรญ CLI Antigravity / Gemini na vzdรกlenรฝch serverech?\n\nPoskytovatelรฉ rozhranรญ CLI **Antigravity** a **Gemini** pouลพรญvajรญ **Google OAuth 2.0** . Google vyลพaduje, aby se `redirect_uri` v toku OAuth pล™esnฤ› shodoval s jednรญm z pล™edregistrovanรฝch URI v konzoli Google Cloud Console aplikace.\n\nPล™ihlaลกovacรญ รบdaje OAuth, kterรฉ jsou souฤรกstรญ OmniRoute, jsou registrovรกny **pouze pro `localhost`** . Kdyลพ pล™istupujete k OmniRoute na vzdรกlenรฉm serveru (napล™. `https://omniroute.myserver.com` ), Google odmรญtne ovฤ›ล™enรญ pomocรญ:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### ล˜eลกenรญ: Nakonfigurujte si vlastnรญ pล™ihlaลกovacรญ รบdaje OAuth\n\nV Google Cloud Console je potล™eba vytvoล™it **ID klienta OAuth 2.0** s URI vaลกeho serveru.\n\n#### Krok za krokem\n\n**1. Otevล™ete konzoli Google Cloud**\n\nPล™ejdฤ›te na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvoล™te novรฉ ID klienta OAuth 2.0**\n\n- Kliknฤ›te na **โ€ž+ Vytvoล™it pล™ihlaลกovacรญ รบdajeโ€œ** โ†’ **โ€žID klienta OAuthโ€œ**\n- Typ aplikace: **โ€žWebovรก aplikaceโ€œ**\n- Nรกzev: cokoli chcete (napล™. `OmniRoute Remote` )\n\n**3. Pล™idejte autorizovanรฉ URI pro pล™esmฤ›rovรกnรญ**\n\nDo pole **โ€žAutorizovanรฉ identifikรกtory URI pro pล™esmฤ›rovรกnรญโ€œ** pล™idejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraฤte `your-server.com` domรฉnou nebo IP adresou vaลกeho serveru (v pล™รญpadฤ› potล™eby uveฤte i port, napล™. `http://45.33.32.156:20128/callback` ).\n\n**4. Uloลพte a zkopรญrujte pล™ihlaลกovacรญ รบdaje**\n\nPo vytvoล™enรญ Google zobrazรญ **ID klienta** a **tajnรฝ kรณd klienta** .\n\n**5. Nastavenรญ promฤ›nnรฝch prostล™edรญ**\n\nVe vaลกem souboru `.env` (nebo promฤ›nnรฝch prostล™edรญ Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu pล™ipojit**\n\nล˜รญdicรญ panel โ†’ Poskytovatelรฉ โ†’ Antigravity (nebo Gemini CLI) โ†’ OAuth\n\nGoogle nynรญ bude sprรกvnฤ› pล™esmฤ›rovรกvat na `https://your-server.com/callback` .\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nPokud si teฤ nechcete nastavovat vlastnรญ pล™ihlaลกovacรญ รบdaje, mลฏลพete stรกle pouลพรญt **ruฤnรญ postup pro URL** :\n\n1. OmniRoute otevรญrรก autorizaฤnรญ URL od Googlu\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru).\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe (i kdyลพ se strรกnka nenaฤte)\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute.\n5. Kliknฤ›te na **โ€žPล™ipojitโ€œ**\n\n> To funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na to, zda se naฤetla pล™esmฤ›rovacรญ strรกnka.\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nChcete-li zรญskat pล™รญstup k pล™ihlaลกovacรญm รบdajลฏm bez vlastnรญ konfigurace, mลฏลพete pouลพรญt nรกsledujรญcรญ postup:\n\n1. OmniRoute otevล™e URL autorizace Google\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru)\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute\n5. Kliknฤ›te na **โ€žPล™ipojit\"**\n\n> Toto ล™eลกenรญ funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na naฤtenรญ pล™esmฤ›rovacรญ strรกnky.\n\n---\n\n## ๐Ÿ› ๏ธ Technologickรฝ stack\n\n
\nKliknutรญm rozbalรญte podrobnosti o technologickรฉm stacku\n
\n\n- **Runtime** : Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ **nenรญ podporovรกn** โ€” nativnรญ binรกrnรญ soubory `better-sqlite3` jsou nekompatibilnรญ)\n- **Jazyk** : TypeScript 5.9 โ€” **100% TypeScript** napล™รญฤ `src/` a `open-sse/` ( `any` v zรกkladnรญch modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databรกze** : LowDB (JSON) + SQLite (stav domรฉny + protokoly proxy + audit MCP + rozhodnutรญ o smฤ›rovรกnรญ)\n- **Schรฉmata** : Zod (validace I/O nรกstrojลฏ MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamovรกnรญ** : Udรกlosti odeslanรฉ serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klรญฤe + autorizace s rozsahem MCP\n- **Testovรกnรญ** : Node.js test runner + Vitest (900+ testลฏ vฤetnฤ› unit, integraฤnรญch, E2E)\n- **CI/CD** : Akce GitHubu (automatickรฉ publikovรกnรญ v npm + Docker Hub pล™i vydรกnรญ)\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **Balรญฤek** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistiฤ, exponenciรกlnรญ odstavenรญ, ochrana proti hromลฏm, faleลกnรฉ TLS, automatickรฉ kombinovanรฉ samoopravovรกnรญ\n\n---\n\n## ๐Ÿ“– Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uลพivatelskรก pล™รญruฤka](docs/USER_GUIDE.md) | Poskytovatelรฉ, kombinace, integrace CLI, nasazenรญ |\n| [Referenฤnรญ informace k API](docs/API_REFERENCE.md) | Vลกechny koncovรฉ body s pล™รญklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nรกstrojลฏ MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamovรกnรญ, sprรกva รบloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorovรฉ bodovรกnรญ, balรญฤky reลพimลฏ, samolรฉฤba |\n| [Odstraลˆovรกnรญ problรฉmลฏ](docs/TROUBLESHOOTING.md) | Bฤ›ลพnรฉ problรฉmy a jejich ล™eลกenรญ |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a internรญ prvky systรฉmu |\n| [Pล™ispรญvรกnรญ](CONTRIBUTING.md) | Nastavenรญ a pokyny pro vรฝvoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpeฤnostnรญ zรกsady](SECURITY.md) | Hlรกลกenรญ zranitelnostรญ a bezpeฤnostnรญ postupy |\n| [Nasazenรญ virtuรกlnรญho poฤรญtaฤe](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletnรญ prลฏvodce: Nastavenรญ virtuรกlnรญho poฤรญtaฤe + nginx + Cloudflare |\n| [Galerie funkcรญ](docs/FEATURES.md) | Vizuรกlnรญ prohlรญdka ล™รญdicรญho panelu se snรญmky obrazovky |\n| [Kontrolnรญ seznam vydรกnรญ](docs/RELEASE_CHECKLIST.md) | Kroky ovฤ›ล™enรญ pล™ed vydรกnรญm |\n\n---\n\n## ๐Ÿ—บ๏ธ Plรกn\n\nOmniRoute mรก **v plรกnu vรญce neลพ 210 funkcรญ** v nฤ›kolika fรกzรญch vรฝvoje. Zde jsou klรญฤovรฉ oblasti:\n\n| Kategorie | Plรกnovanรฉ funkce | Hlavnรญ body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| ๐Ÿง  **Smฤ›rovรกnรญ a inteligence** | 25+ | Smฤ›rovรกnรญ s nejniลพลกรญ latencรญ, smฤ›rovรกnรญ zaloลพenรฉ na tagech, kontrola kvรณt pล™ed vรฝstupem, vรฝbฤ›r รบฤtu P2C |\n| ๐Ÿ”’ **Zabezpeฤenรญ a dodrลพovรกnรญ pล™edpisลฏ** | 20+ | Zpevnฤ›nรญ SSRF, maskovรกnรญ pล™ihlaลกovacรญch รบdajลฏ, limit rychlosti pro kaลพdรฝ koncovรฝ bod, stanovenรญ rozsahu klรญฤลฏ pro sprรกvu |\n| ๐Ÿ“Š **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledovรกnรญ kvรณt v reรกlnรฉm ฤase, sledovรกnรญ nรกkladลฏ podle modelu |\n| ๐Ÿ”„ **Integrace poskytovatelลฏ** | 20+ | Dynamickรฝ registr modelลฏ, doba zchlazenรญ poskytovatelลฏ, Codex pro vรญce รบฤtลฏ, analรฝza kvรณt Copilota |\n| โšก **Vรฝkon** | 15+ | Dvojitรก vrstva mezipamฤ›ti, mezipamฤ›ลฅ vรฝzev, mezipamฤ›ลฅ odpovฤ›dรญ, udrลพovรกnรญ streamovรกnรญ, dรกvkovรฉ API |\n| ๐ŸŒ **Ekosystรฉm** | 10+ | WebSocket API, horkรฉ opฤ›tovnรฉ naฤรญtรกnรญ konfigurace, distribuovanรฉ รบloลพiลกtฤ› konfigurace, komerฤnรญ reลพim |\n\n### ๐Ÿ”œ Jiลพ brzy\n\n- ๐Ÿ”— **Integrace OpenCode** โ€” Nativnรญ podpora poskytovatelลฏ pro IDE kรณdovรกnรญ s AI v OpenCode\n- ๐Ÿ”— **Integrace TRAE** โ€” Plnรก podpora vรฝvojovรฉho rรกmce TRAE pro umฤ›lou inteligenci\n- ๐Ÿ“ฆ **Dรกvkovรฉ API** โ€” Asynchronnรญ dรกvkovรฉ zpracovรกnรญ hromadnรฝch poลพadavkลฏ\n- ๐ŸŽฏ **Smฤ›rovรกnรญ na zรกkladฤ› tagลฏ** โ€” Smฤ›rovรกnรญ poลพadavkลฏ na zรกkladฤ› vlastnรญch tagลฏ a metadat\n- ๐Ÿ’ฐ **Strategie nejniลพลกรญch nรกkladลฏ** โ€“ Automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n> ๐Ÿ“ รšplnรฉ specifikace funkcรญ jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobnรฝch specifikacรญ)\n\n---\n\n## ๐Ÿ‘ฅ Pล™ispฤ›vatelรฉ\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Pล™ispฤ›vatelรฉ](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak pล™ispฤ›t\n\n1. Vytvoล™enรญ forku repozitรกล™e\n2. Vytvoล™te si vlastnรญ vฤ›tev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrฤte zmฤ›ny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do vฤ›tve ( `git push origin feature/amazing-feature` )\n5. Otevล™รญt ลพรกdost o zmฤ›ny (pull request)\n\nPodrobnรฉ pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydรกnรญ novรฉ verze\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Hvฤ›zdnรก historie\n\n## Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## ๐Ÿ™ Podฤ›kovรกnรญ\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** โ€“ pลฏvodnรญmu projektu, kterรฝ inspiroval tento fork. OmniRoute stavรญ na tomto neuvฤ›ล™itelnรฉm zรกkladu s dalลกรญmi funkcemi, multimodรกlnรญmi API a kompletnรญm pล™epsรกnรญm TypeScriptu.\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€“ pลฏvodnรญ implementaci Go, kterรก inspirovala tento JavaScriptovรฝ port.\n\n---\n\n## ๐Ÿ“„ Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n
\n Vytvoล™eno s โค๏ธ pro vรฝvojรกล™e, kteล™รญ programujรญ 24 hodin dennฤ›, 7 dnรญ v tรฝdnu\n
\n

omniroute.online

\n
\n\n"}, "a12622b3d816fc9357293474e8366becae95cc25": {"t": 1785764467.8171098, "n": 91323, "h": "44323280802cfd73", "c": "# ๐Ÿš€ OmniRoute โ€” Bezplatnรก brรกna umฤ›lรฉ inteligence\n\n### Nikdy nepล™estรกvejte s kรณdovรกnรญm. Chytrรฉ smฤ›rovรกnรญ k **BEZPLATNรM a levnรฝm modelลฏm AI** s automatickรฝm pล™epรญnรกnรญm mezi zรกloลพnรญmi systรฉmy.\n\n_Vรกลก univerzรกlnรญ API proxy โ€“ jeden endpoint, vรญce neลพ 44 poskytovatelลฏ, nulovรฉ vรฝpadky. Nynรญ s orchestracรญ agentลฏ **MCP a A2A** ._\n\n**Dokonฤenรญ chatu โ€ข Vklรกdรกnรญ โ€ข Generovรกnรญ obrรกzkลฏ โ€ข Video โ€ข Hudba โ€ข Audio โ€ข Zmฤ›na poล™adรญ โ€ข **Vyhledรกvรกnรญ na webu** โ€ข MCP server โ€ข A2A protokol โ€ข 100% TypeScript**\n\n---\n\n
\n
\n

\"verze\"Docker\"Licence\"\"Webovรฉ\"WhatsApp\"

\n

๐ŸŒ Webovรฉ strรกnky โ€ข ๐Ÿš€ Rychlรฝ start โ€ข ๐Ÿ’ก Funkce โ€ข ๐Ÿ“– Dokumentace โ€ข ๐Ÿ’ฐ Cenรญk โ€ข ๐Ÿ’ฌ WhatsApp

\n
\n\n๐ŸŒ **Dostupnรฉ v:** ๐Ÿ‡บ๐Ÿ‡ธ [Angliฤtina](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n### ๐Ÿ†• What's New in v3.0.0\n\n| Area | Change |\n| --- | --- |\n| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| โœ… **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |\n| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| ๐ŸŒ **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| ๐Ÿ”ง **926 Tests** | Full test suite passes with 0 failures |\n\n\n\n### ๐Ÿ†• What's New in v3.0.0\n\n| Area | Change |\n| --- | --- |\n| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |\n| โœ… **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |\n| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |\n| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |\n| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |\n| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |\n| ๐ŸŒ **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |\n| ๐Ÿ”ง **926 Tests** | Full test suite passes with 0 failures |\n\n---\n\n\n\n## ๐Ÿ–ผ๏ธ Hlavnรญ ovlรกdacรญ panel\n\n
\"ล˜รญdicรญ
\n\n---\n\n## ๐Ÿ“ธ Nรกhled ล™รญdicรญho panelu\n\n
\nKliknutรญm zobrazรญte snรญmky obrazovky z ล™รญdicรญho panelu\n
\n\n| Strana | Snรญmek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelรฉ** | ![Poskytovatelรฉ](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdravรญ** | ![Zdravรญ](docs/screenshots/04-health.png) |\n| **Pล™ekladatel** | ![Pล™ekladatel](docs/screenshots/05-translator.png) |\n| **Nastavenรญ** | ![Nastavenรญ](docs/screenshots/06-settings.png) |\n| **Nรกstroje CLI** | ![Nรกstroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly pouลพรญvรกnรญ** | ![Pouลพรญvรกnรญ](docs/screenshots/08-usage.png) |\n| **Koncovรฉ body** | ![Koncovรฉ body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### ๐Ÿค– Bezplatnรฝ poskytovatel umฤ›lรฉ inteligence pro vaลกe oblรญbenรฉ programรกtory\n\n_Pล™ipojte libovolnรฝ nรกstroj IDE nebo CLI s umฤ›lou inteligencรญ pล™es OmniRoute โ€” bezplatnou API brรกnu pro neomezenรฉ kรณdovรกnรญ._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\"OpenClaw\"
OpenClaw
โญ 205 tisรญc 		\"NanoBot\"
NanoBot
โญ 20,9 tisรญc 		\"PicoClaw\"
PicoClaw
โญ 14,6 tisรญc 		\"ZeroClaw\"
ZeroClaw
โญ 9,9 tisรญc 		\"ลฝeleznรฝ
ลฝeleznรฝ drรกp
โญ 2,1 tisรญce
\"OpenCode\"
OpenCode
โญ 106 tisรญc 		\"Codex
Codex CLI
โญ 60,8 tisรญc 		\"Claude
Claude Code
โญ 67,3 tisรญc 		\"Gemini
Gemini CLI
โญ 94,7 tisรญc 		\"Kilo
Kilo kรณd
โญ 15,5 tisรญc
\n\n๐Ÿ“ก Vลกichni agenti se pล™ipojujรญ pล™es http://localhost:20128/v1 nebo http://cloud.omniroute.online/v1 โ€” jedna konfigurace, neomezenรฉ modely a kvรณty\n\n---\n\n## ๐Ÿค” Proฤ OmniRoute?\n\n**Pล™estaลˆte plรฝtvat penฤ›zi a narรกลพet na limity:**\n\n- Kvรณta pล™edplatnรฉho vyprลกรญ kaลพdรฝ mฤ›sรญc\n- Limity rychlosti vรกm zabrรกnรญ v kรณdovรกnรญ\n- Drahรก API (20โ€“50 USD/mฤ›sรญc na poskytovatele)\n- Ruฤnรญ pล™epรญnรกnรญ mezi poskytovateli\n\n**OmniRoute to ล™eลกรญ:**\n\n- โœ… **Maximalizujte pล™edplatnรฉ** โ€“ Sledujte kvรณtu, vyuลพijte kaลพdou ฤรกstku pล™ed resetovรกnรญm\n- โœ… **Automatickรฉ zรกloลพnรญ** โ€“ Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma, ลพรกdnรฉ vรฝpadky\n- โœ… **Vรญce รบฤtลฏ** โ€“ Round-robin mezi รบฤty u jednotlivรฝch poskytovatelลฏ\n- โœ… **Univerzรกlnรญ** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakรฝmkoli nรกstrojem CLI\n\n---\n\n## ๐Ÿ“ง Podpora\n\n> ๐Ÿ’ฌ **Pล™idejte se k naลกรญ komunitฤ›!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Zรญskejte pomoc, sdรญlejte tipy a buฤte v obraze.\n\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problรฉmy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitnรญ skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Pล™ispรญvรกnรญ** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevล™ete ลพรกdost o pล™รญspฤ›vek nebo si vyberte `good first issue`\n- **Pลฏvodnรญ projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Hlรกsรญte chybu?\n\nPล™i otevรญrรกnรญ problรฉmu spusลฅte pล™รญkaz system-info a pล™iloลพte vygenerovanรฝ soubor:\n\n```bash\nnpm run system-info\n```\n\nTรญm se vygeneruje soubor `system-info.txt` s verzรญ Node.js, verzรญ OmniRoute, podrobnostmi o operaฤnรญm systรฉmu, nainstalovanรฝmi nรกstroji CLI (iflow, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systรฉmovรฝmi balรญฤky โ€“ vลกe, co potล™ebujeme k rychlรฉ reprodukci vaลกeho problรฉmu. Soubor pล™iloลพte pล™รญmo k vaลกemu problรฉmu na GitHubu.\n\n---\n\n## ๐Ÿ”„ Jak to funguje\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ Co ล™eลกรญ OmniRoute โ€” 30 skuteฤnรฝch problรฉmลฏ a pล™รญpadลฏ pouลพitรญ\n\n> **Kaลพdรฝ vรฝvojรกล™ pouลพรญvajรญcรญ nรกstroje umฤ›lรฉ inteligence se s tฤ›mito problรฉmy setkรกvรก dennฤ›.** OmniRoute byl vytvoล™en tak, aby je vลกechny vyล™eลกil โ€“ od pล™ekroฤenรญ nรกkladลฏ po regionรกlnรญ bloky, od nefunkฤnรญch tokลฏ OAuth aลพ po operace s protokoly a sledovatelnost v podniku.\n\n
\n๐Ÿ’ธ 1. โ€žPlatรญm si drahรฉ pล™edplatnรฉ, ale stรกle mฤ› ruลกรญ limityโ€œ\n
\n\nVรฝvojรกล™i platรญ za Claude Pro, Codex Pro nebo GitHub Copilot 20โ€“200 dolarลฏ mฤ›sรญฤnฤ›. I pล™i platbฤ› mรก kvรณta strop โ€“ 5 hodin pouลพรญvรกnรญ, tรฝdennรญ limity nebo limity rychlosti za minutu. Uprostล™ed kรณdovacรญ relace poskytovatel pล™estane reagovat a vรฝvojรกล™ ztrรกcรญ plynulost a produktivitu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Inteligentnรญ ฤtyล™รบrovลˆovรก zรกloลพnรญ sluลพba** โ€“ Pokud dojde kvรณta pล™edplatnรฉho, โ€‹โ€‹automaticky se pล™esmฤ›ruje na API klรญฤ โ†’ Levnรฉ โ†’ Zdarma bez manuรกlnรญho zรกsahu\n- **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** โ€“ Zobrazuje spotล™ebu tokenลฏ v reรกlnรฉm ฤase s odpoฤรญtรกvรกnรญm resetovรกnรญ (5 hodin, dennฤ›, tรฝdnฤ›)\n- **Podpora vรญce รบฤtลฏ** โ€“ Vรญce รบฤtลฏ u jednoho poskytovatele s automatickรฝm pล™epรญnรกnรญm โ€“ kdyลพ jeden dojde, pล™epne se na dalลกรญ\n- **Vlastnรญ kombinace** โ€” Pล™izpลฏsobitelnรฉ zรกloลพnรญ ล™etฤ›zce se 6 strategiemi vyvaลพovรกnรญ (fill-first, round robin, P2C, nรกhodnรฉ, nejmรฉnฤ› pouลพรญvanรฉ, nรกkladovฤ› optimalizovanรฉ)\n- **Codex Business Quotas** โ€” Sledovรกnรญ kvรณt pracovnรญho prostoru firmy/tรฝmu pล™รญmo v dashboardu\n\n
\n๐Ÿ”Œ 2. โ€žPotล™ebuji pouลพรญt vรญce poskytovatelลฏ, ale kaลพdรฝ mรก jinรฉ APIโ€œ\n
\n\nOpenAI pouลพรญvรก jeden formรกt, Claude (Anthropic) jinรฝ a Gemini jeลกtฤ› tล™etรญ. Pokud chce vรฝvojรกล™ testovat modely od rลฏznรฝch poskytovatelลฏ nebo mezi nimi pล™echรกzet, musรญ pล™ekonfigurovat SDK, zmฤ›nit koncovรฉ body a vypoล™รกdat se s nekompatibilnรญmi formรกty. Vlastnรญ poskytovatelรฉ (FriendLI, NIM) majรญ nestandardnรญ koncovรฉ body modelลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sjednocenรฝ koncovรฝ bod** โ€” Jeden `http://localhost:20128/v1` slouลพรญ jako proxy pro vลกech 44+ poskytovatelลฏ.\n- **Pล™eklad formรกtu** โ€” Automatickรฝ a transparentnรญ: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Sanitizace odpovฤ›dรญ** โ€” Odstraลˆuje nestandardnรญ pole ( `x_groq` , `usage_breakdown` , `service_tier` ), kterรก poruลกujรญ OpenAI SDK v1.83+\n- **Normalizace rolรญ** โ€” Pล™evรกdรญ `developer` โ†’ `system` pro poskytovatele bez OpenAI; `system` โ†’ `user` pro GLM/ERNIE\n- **Extrakce tagลฏ Think** โ€” Extrahuje bloky `` z modelลฏ, jako je DeepSeek R1, do standardizovanรฉho `reasoning_content`\n- **Strukturovanรฝ vรฝstup pro Gemini** โ€” `json_schema` โ†’ automatickรก konverze `responseMimeType` / `responseSchema`\n- **Vรฝchozรญ hodnota `stream` je `false`** โ€“ Odpovรญdรก specifikaci OpenAI, ฤรญmลพ se zabrรกnรญ neoฤekรกvanรฉmu SSE v Python/Rust/Go SDK.\n\n
\n๐ŸŒ 3. โ€žMลฏj poskytovatel AI blokuje mลฏj region/zemiโ€œ\n
\n\nPoskytovatelรฉ jako OpenAI/Codex blokujรญ pล™รญstup z urฤitรฝch geografickรฝch oblastรญ. Uลพivatelรฉ se bฤ›hem pล™ipojenรญ OAuth a API dostรกvajรญ k chybรกm jako `unsupported_country_region_territory` . To je obzvlรกลกtฤ› frustrujรญcรญ pro vรฝvojรกล™e z rozvojovรฝch zemรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **3รบrovลˆovรก konfigurace proxy** โ€“ Konfigurovatelnรก proxy na 3 รบrovnรญch: globรกlnรญ (veลกkerรฝ provoz), pro jednotlivรฉ poskytovatele (pouze jeden poskytovatel) a pro jednotlivรฉ pล™ipojenรญ/klรญฤ\n- **Barevnฤ› kรณdovanรฉ odznaky proxy** โ€“ Vizuรกlnรญ indikรกtory: ๐ŸŸข globรกlnรญ proxy, ๐ŸŸก proxy poskytovatele, ๐Ÿ”ต proxy pล™ipojenรญ, vลพdy zobrazujรญcรญ IP adresu\n- **Vรฝmฤ›na tokenลฏ OAuth prostล™ednictvรญm proxy** โ€“ tok OAuth takรฉ prochรกzรญ pล™es proxy, ฤรญmลพ se ล™eลกรญ `unsupported_country_region_territory`\n- **Testy pล™ipojenรญ pล™es proxy** โ€“ Testy pล™ipojenรญ pouลพรญvajรญ nakonfigurovanรฝ proxy (jiลพ ลพรกdnรฉ pล™รญmรฉ obchรกzenรญ)\n- **Podpora SOCKS5** โ€” Plnรก podpora proxy SOCKS5 pro odchozรญ smฤ›rovรกnรญ\n- **TLS Fingerprint Spoofing** โ€” Otisk prstu TLS podobnรฝ prohlรญลพeฤi pomocรญ `wreq-js` pro obchรกzenรญ detekce botลฏ\n- **๐Ÿ” Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** โ€” Zmฤ›nรญ poล™adรญ zรกhlavรญ a polรญ v tฤ›le serveru tak, aby odpovรญdala nativnรญm binรกrnรญm podpisลฏm v CLI, ฤรญmลพ drasticky sniลพuje riziko nahlaลกovรกnรญ รบฤtu. IP adresa proxy je zachovรกna โ€” zรญskรกte souฤasnฤ› stealth **i** maskovรกnรญ IP adresy.\n\n
\n๐Ÿ†“ 4. โ€žChci pouลพรญvat umฤ›lou inteligenci pro kรณdovรกnรญ, ale nemรกm penรญzeโ€œ\n
\n\nNe kaลพdรฝ si mลฏลพe dovolit zaplatit 20โ€“200 dolarลฏ mฤ›sรญฤnฤ› za pล™edplatnรฉ AI. Studenti, vรฝvojรกล™i z rozvรญjejรญcรญch se zemรญ, amatรฉล™i a freelanceล™i potล™ebujรญ pล™รญstup ke kvalitnรญm modelลฏm za nulovou cenu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vestavฤ›nรญ poskytovatelรฉ bezplatnรฉ รบrovnฤ›** โ€” Nativnรญ podpora pro 100% bezplatnรฉ poskytovatele: iFlow (5 neomezenรฝch modelลฏ pล™es OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezenรฉ modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisรญc tokenลฏ/mฤ›sรญc zdarma)\n- **Ollama Cloud** โ€” Cloudovฤ› hostovanรฉ modely Ollama na `api.ollama.com` s bezplatnou รบrovnรญ โ€žLight usageโ€œ; pouลพijte prefix `ollamacloud/`\n- **Kombinace pouze zdarma** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = 0 $/mฤ›sรญc s nulovรฝmi prostoji\n- **NVIDIA NIM Free Access** โ€” ~40 RPM developerskรฝ pล™รญstup k vรญce neลพ 70 modelลฏm na build.nvidia.com (pล™echod z kreditลฏ na ฤistรฉ limity rychlosti)\n- **Strategie optimalizace nรกkladลฏ** โ€“ Strategie smฤ›rovรกnรญ, kterรก automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n
\n๐Ÿ”’ 5. โ€žPotล™ebuji chrรกnit svou brรกnu umฤ›lรฉ inteligence pล™ed neoprรกvnฤ›nรฝm pล™รญstupemโ€œ\n
\n\nPล™i zpล™รญstupnฤ›nรญ brรกny umฤ›lรฉ inteligence sรญti (LAN, VPS, Docker) mลฏลพe kdokoli s adresou spotล™ebovat tokeny/kvรณtu vรฝvojรกล™e. Bez ochrany jsou API zranitelnรก vลฏฤi zneuลพitรญ, prompt injection a dalลกรญmu zneuลพitรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sprรกva klรญฤลฏ API** โ€“ generovรกnรญ, rotace a vymezovรกnรญ rozsahu pro kaลพdรฉho poskytovatele s vyhrazenou strรกnkou `/dashboard/api-manager`\n- **Oprรกvnฤ›nรญ na รบrovni modelu** โ€“ Omezenรญ klรญฤลฏ API na konkrรฉtnรญ modely ( `openai/*` , zรกstupnรฉ znaky) pomocรญ pล™epรญnaฤe Povolit vลกe/Omezit\n- **Ochrana koncovรฝch bodลฏ API** โ€“ Vyลพaduje klรญฤ pro `/v1/models` a blokuje konkrรฉtnรญ poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** โ€” Vลกechny trasy dashboardu chrรกnฤ›nรฉ middlewarem `withAuth` + tokeny CSRF\n- **Omezovaฤ rychlosti** โ€” Omezovรกnรญ rychlosti na IP s konfigurovatelnรฝmi okny\n- **Filtrovรกnรญ IP adres** โ€” Seznam povolenรฝch/blokovanรฝch adres pro ล™รญzenรญ pล™รญstupu\n- **Ochrana proti vklรกdรกnรญ vรฝzev** โ€“ Sanitizace proti ลกkodlivรฝm vzorcลฏm vรฝzev\n- **ล ifrovรกnรญ AES-256-GCM** โ€“ pล™ihlaลกovacรญ รบdaje jsou v klidovรฉm stavu ลกifrovรกny\n\n
\n๐Ÿ›‘ 6. โ€žMลฏj poskytovatel selhal a jรก ztratil/a programovacรญ tokโ€œ\n
\n\nPoskytovatelรฉ umฤ›lรฉ inteligence se mohou stรกt nestabilnรญmi, vracet chyby 5xx nebo dosรกhnout doฤasnรฝch limitลฏ rychlosti. Pokud je vรฝvojรกล™ zรกvislรฝ na jedinรฉm poskytovateli, je jeho prรกce pล™eruลกena. Bez jistiฤลฏ mลฏลพe opakovanรฉ pokusy vรฉst k pรกdu aplikace.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Jistiฤ pro kaลพdรฝ model** โ€“ Automatickรฉ otevรญrรกnรญ/zavรญrรกnรญ s konfigurovatelnรฝmi prahovรฝmi hodnotami a dobou ochlazovรกnรญ (Zavล™eno/Otevล™eno/Poloviฤnรญ otevล™enรญ), rozsah definovanรฝ pro kaลพdรฝ model, aby se zabrรกnilo kaskรกdovรกnรญ blokลฏ\n- **Exponenciรกlnรญ odklad** โ€” Progresivnรญ zpoลพdฤ›nรญ opakovรกnรญ\n- **Anti-Thundering Herd** โ€” ochrana Mutex + semafor proti soubฤ›ลพnรฝm bouล™รญm s opakovanรฝmi pokusy\n- **Kombinovanรฉ zรกloลพnรญ ล™etฤ›zce** โ€“ Pokud primรกrnรญ poskytovatel selลพe, automaticky se propadne ล™etฤ›zcem bez zรกsahu.\n- **Kombinovanรฝ jistiฤ** โ€“ Automaticky deaktivuje selhรกvajรญcรญho poskytovatele v rรกmci kombinovanรฉho ล™etฤ›zce\n- **Dashboard stavu** โ€” Monitorovรกnรญ provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti, latence p50/p95/p99\n\n
\n๐Ÿ”ง 7. โ€žKonfigurace kaลพdรฉho nรกstroje umฤ›lรฉ inteligence je zdlouhavรก a opakujรญcรญ seโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Kaลพdรฝ nรกstroj potล™ebuje jinou konfiguraci (API endpoint, klรญฤ, model). Pล™ekonfigurovรกnรญ pล™i zmฤ›nฤ› poskytovatele nebo modelu je ztrรกta ฤasu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel nรกstrojลฏ CLI** โ€” Vyhrazenรก strรกnka s nastavenรญm jednรญm kliknutรญm pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generรกtor konfigurace GitHub Copilot** โ€“ Generuje `chatLanguageModels.json` pro VS Code s hromadnรฝm vรฝbฤ›rem modelu\n- **Prลฏvodce zavรกdฤ›nรญm** โ€“ 4krokovรฉ nastavenรญ pro zaฤรญnajรญcรญ uลพivatele\n- **Jeden koncovรฝ bod, vลกechny modely** โ€“ jednou nakonfigurujte `http://localhost:20128/v1` a zรญskejte pล™รญstup k vรญce neลพ 44 poskytovatelลฏm\n\n
\n๐Ÿ”‘ 8. โ€žSprรกva OAuth tokenลฏ od vรญce poskytovatelลฏ je pekloโ€œ\n
\n\nClaude Code, Codex, Gemini CLI, Copilot โ€“ vลกechny pouลพรญvajรญ OAuth 2.0 s tokeny s vyprลกenรญm platnosti. Vรฝvojรกล™i se musรญ neustรกle znovu autentizovat, ล™eลกit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdรกlenรฝch serverech. Obzvlรกลกtฤ› problematickรฝ je OAuth v LAN/VPS.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Automatickรก aktualizace tokenลฏ** โ€“ Tokeny OAuth se obnovujรญ na pozadรญ pล™ed vyprลกenรญm platnosti.\n- **Vestavฤ›nรฝ OAuth 2.0 (PKCE)** โ€“ Automatickรฝ tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow\n- **Multi-Account OAuth** โ€” Vรญce รบฤtลฏ na poskytovatele prostล™ednictvรญm extrakce tokenลฏ JWT/ID\n- **OAuth LAN/Remote Fix** โ€” Detekce privรกtnรญ IP adresy pro `redirect_uri` + manuรกlnรญ reลพim URL pro vzdรกlenรฉ servery\n- **OAuth Behind Nginx** โ€” Pouลพรญvรก `window.location.origin` pro kompatibilitu s reverznรญ proxy\n- **Prลฏvodce vzdรกlenรฝm OAuth** โ€“ Podrobnรฝ nรกvod k pล™ihlaลกovacรญm รบdajลฏm Google Cloud na VPS/Dockeru\n\n
\n๐Ÿ“Š 9. โ€žNevรญm, kolik utrรกcรญm ani kdeโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ vรญce placenรฝch poskytovatelลฏ, ale nemajรญ jednotnรฝ pล™ehled o vรฝdajรญch. Kaลพdรฝ poskytovatel mรก svลฏj vlastnรญ fakturaฤnรญ panel, ale neexistuje ลพรกdnรฝ konsolidovanรฝ pล™ehled. Mohou se hromadit neoฤekรกvanรฉ nรกklady.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard pro analรฝzu nรกkladลฏ** โ€“ Sledovรกnรญ nรกkladลฏ na token a sprรกva rozpoฤtu pro kaลพdรฉho poskytovatele\n- **Rozpoฤtovรฉ limity na รบroveลˆ** โ€“ Strop vรฝdajลฏ na รบroveลˆ, kterรฝ spouลกtรญ automatickรฝ zรกloลพnรญ reลพim\n- **Konfigurace cen podle modelu** โ€“ Konfigurovatelnรฉ ceny podle modelu\n- **Statistiky pouลพitรญ pro kaลพdรฝ klรญฤ API** โ€” Poฤet poลพadavkลฏ a ฤasovรฉ razรญtko poslednรญho pouลพitรญ pro kaลพdรฝ klรญฤ\n- **Analytickรฝ panel** โ€“ Statistickรฉ karty, graf vyuลพitรญ modelu, tabulka poskytovatelลฏ s mรญrou รบspฤ›ลกnosti a latencรญ\n\n
\n๐Ÿ› 10. โ€žNedokรกลพu diagnostikovat chyby a problรฉmy ve volรกnรญ umฤ›lรฉ inteligence.โ€œ\n
\n\nKdyลพ volรกnรญ selลพe, vรฝvojรกล™ nevรญ, zda se jednalo o limit rychlosti, vyprลกelรฝ token, ลกpatnรฝ formรกt nebo chybu poskytovatele. Fragmentovanรฉ protokoly napล™รญฤ rลฏznรฝmi terminรกly. Bez sledovatelnosti je ladฤ›nรญ metodou pokus-omyl.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel jednotnรฝch protokolลฏ** โ€“ 4 karty: Protokoly poลพadavkลฏ, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlรญลพeฤ protokolลฏ konzole** โ€” Prohlรญลพeฤ protokolลฏ v reรกlnรฉm ฤase ve stylu terminรกlu s barevnฤ› kรณdovanรฝmi รบrovnฤ›mi, automatickรฝm posouvรกnรญm, vyhledรกvรกnรญm a filtrovรกnรญm\n- **Protokoly proxy SQLite** โ€“ trvalรฉ protokoly, kterรฉ pล™eลพijรญ restart serveru\n- **Pล™ekladaฤskรฉ hล™iลกtฤ›** โ€” 4 reลพimy ladฤ›nรญ: Hล™iลกtฤ› (pล™eklad formรกtu), Tester chatu (okruลพnรญ), Testovacรญ stลฏl (dรกvkovรฝ), ลฝivรฝ monitor (v reรกlnรฉm ฤase)\n- **Telemetrie poลพadavkลฏ** โ€” latence p50/p95/p99 + trasovรกnรญ X-Request-Id\n- **Souborovรฉ protokolovรกnรญ s rotacรญ** โ€“ Konzolovรฝ interceptor zachycuje vลกe do protokolu JSON s rotacรญ na zรกkladฤ› velikosti\n- **Zprรกva o systรฉmovรฝch informacรญch** โ€” pล™รญkaz `npm run system-info` vygeneruje `system-info.txt` s kompletnรญm popisem vaลกeho prostล™edรญ (verze uzlu, verze OmniRoute, operaฤnรญ systรฉm, nรกstroje CLI, stav Dockeru/PM2). Pล™iloลพte jej pล™i hlรกลกenรญ problรฉmลฏ pro okamลพitรฉ tล™รญdฤ›nรญ.\n\n
\n๐Ÿ—๏ธ 11. โ€žNasazenรญ a รบdrลพba brรกny je sloลพitรกโ€œ\n
\n\nInstalace, konfigurace a รบdrลพba AI proxy v rลฏznรฝch prostล™edรญch (lokรกlnรญ, VPS, Docker, cloud) je pracnรก. Problรฉmy, jako jsou pevnฤ› zakรณdovanรฉ cesty, `EACCES` u adresรกล™ลฏ, konflikty portลฏ a multiplatformnรญ sestavenรญ, pล™ispรญvajรญ k obtรญลพรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **npm globรกlnรญ instalace** โ€” `npm install -g omniroute && omniroute` โ€” hotovo\n- **Docker Multi-Platform** โ€” AMD64 + nativnรญ ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** โ€” `base` (bez nรกstrojลฏ CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopovรก aplikace Electron** โ€” Nativnรญ aplikace pro Windows/macOS/Linux se systรฉmovou liลกtou, automatickรฝm spuลกtฤ›nรญm a offline reลพimem\n- **Reลพim rozdฤ›lenรฝch portลฏ** โ€“ API a ล™รญdicรญ panel na samostatnรฝch portech pro pokroฤilรฉ scรฉnรกล™e (reverznรญ proxy, sรญลฅovรกnรญ kontejnerลฏ)\n- **Cloud Sync** โ€“ Konfigurace synchronizace mezi zaล™รญzenรญmi pomocรญ Cloudflare Workers\n- **Zรกlohy databรกzรญ** โ€” Automatickรฉ zรกlohovรกnรญ, obnovenรญ, export a import vลกech nastavenรญ\n\n
\n๐ŸŒ 12. โ€žRozhranรญ je pouze v angliฤtinฤ› a mลฏj tรฝm nemluvรญ anglickyโ€œ\n
\n\nTรฝmy v neanglicky mluvรญcรญch zemรญch, zejmรฉna v Latinskรฉ Americe, Asii a Evropฤ›, se potรฝkajรญ s rozhranรญmi pouze v angliฤtinฤ›. Jazykovรฉ bariรฉry sniลพujรญ mรญru pล™ijetรญ a zvyลกujรญ chyby v konfiguraci.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard i18n โ€” 30 jazykลฏ** โ€” Vลกech 500+ klรกves je pล™eloลพeno vฤetnฤ› arabลกtiny, bulharลกtiny, dรกnลกtiny, nฤ›mฤiny, ลกpanฤ›lลกtiny, finลกtiny, francouzลกtiny, hebrejลกtiny, hindลกtiny, maฤarลกtiny, indonรฉลกtiny, italลกtiny, japonลกtiny, korejลกtiny, malajลกtiny, holandลกtiny, norลกtiny, polลกtiny, portugalลกtiny (PT/BR), rumunลกtiny, ruลกtiny, slovenลกtiny, ลกvรฉdลกtiny, thajลกtiny, ukrajinลกtiny, vietnamลกtiny, ฤรญnลกtiny, filipรญnลกtiny a angliฤtiny\n- **Podpora RTL** โ€“ Podpora psanรญ zprava doleva pro arabลกtinu a hebrejลกtinu\n- **Vรญcejazyฤnรฉ soubory README** โ€” 30 kompletnรญch pล™ekladลฏ dokumentace\n- **Vรฝbฤ›r jazyka** โ€” Ikona glรณbu v zรกhlavรญ pro pล™epรญnรกnรญ v reรกlnรฉm ฤase\n\n
\n๐Ÿ”„ 13. โ€žPotล™ebuji vรญc neลพ jen chat โ€“ potล™ebuji vloลพenรฉ soubory, obrรกzky, zvuk.โ€œ\n
\n\nUmฤ›lรก inteligence nenรญ jen dokonฤovรกnรญ chatu. Vรฝvojรกล™i potล™ebujรญ generovat obrรกzky, pล™episovat zvuk, vytvรกล™et embeddedy pro RAG, mฤ›nit poล™adรญ dokumentลฏ a moderovat obsah. Kaลพdรฉ API mรก jinรฝ koncovรฝ bod a formรกt.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vklรกdรกnรญ** โ€” `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generovรกnรญ obrรกzkลฏ** โ€” `/v1/images/generations` s 10 poskytovateli a vรญce neลพ 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Pล™evod textu na video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Pล™evod textu na hudbu** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Pล™epis zvuku** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Pล™evod textu na ล™eฤ** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a dalลกรญ stรกvajรญcรญ poskytovatelรฉ\n- **Moderovรกnรญ** โ€” `/v1/moderations` โ€” Kontroly bezpeฤnosti obsahu\n- **Zmฤ›na poล™adรญ** โ€” `/v1/rerank` โ€” Zmฤ›na poล™adรญ relevance dokumentu\n- **Responses API** โ€” Plnรก podpora `/v1/responses` pro Codex\n\n
\n๐Ÿงช 14. โ€žNemรกm zpลฏsob, jak testovat a porovnรกvat kvalitu napล™รญฤ modely.โ€œ\n
\n\nVรฝvojรกล™i chtฤ›jรญ vฤ›dฤ›t, kterรฝ model je pro jejich pล™รญpad pouลพitรญ nejlepลกรญ โ€“ kรณd, pล™eklad, uvaลพovรกnรญ โ€“ ale ruฤnรญ porovnรกvรกnรญ je pomalรฉ. Neexistujรญ ลพรกdnรฉ integrovanรฉ nรกstroje pro vyhodnocovรกnรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Hodnocenรญ LLM** โ€” Testovรกnรญ Golden setu s 10 pล™edinstalovanรฝmi pล™รญpady zahrnujรญcรญmi pozdravy, matematiku, geografii, generovรกnรญ kรณdu, dodrลพovรกnรญ JSON, pล™eklad, markdown, odmรญtnutรญ bezpeฤnostnรญch poลพadavkลฏ\n- **4 strategie shody** โ€” `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovacรญ lavice pro pล™ekladatelskรฉ hล™iลกtฤ›** โ€” Dรกvkovรฉ testovรกnรญ s vรญce vstupy a oฤekรกvanรฝmi vรฝstupy, porovnรกnรญ napล™รญฤ poskytovateli\n- **Tester chatu** โ€” Kompletnรญ okruลพnรญ cesta s vizuรกlnรญm vykreslovรกnรญm odpovฤ›dรญ\n- **ลฝivรฝ monitor** โ€” Stream vลกech poลพadavkลฏ prochรกzejรญcรญch proxy serverem v reรกlnรฉm ฤase\n\n
\n๐Ÿ“ˆ 15. โ€žPotล™ebuji ลกkรกlovat bez ztrรกty vรฝkonuโ€œ\n
\n\nS rostoucรญm objemem poลพadavkลฏ generujรญ stejnรฉ otรกzky bez uklรกdรกnรญ do mezipamฤ›ti duplicitnรญ nรกklady. Bez idempotence duplicitnรญ poลพadavky plรฝtvajรญ zpracovรกnรญm. Je nutnรฉ dodrลพovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sรฉmantickรก mezipamฤ›ลฅ** โ€” Dvouvrstvรก mezipamฤ›ลฅ (signatura + sรฉmantika) sniลพuje nรกklady a latenci\n- **Idempotence poลพadavku** โ€” 5s deduplikaฤnรญ okno pro identickรฉ poลพadavky\n- **Detekce limitu rychlosti** โ€“ sledovรกnรญ otรกฤek za minutu (RPM), minimรกlnรญ mezera a maximรกlnรญ soubฤ›ลพnรฉ sledovรกnรญ pro kaลพdรฉho poskytovatele\n- **Upravitelnรฉ limity rychlosti** โ€” Konfigurovatelnรฉ vรฝchozรญ hodnoty v Nastavenรญ โ†’ Odolnost s perzistencรญ\n- **Mezipamฤ›ลฅ pro ovฤ›ล™enรญ klรญฤลฏ API** โ€” tล™รญvrstvรก mezipamฤ›ลฅ pro vรฝkon produkฤnรญho prostล™edรญ\n- **Dashboard s telemetriรญ** โ€“ latence p50/p95/p99, statistiky mezipamฤ›ti, dostupnost\n\n
\n๐Ÿค– 16. โ€žChci mรญt chovรกnรญ modelลฏ globรกlnฤ› pod kontrolouโ€œ\n
\n\nVรฝvojรกล™i, kteล™รญ chtฤ›jรญ vลกechny odpovฤ›di v urฤitรฉm jazyce, se specifickรฝm tรณnem nebo chtฤ›jรญ omezit tokeny pro uvaลพovรกnรญ. Konfigurace tรฉto funkce v kaลพdรฉm nรกstroji/poลพadavku je nepraktickรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vloลพenรญ systรฉmovรฉho prompt** โ€“ Globรกlnรญ prompt aplikovanรฝ na vลกechny poลพadavky\n- **Validace rozpoฤtu Thinking** โ€” ล˜รญzenรญ alokace tokenลฏ na poลพadavek (prลฏchozรญ, automatickรฉ, vlastnรญ, adaptivnรญ)\n- **6 strategiรญ smฤ›rovรกnรญ** โ€“ Globรกlnรญ strategie, kterรฉ urฤujรญ, jak jsou poลพadavky distribuovรกny\n- **Smฤ›rovaฤ se zรกstupnรฝmi znaky** โ€” vzory `provider/*` dynamicky smฤ›rujรญ k libovolnรฉmu poskytovateli\n- **Pล™epรญnรกnรญ povolenรญ/zakรกzรกnรญ kombinacรญ** โ€“ Pล™epรญnรกnรญ kombinacรญ pล™รญmo z ล™รญdicรญho panelu\n- **Pล™epรญnรกnรญ poskytovatele** โ€“ Povolenรญ/zakรกzรกnรญ vลกech pล™ipojenรญ pro poskytovatele jednรญm kliknutรญm\n- **Blokovanรญ poskytovatelรฉ** โ€“ Vylouฤenรญ konkrรฉtnรญch poskytovatelลฏ ze seznamu `/v1/models`\n\n
\n๐Ÿงฐ 17. โ€žPotล™ebuji nรกstroje MCP jako prvotล™รญdnรญ produktovรฉ funkce.โ€œ\n
\n\nMnoho bran umฤ›lรฉ inteligence odhaluje MCP pouze jako skrytรฝ implementaฤnรญ detail. Tรฝmy potล™ebujรญ viditelnou a spravovatelnou operaฤnรญ vrstvu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- MCP se zobrazuje v navigaci na ล™รญdicรญm panelu a na kartฤ› protokolu koncovรฉho bodu.\n- Vyhrazenรก strรกnka pro sprรกvu MCP s procesy, nรกstroji, rozsahy a auditem\n- Vestavฤ›nรฝ rychlรฝ start pro `omniroute --mcp` a onboarding klienta\n\n
\n๐Ÿง  18. โ€žPotล™ebuji orchestraci A2A se synchronizacรญ a cestami รบloh streamu.โ€œ\n
\n\nPracovnรญ postupy agentลฏ vyลพadujรญ jak pล™รญmรฉ odpovฤ›di, tak dlouhodobรฉ streamovanรฉ provรกdฤ›nรญ s kontrolou ลพivotnรญho cyklu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Koncovรฝ bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamovรกnรญ SSE s ลกรญล™enรญm stavu terminรกlu\n- Rozhranรญ API ลพivotnรญho cyklu รบloh pro `tasks/get` a `tasks/cancel`\n\n
\n๐Ÿ›ฐ๏ธ 19. โ€žPotล™ebuji skuteฤnรฝ stav procesu MCP, ne odhadovanรฝ stav.โ€œ\n
\n\nProvoznรญ tรฝmy potล™ebujรญ vฤ›dฤ›t, zda je MCP skuteฤnฤ› aktivnรญ, nejen zda je API dosaลพitelnรฉ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Soubor bฤ›hovรฉho heartbeatu s PID, ฤasovรฝmi razรญtky, transportem, poฤtem nรกstrojลฏ a reลพimem rozsahu\n- API stavu MCP kombinujรญcรญ prezenฤnรญ signรกl a nedรกvnou aktivitu\n- Karty stavu uลพivatelskรฉho rozhranรญ pro zobrazenรญ aktuรกlnosti procesลฏ/provozuschopnosti/prezenฤnรญho signรกlu\n\n
\n๐Ÿ“‹ 20. โ€žPotล™ebuji auditovatelnรฉ provedenรญ nรกstroje MCPโ€œ\n
\n\nKdyลพ nรกstroje mฤ›nรญ konfiguraci nebo spouลกtฤ›jรญ operaฤnรญ akce, tรฝmy potล™ebujรญ forenznรญ sledovatelnost.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Protokolovรกnรญ auditu pro volรกnรญ nรกstrojลฏ MCP s podporou SQLite\n- Filtruje podle nรกstroje, รบspฤ›chu/neรบspฤ›chu, klรญฤe API a strรกnkovรกnรญ\n- Tabulka auditu dashboardu + koncovรฉ body statistik pro automatizaci\n\n
\n๐Ÿ” 21. โ€žPotล™ebuji omezenรก oprรกvnฤ›nรญ MCP pro kaลพdou integraci.โ€œ\n
\n\nRลฏznรญ klienti by mฤ›li mรญt pล™รญstup ke kategoriรญm nรกstrojลฏ s nejniลพลกรญmi oprรกvnฤ›nรญmi.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- 9 detailnรญch MCP sond pro kontrolovanรฝ pล™รญstup k nรกstrojลฏm\n- Vynucenรญ rozsahu a viditelnost v uลพivatelskรฉm rozhranรญ sprรกvy MCP\n- Bezpeฤnรก vรฝchozรญ poloha pro provoznรญ nรกstroje\n\n
\nโš™๏ธ 22. โ€žPotล™ebuji provoznรญ kontroly bez nutnosti pล™esouvรกnรญโ€œ\n
\n\nTรฝmy potล™ebujรญ rychlรฉ zmฤ›ny v bฤ›hovรฉm prostล™edรญ bฤ›hem incidentลฏ nebo nรกkladovรฝch udรกlostรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Pล™epnฤ›te aktivaci komba pล™รญmo z ล™รญdicรญho panelu MCP\n- Pouลพรญvejte profily odolnosti z pล™eddefinovanรฝch balรญฤkลฏ zรกsad\n- Resetujte stav jistiฤe ze stejnรฉho ovlรกdacรญho panelu\n\n
\n๐Ÿ”„ 23. โ€žPotล™ebuji ลพivรฝ pล™ehled o ลพivotnรญm cyklu รบkolลฏ A2A a jejich zruลกenรญ.โ€œ\n
\n\nBez pล™ehledu o ลพivotnรญm cyklu je obtรญลพnรฉ tล™รญdit incidenty รบkolลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Vรฝpis/filtrovรกnรญ รบkolลฏ podle stรกtu/dovednosti s strรกnkovรกnรญm\n- Podrobnรฝ pล™ehled metadat รบloh, udรกlostรญ a artefaktลฏ\n- Koncovรฝ bod zruลกenรญ รบlohy a akce uลพivatelskรฉho rozhranรญ s potvrzenรญm\n\n
\n๐ŸŒŠ 24. โ€žPotล™ebuji metriky aktivnรญho streamu pro A2A zรกtฤ›ลพโ€œ\n
\n\nStreamovacรญ pracovnรญ postupy vyลพadujรญ provoznรญ pล™ehled o soubฤ›ลพnosti a ลพivรฝch pล™ipojenรญch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- ฤŒรญtaฤe aktivnรญch streamลฏ integrovanรฉ do stavu A2A\n- ฤŒasovรฉ razรญtko poslednรญho รบkolu a poฤty pro jednotlivรฉ stavy\n- Karty A2A dashboardu pro monitorovรกnรญ provozu v reรกlnรฉm ฤase\n\n
\n๐Ÿชช 25. โ€žPotล™ebuji standardnรญ vyhledรกvรกnรญ agentลฏ pro klientyโ€œ\n
\n\nExternรญ klienti a orchestratoล™i potล™ebujรญ pro onboarding strojovฤ› ฤitelnรก metadata.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazenรฉ v uลพivatelskรฉm rozhranรญ pro sprรกvu\n- API pro stav A2A zahrnuje metadata pro zjiลกลฅovรกnรญ pro automatizaci\n\n
\n๐Ÿงญ 26. โ€žPotล™ebuji v uลพivatelskรฉm rozhranรญ produktu zjistitelnost protokolu.โ€œ\n
\n\nPokud uลพivatelรฉ nemohou objevit protokolovรฉ povrchy, kvalita pล™ijetรญ a podpory klesรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Strรกnka Konsolidovanรฉ **koncovรฉ body** s kartami pro koncovรฉ body Proxy, MCP, A2A a API\n- Pล™epรญnรกnรญ stavu inline sluลพby (Online/Offline) pro MCP a A2A\n- Odkazy z pล™ehledu na vyhrazenรฉ karty pro sprรกvu\n\n
\n๐Ÿงช 27. โ€žPotล™ebuji komplexnรญ ovฤ›ล™enรญ protokolu se skuteฤnรฝmi klienty.โ€œ\n
\n\nSimulovanรฉ testy nestaฤรญ k ovฤ›ล™enรญ kompatibility protokolu pล™ed vydรกnรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sada E2E, kterรก spouลกtรญ aplikaci a pouลพรญvรก skuteฤnรฝ transport klienta MCP SDK.\n- Klientskรฉ testy A2A pro toky zjiลกลฅovรกnรญ, odesรญlรกnรญ, streamovรกnรญ, naฤรญtรกnรญ a zruลกenรญ\n- Kล™รญลพovรก kontrola tvrzenรญ oproti API pro audit MCP a รบkoly A2A\n\n
\n๐Ÿ“ก 28. โ€žPotล™ebuji jednotnou pozorovatelnost napล™รญฤ vลกemi rozhranรญmiโ€œ\n
\n\nRozdฤ›lenรญ pozorovatelnosti podle protokolu vytvรกล™รญ slepรก mรญsta a delลกรญ MTTR.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรฉ dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie poลพadavkลฏ napล™รญฤ vrstvami OpenAI, MCP a A2A\n- Provoznรญ API pro stav a automatizaci\n\n
\n๐Ÿ’ผ 29. โ€žPotล™ebuji jeden runtime pro proxy + nรกstroje + orchestraci agentลฏโ€œ\n
\n\nSpouลกtฤ›nรญ mnoha samostatnรฝch sluลพeb zvyลกuje provoznรญ nรกklady a poฤet poruch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Proxy, MCP server a A2A server kompatibilnรญ s OpenAI v jednom balรญฤku\n- Sdรญlenรฉ ovฤ›ล™ovรกnรญ, odolnost, รบloลพiลกtฤ› dat a pozorovatelnost\n- Konzistentnรญ model politik napล™รญฤ vลกemi interakฤnรญmi plochami\n\n
\n๐Ÿš€ 30. โ€žPotล™ebuji agentskรฉ pracovnรญ postupy bez slepenรญ kรณdu.โ€œ\n
\n\nTรฝmy ztrรกcejรญ rychlost pล™i spojovรกnรญ vรญce ad-hoc sluลพeb a skriptลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรก strategie koncovรฝch bodลฏ pro klienty a agenty\n- Vestavฤ›nรก uลพivatelskรก rozhranรญ pro sprรกvu protokolลฏ a cesty pro ovฤ›ล™ovรกnรญ kouล™e\n- Zรกklady pล™ipravenรฉ pro produkฤnรญ prostล™edรญ (zabezpeฤenรญ, protokolovรกnรญ, odolnost, zรกlohovรกnรญ)\n\n### Pล™รญklady hernรญch plรกnลฏ (integrovanรฉ pล™รญpady uลพitรญ)\n\n**Pล™รญruฤka A: Maximalizace placenรฉho pล™edplatnรฉho + levnรฉ zรกlohovรกnรญ**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Pล™รญruฤka B: Kรณdovacรญ stack s nulovรฝmi nรกklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Pล™รญruฤka C: Nonstop zรกloลพnรญ ล™etฤ›zec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Pล™รญruฤka D: Operace agentลฏ s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Zaฤnฤ›te zdarma โ€” Nulovรฉ nรกklady na konfiguraci\n\n> Nastavte si kรณdovรกnรญ s umฤ›lou inteligencรญ bฤ›hem nฤ›kolika minut za **0 $/mฤ›sรญc** . Propojte tyto bezplatnรฉ รบฤty a vyuลพijte vestavฤ›nou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelรฉ odemฤeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Pล™ipojenรญ **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€“ **neomezenฤ›** |\n| 2 | Pล™ipojenรญ k **iFlow** (Google OAuth) | kimi-k2-myลกlenรญ, qwen3-coder-plus, deepseek-r1... โ€” **neomezenฤ›** |\n| 3 | Pล™ipojenรญ **Qwen** (kรณd zaล™รญzenรญ) | qwen3-coder-plus, qwen3-coder-flash... โ€” **neomezenฤ›** |\n| 4 | Pล™ipojenรญ **rozhranรญ pล™รญkazovรฉho ล™รกdku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180 000 GBP/mฤ›sรญc zdarma** |\n| 5 | `/dashboard/combos` โ†’ ล ablona **Free Stack (0 $)** | Automatickรฉ zaล™azenรญ vลกech bezplatnรฝch poskytovatelลฏ do routingu |\n\n**V libovolnรฉm IDE/CLI naveฤte:** `http://localhost:20128/v1` ยท Klรญฤ API: `any-string` ยท Hotovo.\n\n> **Volitelnรฉ doplลˆkovรฉ krytรญ (takรฉ zdarma):** Groq API klรญฤ (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelลฏ), Cerebras (1 milion tok/den).\n\n## โšก Rychlรฝ start\n\n### 1) Nainstalujte a spusลฅte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uลพivatelรฉ pnpm:** Po instalaci spusลฅte `pnpm approve-builds -g` , abyste povolili nativnรญ skripty pro sestavenรญ vyลพadovanรฉ programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard se otevรญrรก na `http://localhost:20128` a zรกkladnรญ URL API je `http://localhost:20128/v1` .\n\n| Pล™รญkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuลกtฤ›nรญ serveru ( `PORT=20128` , API a dashboard na stejnรฉm portu) |\n| `omniroute --port 3000` | Nastavte kanonickรฝ/API port na 3000 |\n| `omniroute --mcp` | Spuลกtฤ›nรญ MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevรญrat prohlรญลพeฤ automaticky |\n| `omniroute --help` | Zobrazit nรกpovฤ›du |\n\nVolitelnรฝ reลพim s rozdฤ›lenรฝm portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Pล™ipojte poskytovatele a vytvoล™te si klรญฤ API\n\n1. Otevล™ete Dashboard โ†’ `Providers` a pล™ipojte alespoลˆ jednoho poskytovatele (klรญฤ OAuth nebo API).\n2. Otevล™ete Dashboard โ†’ `Endpoints` a vytvoล™te API klรญฤ.\n3. (Volitelnรฉ) Otevล™ete Dashboard โ†’ `Combos` a nastavte zรกloลพnรญ ล™etฤ›zec.\n\n### 3) Nasmฤ›rujte svลฏj kรณdovacรญ nรกstroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilnรญmi s OpenAI.\n\n### 4) Povolenรญ a ovฤ›ล™enรญ protokolลฏ (v2.0)\n\n**MCP (pro operace ล™รญzenรฉ nรกstroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak pล™ipojte svรฉho MCP klienta pล™es `stdio` a otestujte nรกstroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovnรญ postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ovฤ›ล™te vลกe od zaฤรกtku do konce (doporuฤeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ovฤ›ล™uje skuteฤnรฉ toky klientลฏ MCP a A2A v porovnรกnรญ se spuลกtฤ›nou aplikacรญ.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute je k dispozici jako veล™ejnรฝ obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlรฝ bฤ›h:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostล™edรญ:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Pouลพรญvรกnรญ Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | ล tรญtek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovฤ›jลกรญ stabilnรญ verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuรกlnรญ verze |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktopovรก aplikace โ€“ offline a vลพdy zapnutรก\n\n> ๐Ÿ†• **NOVINKA!** OmniRoute je nynรญ k dispozici jako **nativnรญ desktopovรก aplikace** pro Windows, macOS a Linux.\n\nSpusลฅte OmniRoute jako samostatnou desktopovou aplikaci โ€“ pro lokรกlnรญ modely nenรญ potล™eba ลพรกdnรฝ terminรกl, prohlรญลพeฤ ani internet. Aplikace zaloลพenรก na platformฤ› Electron obsahuje:\n\n- ๐Ÿ–ฅ๏ธ **Nativnรญ okno** โ€” Vyhrazenรฉ okno aplikace s integracรญ do systรฉmovรฉ liลกty\n- ๐Ÿ”„ **Automatickรฉ spuลกtฤ›nรญ** โ€” Spuลกtฤ›nรญ OmniRoute po pล™ihlรกลกenรญ do systรฉmu\n- ๐Ÿ”” **Nativnรญ oznรกmenรญ** โ€“ Zรญskejte upozornฤ›nรญ na vyฤerpรกnรญ kvรณty nebo problรฉmy s poskytovateli\n- โšก **Instalace jednรญm kliknutรญm** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline reลพim** โ€” Funguje plnฤ› offline s pล™iloลพenรฝm serverem\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systรฉmovรฝ zรกsobnรญk\n\nPo minimalizaci se OmniRoute nachรกzรญ v systรฉmovรฉ liลกtฤ› a nabรญzรญ rychlรฉ akce:\n\n- Otevล™รญt ล™รญdicรญ panel\n- Zmฤ›nit port serveru\n- Ukonฤit aplikaci\n\n๐Ÿ“– รšplnรก dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pล™ehled cen\n\n| รšroveลˆ | Poskytovatel | Nรกklady | Obnovenรญ kvรณty | Nejlepลกรญ pro |\n| --------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **๐Ÿ’ณ Pล˜EDPLATNร‰** | Claude Code (profesionรกl) | 20 dolarลฏ mฤ›sรญฤnฤ› | 5 hodin + tรฝdnฤ› | Jiลพ pล™ihlรกลกen/a k odbฤ›ru |\n| Kodex (Plus/Pro) | 20โ€“200 USD/mฤ›sรญc | 5 hodin + tรฝdnฤ› | Uลพivatelรฉ OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisรญc mฤ›sรญฤnฤ› + 1 tisรญc dennฤ› | Kaลพdรฝ! |\n| GitHub Copilot | 10โ€“19 USD/mฤ›sรญc | Mฤ›sรญฤnรญ | Uลพivatelรฉ GitHubu |\n| **๐Ÿ”‘ KLรฤŒ API** | NVIDIA NIM | **ZDARMA** (vรฝvoj navลพdy) | ~40 ot./min | 70+ otevล™enรฝch modelลฏ |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ na svฤ›tฤ› |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisรญc otรกฤek za minutu | Ultrarychlรก lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | ลฝรกdnรฝ | Nejlepลกรญ zdลฏvodnฤ›nรญ ceny a kvality |\n| xAI Grok-4 Rychlรฝ | **0,20/0,50 USD za 1 milion** ๐Ÿ†• | ลฝรกdnรฝ | Nejrychlejลกรญ + volรกnรญ nรกstroje, ultranรญzkรฉ |\n| xAI Grok-4 (standardnรญ) | 0,20/1,50 USD za 1 milion ๐Ÿ†• | ลฝรกdnรฝ | Vlajkovรก loฤ Reasoning od xAI |\n| Mistral | Zkuลกebnรญ verze zdarma + placenรฉ | Omezenรก sazba | Evropskรก umฤ›lรก inteligence |\n| OpenRouter | Platba za pouลพitรญ | ลฝรกdnรฝ | Vรญce neลพ 100 modelลฏ agregovรกno. |\n| **๐Ÿ’ฐ LEVNร‰** | GLM-5 (pล™es Z.AI) ๐Ÿ†• | 0,5 USD/1 milion | Dennฤ› v 10:00 | Vรฝstup 128 tisรญc obrazovรฝch bodลฏ, nejnovฤ›jลกรญ vlajkovรก loฤ |\n| GLM-4.7 | 0,6 USD/1 milion | Dennฤ› v 10:00 | Zรกloha rozpoฤtu |\n| MiniMax M2.5 ๐Ÿ†• | Vstup 0,3 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | รšvaha + agentnรญ รบkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | Nejlevnฤ›jลกรญ varianta |\n| Kimi K2.5 (Moonshot API) ๐Ÿ†• | Platba za pouลพitรญ | ลฝรกdnรฝ | Pล™รญmรฝ pล™รญstup k Moonshot API |\n| Kimi K2 | 9 dolarลฏ mฤ›sรญฤnฤ› bez zรกvazkลฏ | 10 milionลฏ tokenลฏ/mฤ›sรญc | Pล™edvรญdatelnรฉ nรกklady |\n| **๐Ÿ†“ ZDARMA** | iFlow | **0 dolarลฏ** | Neomezenรฝ | 5 modelลฏ neomezenฤ› |\n| Qwen | **0 dolarลฏ** | Neomezenรฝ | 4 modely neomezenฤ› |\n| Kiro | **0 dolarลฏ** | Neomezenรฝ | Claude Sonnet/Haiku (tvorce AWS) |\n\n> ๐Ÿ†• **Pล™idรกny novรฉ modely (bล™ezen 2026):** ล™ada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkovรกno na 1143 ms โ€“ o 30 % rychlejลกรญ neลพ Gemini 2.5 Flash), GLM-5 pล™es Z.AI s vรฝstupem 128K, uvaลพovรกnรญ MiniMax M2.5, aktualizovanรฉ ceny DeepSeek V3.2, Kimi K2.5 pล™es Moonshot Direct API.\n\n**๐Ÿ’ก Kombinovanรฝ balรญk za 0 $ โ€” Kompletnรญ bezplatnรก instalace:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\niFlow (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Nulovรฉ nรกklady. Nikdy nepล™estรกvejte s kรณdovรกnรญm.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a vลกechny zรกloลพnรญ reลพimy se provede automaticky โ€“ ลพรกdnรฉ ruฤnรญ pล™epรญnรกnรญ.\n\n---\n\n---\n\n## ๐Ÿ†“ Bezplatnรฉ modely โ€“ Co skuteฤnฤ› zรญskรกte\n\n> Vลกechny nรญลพe uvedenรฉ modely jsou **100% zdarma a nevyลพadujรญ ลพรกdnou kreditnรญ kartu** . OmniRoute mezi nimi automaticky propojรญ trasy, kdyลพ dojde jedna kvรณta โ€“ zkombinujte je vลกechny a zรญskejte tak nerozluฤnou kombinaci za 0 dolarลฏ.\n\n### ๐Ÿ”ต CLAUDE MODELS (pล™es Kiro โ€” AWS Builder ID)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-opus-4.6` | `kr/` | **Neomezenรฝ** | Nejnovฤ›jลกรญ opus od Kira |\n\n### ๐ŸŸข MODELY IFLOW (Bezplatnรฉ OAuth โ€” bez nutnosti platit kreditnรญ kartou)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-plus` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `deepseek-r1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `minimax-m2.1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `kimi-k2` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n\n### ๐ŸŸก MODELY QWEN (Ovฤ›ล™enรญ kรณdu zaล™รญzenรญ)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-next` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `vision-model` | `qw/` | **Neomezenรฝ** | Multimodรกlnรญ (obrรกzky) |\n\n### ๐ŸŸฃ Rozhranรญ GEMINI CLI (Google OAuth)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisรญc tok/mฤ›sรญc** + 1 tisรญc/den | Mฤ›sรญฤnรญ reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisรญc mฤ›sรญฤnฤ› (sdรญlenรฝ bazรฉn) | Vysokรก kvalita |\n\n### โšซ NVIDIA NIM (Bezplatnรฝ klรญฤ API โ€” build.nvidia.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vรฝvojรกล™) | ลฝรกdnรฝ limit tokenลฏ | **~40 ot./min** | Vรญce neลพ 70 modelลฏ; pล™echod na ฤistรฉ limity sazeb v polovinฤ› roku 2025 |\n\nOblรญbenรฉ bezplatnรฉ modely: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct` , `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Bezplatnรฝ klรญฤ API โ€” inference.cerebras.ai)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenลฏ/den** | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ inference LLM na svฤ›tฤ›; dennฤ› se resetuje |\n\nDostupnรฉ zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Bezplatnรฝ API klรญฤ โ€” console.groq.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisรญc otรกฤek za minutu** | 30 ot./min na model | ลฝรกdnรก kreditnรญ karta; limit 429, neรบฤtovรกno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **๐Ÿ’ก Ultimรกtnรญ bezplatnรฝ zรกsobnรญk:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> โ†’ iFlow (5 models, unlimited)\n> โ†’ Qwen (4 models, unlimited)\n> โ†’ Gemini CLI (180K/mo)\n> โ†’ Cerebras (1M tok/day)\n> โ†’ Groq (14.4K req/day)\n> โ†’ NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a uลพ nikdy nebudete platit za umฤ›lou inteligenci.\n\n## ๐ŸŽ™๏ธ Kombinovanรก transkripce zdarma\n\n> Pล™episujte libovolnรฉ audio/video za **0 $** โ€“ Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako zรกloลพnรญ nรกstroj, Groq Whisper jako neomezenรก nouzovรก zรกloha.\n\n| Poskytovatel | Bezplatnรฉ kredity | Nejlepลกรญ model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| ๐ŸŸข **Deepgram** | **200 dolarลฏ zdarma** (registrace) | `nova-3` โ€” nejvyลกลกรญ pล™esnost, vรญce neลพ 30 jazykลฏ | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ต **AssemblyAI** | **50 dolarลฏ zdarma** (registrace) | `universal-3-pro` โ€” kapitoly, sentiment, osobnรญ รบdaje | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ด **Groq** | **Navลพdy zdarma** | `whisper-large-v3` โ€” OpenAI ล epot | 30 ot./min (omezenรก rychlost) |\n\n**Navrhovanรก kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nPak v `/dashboard/media` โ†’ zรกloลพka **Pล™epis** : nahrajte libovolnรฝ zvukovรฝ nebo video soubor โ†’ vyberte kombinovanรฝ koncovรฝ bod โ†’ zรญskejte pล™epis v podporovanรฝch formรกtech.\n\n## ๐Ÿ’ก Klรญฤovรฉ vlastnosti\n\nOmniRoute v2.0 je navrลพen jako operaฤnรญ platforma, nikoli pouze jako proxy pro relรฉ.\n\n### ๐Ÿค– Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dฤ›lรก |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (16 nรกstrojลฏ)** | Nรกstroje IDE/agent prostล™ednictvรญm 3 transportลฏ: stdio, SSE ( `/api/mcp/sse` ), Streamovatelnรฝ HTTP ( `/api/mcp/stream` ) |\n| ๐Ÿค **A2A server (JSON-RPC + SSE)** | Spouลกtฤ›nรญ รบloh mezi agenty se synchronizacรญ a streamovรกnรญm |\n| ๐Ÿงญ **Konsolidovanรก strรกnka koncovรฝch bodลฏ** | Strรกnka pro sprรกvu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| ๐ŸŽš๏ธ **Pล™epรญnaฤe pro povolenรญ/zakรกzรกnรญ sluลพby** | Pล™epรญnaฤe ZAP/VYP pro MCP a A2A s trvalรฝm nastavenรญm (vรฝchozรญ: VYP) |\n| ๐Ÿ›ฐ๏ธ **Srdeฤnรญ tep za bฤ›hu MCP** | Skuteฤnรฝ stav procesu (pid, doba provozuschopnosti, stรกล™รญ heartbeatu, transport, reลพim rozsahu) |\n| ๐Ÿ“‹ **Auditnรญ zรกznam MCP** | Filtrovatelnรฉ protokoly auditu s hodnocenรญm รบspฤ›chu/neรบspฤ›chu a klรญฤovรฝm pล™iล™azenรญm |\n| ๐Ÿ” **Vynucovรกnรญ rozsahu MCP** | 9 podrobnรฝch oprรกvnฤ›nรญ pro ล™รญzenรฝ pล™รญstup k nรกstrojลฏm |\n| ๐Ÿ“ก **Sprรกva ลพivotnรญho cyklu รบkolลฏ A2A** | Seznam/filtrovรกnรญ รบloh, kontrola udรกlostรญ/artefaktลฏ, zruลกenรญ spuลกtฤ›nรฝch รบloh |\n| ๐Ÿ“‹ **Objevenรญ karty agenta** | `/.well-known/agent.json` pro automatickรฉ vyhledรกvรกnรญ klientลฏ |\n| ๐Ÿงช **Testovacรญ postroj Protocol E2E** | Skuteฤnรฉ MCP SDK + toky klientลฏ A2A v `test:protocols:e2e` |\n| โš™๏ธ **Provoznรญ kontroly** | Kombinace pล™epรญnaฤลฏ, pouลพitรญ profilลฏ odolnosti, resetovรกnรญ jistiฤลฏ z jednoho ovlรกdacรญho panelu |\n\n### ๐Ÿง  Smฤ›rovรกnรญ a inteligence\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| ๐ŸŽฏ **Inteligentnรญ ฤtyล™รบrovลˆovรฝ zรกloลพnรญ systรฉm** | Automatickรก trasa: Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma |\n| ๐Ÿ“Š **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** | Poฤet tokenลฏ v reรกlnรฉm ฤase + odpoฤet resetovรกnรญ pro kaลพdรฉho poskytovatele |\n| ๐Ÿ”„ **Pล™eklad formรกtu** | OpenAI โ†” Claude โ†” Gemini โ†” Odpovฤ›di s konverzemi bezpeฤnรฝmi pro schรฉma |\n| ๐Ÿ‘ฅ **Podpora vรญce รบฤtลฏ** | Vรญce รบฤtลฏ na poskytovatele s inteligentnรญm vรฝbฤ›rem |\n| ๐Ÿ”„ **Automatickรก aktualizace tokenลฏ** | Tokeny OAuth se automaticky obnovujรญ pล™i opakovanรฉm pokusu. |\n| ๐ŸŽจ **Vlastnรญ kombinace** | 6 vyvaลพovacรญch strategiรญ + ล™รญzenรญ zรกloลพnรญho ล™etฤ›zce |\n| ๐ŸŒ **Smฤ›rovaฤ se zรกstupnรฝmi znaky** | dynamickรฉ smฤ›rovรกnรญ `provider/*` |\n| ๐Ÿง  **Pล™emรฝลกlenรญ o rozpoฤtovรฝch kontrolรกch** | Limity pro prลฏchozรญ, automatickรฉ, vlastnรญ a adaptivnรญ uvaลพovรกnรญ |\n| ๐Ÿ”€ **Aliasy modelลฏ** | Vestavฤ›nรฉ + vlastnรญ aliasovรกnรญ modelลฏ a bezpeฤnost migrace |\n| โšก **Degradace pozadรญ** | Smฤ›rujte รบlohy na pozadรญ s nรญzkou prioritou na levnฤ›jลกรญ modely |\n| ๐Ÿงช **Chytrรฉ smฤ›rovรกnรญ s ohledem na รบkoly** | Automatickรฝ vรฝbฤ›r modelu podle typu obsahu (kรณdovรกnรญ/vize/analรฝza/sumarizace) |\n| ๐Ÿ’ฌ **Vstล™ikovรกnรญ do systรฉmu** | Globรกlnรญ kontroly chovรกnรญ uplatลˆovanรฉ konzistentnฤ› |\n| ๐Ÿ“„ **Kompatibilita API pro odpovฤ›di** | Plnรก podpora `/v1/responses` pro Codex a pokroฤilรฉ agentickรฉ pracovnรญ postupy |\n\n### ๐ŸŽต Multimodรกlnรญ API\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Generovรกnรญ obrรกzkลฏ** | `/v1/images/generations` s cloudovรฝm a lokรกlnรญm backendem |\n| ๐Ÿ“ **Vloลพenรญ** | `/v1/embeddings` pro vyhledรกvรกnรญ a RAG pipelines |\n| ๐ŸŽค **Pล™epis zvuku** | `/v1/audio/transcriptions` (Whisper a dalลกรญ poskytovatelรฉ) |\n| ๐Ÿ”Š **Pล™evod textu na ล™eฤ** | `/v1/audio/speech` (vรญce enginลฏ/poskytovatelลฏ) |\n| ๐ŸŽฌ **Generovรกnรญ videa** | `/v1/videos/generations` (pracovnรญ postupy ComfyUI + SD WebUI) |\n| ๐ŸŽต **Hudebnรญ generace** | `/v1/music/generations` (pracovnรญ postupy ComfyUI) |\n| ๐Ÿ›ก๏ธ **Moderovรกnรญ** | Bezpeฤnostnรญ kontroly `/v1/moderations` |\n| ๐Ÿ”€ **Zmฤ›na poล™adรญ** | `/v1/rerank` pro hodnocenรญ relevance |\n| ๐Ÿ” **Vyhledรกvรกnรญ na webu** ๐Ÿ†• | `/v1/search` โ€” 5 poskytovatelลฏ (Serper, Brave, Perplexity, Exa, Tavily), vรญce neลพ 6 500 zdarma/mฤ›sรญc, automatickรฉ pล™epnutรญ na zรกloลพnรญ systรฉm, mezipamฤ›ลฅ |\n\n### ๐Ÿ›ก๏ธ Odolnost, bezpeฤnost a sprรกva vฤ›cรญ veล™ejnรฝch\n\n| Funkce | Co to dฤ›lรก |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Jistiฤe** | Vypnutรญ/obnovenรญ pro kaลพdรฝ model s ovlรกdรกnรญm prahovรฝch hodnot |\n| ๐ŸŽฏ **Modely s ohledem na koncovรฉ body** | Vlastnรญ modely deklarujรญ podporovanรฉ koncovรฉ body + formรกt API |\n| ๐Ÿ›ก๏ธ **Stรกdo proti hromลฏm** | Ochrana mutexu a semaforu pล™i udรกlostech opakovรกnรญ/rychlosti |\n| ๐Ÿง  **Sรฉmantickรก + podpisovรก mezipamฤ›ลฅ** | Snรญลพenรญ nรกkladลฏ/latence dรญky dvฤ›ma vrstvรกm mezipamฤ›ti |\n| โšก **ลฝรกdost o idempotenci** | Okno ochrany proti duplikacรญm |\n| ๐Ÿ”’ **Falลกovรกnรญ otiskลฏ prstลฏ pomocรญ TLS** | Otisk TLS podobnรฝ prohlรญลพeฤi โ€“ **sniลพuje detekci botลฏ a nahlaลกovรกnรญ รบฤtลฏ** |\n| ๐Ÿ” **Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** | Shoduje se s nativnรญmi podpisy poลพadavkลฏ CLI โ€“ **sniลพuje riziko zablokovรกnรญ a zรกroveลˆ zachovรกvรก IP adresu proxy** |\n| ๐ŸŒ **Filtrovรกnรญ IP adres** | Ovlรกdรกnรญ seznamu povolenรฝch/blokovanรฝch poloลพek pro odhalenรก nasazenรญ |\n| ๐Ÿ“Š **Upravitelnรฉ limity rychlosti** | Konfigurovatelnรฉ globรกlnรญ/na รบrovni poskytovatele limity s perzistencรญ |\n| ๐Ÿ”‘ **Sprรกva klรญฤลฏ API a stanovenรญ rozsahu** | Bezpeฤnรฉ vydรกvรกnรญ/rotace klรญฤลฏ a kontroly modelu/poskytovatele |\n| ๐Ÿ›ก๏ธ **Chrรกnฤ›nรฉ `/models`** | Volitelnรฉ ovฤ›ล™ovรกnรญ a skrytรญ poskytovatele pro katalog modelลฏ |\n\n### ๐Ÿ“Š Pozorovatelnost a analytika\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| ๐Ÿ“ **ลฝรกdost + protokolovรกnรญ proxy** | รšplnรฉ protokolovรกnรญ poลพadavkลฏ/odpovฤ›dรญ a proxy |\n| ๐Ÿ“‹ **Sjednocenรฝ panel protokolลฏ** | Zobrazenรญ poลพadavkลฏ, proxy, auditu a konzole na jednรฉ strรกnce |\n| ๐Ÿ” **Vyลพรกdat si telemetrii** | Latence p50/p95/p99 a trasovรกnรญ poลพadavkลฏ |\n| ๐Ÿฅ **Panel zdravรญ** | Doba provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti |\n| ๐Ÿ’ฐ **Sledovรกnรญ nรกkladลฏ** | Kontrola rozpoฤtu a pล™ehled o cenรกch pro jednotlivรฉ modely |\n| ๐Ÿ“ˆ **Analytickรฉ vizualizace** | Pล™ehledy vyuลพitรญ modelลฏ/poskytovatelลฏ a zobrazenรญ trendลฏ |\n| ๐Ÿงช **Rรกmec hodnocenรญ** | Testovรกnรญ zlatรฉ sady s konfigurovatelnรฝmi strategiemi shody |\n\n### โ˜๏ธ Nasazenรญ a platforma\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| ๐ŸŒ **Nasazenรญ kdekoli** | Localhost, VPS, Docker, cloudovรก prostล™edรญ |\n| ๐Ÿ’พ **Synchronizace s cloudem** | Synchronizace konfigurace pล™es cloud worker |\n| ๐Ÿ”„ **Zรกlohovรกnรญ/Obnovenรญ** | Toky exportu/importu a obnovy po havรกrii |\n| ๐Ÿง™ **Prลฏvodce nรกstupem** | Prลฏvodce prvnรญm spuลกtฤ›nรญm |\n| ๐Ÿ”ง **Panel nรกstrojลฏ CLI** | Nastavenรญ oblรญbenรฝch kรณdovacรญch nรกstrojลฏ jednรญm kliknutรญm |\n| ๐ŸŽฎ **Modelovรฉ hล™iลกtฤ›** | Otestujte libovolnรฉho poskytovatele/model/koncovรฝ bod z ล™รญdicรญho panelu |\n| ๐Ÿ” **Pล™epรญnaฤ otiskลฏ prstลฏ v pล™รญkazovรฉm ล™รกdku** | Porovnรกvรกnรญ otiskลฏ prstลฏ podle poskytovatele v Nastavenรญ > Zabezpeฤenรญ |\n| ๐ŸŒ **i18n (30 jazykลฏ)** | Plnรก jazykovรก podpora dashboardu a dokumentace s psanรญm zprava doleva |\n| ๐Ÿ“‚ **Adresรกล™ vlastnรญch dat** | Pล™epsรกnรญ `DATA_DIR` pro umรญstฤ›nรญ รบloลพiลกtฤ› |\n\n### Hlubokรฝ pohled na funkce\n\n#### Chytrรก zรกloลพnรญ funkce s praktickou kontrolou nรกkladลฏ\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyลพ selลพe kvรณta, rychlost nebo stav, OmniRoute automaticky pล™ejde k dalลกรญmu kandidรกtovi bez nutnosti ruฤnรญho pล™epรญnรกnรญ.\n\n#### Sprรกva protokolลฏ, kterรก je viditelnรก a ovladatelnรก\n\n- MCP + A2A jsou viditelnรฉ v uลพivatelskรฉm rozhranรญ a dokumentaci (nejsou skrytรฉ)\n- API pro stav protokolu zpล™รญstupลˆujรญ ลพivรก provoznรญ data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnujรญ akce pro operace 2. dne (pล™epรญnรกnรญ kombinacรญ, resetovรกnรญ jistiฤลฏ, zruลกenรญ รบkolลฏ)\n\n#### Pracovnรญ postup pล™ekladatele + validace\n\nOblast pล™ekladatele zahrnuje:\n\n- **Hล™iลกtฤ›** : kontroly transformace poลพadavkลฏ\n- **Tester chatu** : kompletnรญ okruลพnรญ cesta poลพadavku/odpovฤ›di\n- **Testovacรญ stolice** : vรญce pล™รญpadลฏ v jednom bฤ›hu\n- **ลฝivรฝ monitor** : zobrazenรญ provozu v reรกlnรฉm ฤase\n\nPlus validace protokolu se skuteฤnรฝmi klienty pomocรญ `npm run test:protocols:e2e` .\n\n> ๐Ÿ“– **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** โ€” Referenฤnรญ informace o nรกstrojรญch, konfigurace IDE a pล™รญklady klientลฏ\n>\n> ๐Ÿ“– **[Soubor README pro A2A Server](src/lib/a2a/README.md)** โ€” Dovednosti, metody JSON-RPC, streamovรกnรญ a ลพivotnรญ cyklus รบloh\n\n## ๐Ÿงช Hodnocenรญ (Evals)\n\nOmniRoute obsahuje vestavฤ›nรฝ hodnotรญcรญ rรกmec pro testovรกnรญ kvality odpovฤ›dรญ LLM v porovnรกnรญ se zlatou sadou. Pล™รญstup k nฤ›mu je moลพnรฝ pล™es **Analรฝzy โ†’ Hodnocenรญ** v dashboardu.\n\n### Vestavฤ›nรก zlatรก sada\n\nPล™edinstalovanรก sada โ€žOmniRoute Golden Setโ€œ obsahuje testovacรญ pล™รญpady pro:\n\n- Zdravรญm, matematika, zemฤ›pis, generovรกnรญ kรณdu\n- Shoda s formรกtem JSON, pล™eklad, generovรกnรญ markdownลฏ\n- Bezpeฤnostnรญ odmรญtnutรญ (ลกkodlivรฝ obsah), poฤรญtรกnรญ, booleovskรก logika\n\n### Strategie hodnocenรญ\n\n| Strategie | Popis | Pล™รญklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Vรฝstup se musรญ pล™esnฤ› shodovat | `\"4\"` |\n| `contains` | Vรฝstup musรญ obsahovat podล™etฤ›zec (bez rozliลกenรญ velkรฝch a malรฝch pรญsmen) | `\"Paris\"` |\n| `regex` | Vรฝstup musรญ odpovรญdat vzoru regulรกrnรญch vรฝrazลฏ | `\"1.*2.*3\"` |\n| `custom` | Vlastnรญ JS funkce vracรญ true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Prลฏvodce nastavenรญm\n\n### Nastavenรญ protokolu (MCP + A2A)\n\n
\n๐Ÿงฉ Nastavenรญ MCP (Model Context Protocol)\n
\n\nSpuลกtฤ›nรญ MCP transportu v reลพimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporuฤenรฝ postup ovฤ›ล™enรญ:\n\n1. Pล™ipojte svรฉho MCP klienta pล™es stdio.\n2. Spusลฅte `omniroute_get_health` .\n3. Spusลฅte `omniroute_list_combos` .\n4. Otevล™ete `/dashboard/mcp` pro ovฤ›ล™enรญ prezenฤnรญho signรกlu, aktivity a auditu.\n\nUลพiteฤnรก API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n๐Ÿค Nastavenรญ A2A (Agent2Agent)\n
\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat รบkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSprรกva ลพivotnรญho cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvoznรญ uลพivatelskรฉ rozhranรญ:\n\n- `/dashboard/a2a` pro pozorovatelnost รบloh/stavลฏ/streamลฏ a akce kouล™enรญ\n\n
\n๐Ÿงช Komplexnรญ validace protokolu\n
\n\nOvฤ›ล™te oba protokoly se skuteฤnรฝmi klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTรญm se ovฤ›ล™uje:\n\n- Pล™ipojenรญ/seznam/volรกnรญ klienta MCP SDK\n- A2A objevovรกnรญ/odesรญlรกnรญ/streamovรกnรญ/zรญskรกvรกnรญ/zruลกenรญ\n- Kล™รญลพovรก kontrola dat v auditu MCP a API pro sprรกvu รบloh A2A\n\n
\n๐Ÿ’ณ Poskytovatelรฉ pล™edplatnรฉho\n
\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionรกly:** Pro sloลพitรฉ รบkoly pouลพรญvejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvรณtu pro kaลพdรฝ model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Sprรกva limitลฏ รบฤtu Codex (5h + tรฝdnฤ›)\n\nKaลพdรฝ รบฤet Codex mรก nynรญ pล™epรญnaฤe zรกsad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinovรฉho prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zรกsadu tรฝdennรญho prahu okna.\n- Prahovรฉ chovรกnรญ: kdyลพ povolenรฉ okno dosรกhne vyuลพitรญ >=90 %, je danรฝ รบฤet pล™eskoฤen.\n- Chovรกnรญ rotace: OmniRoute automaticky pล™esmฤ›ruje na dalลกรญ zpลฏsobilรฝ รบฤet Codex.\n- Chovรกnรญ pล™i resetovรกnรญ: Po `resetAt` urฤitรฉ doby se รบฤet automaticky opฤ›t stane zpลฏsobilรฝm.\n\nScรฉnรกล™e:\n\n- `5h ON` + `Weekly ON` : รบฤet je pล™eskoฤen, kdyลพ kterรฉkoli z oken dosรกhne prahovรฉ hodnoty.\n- `5h OFF` + `Weekly ON` : รบฤet mลฏลพe bรฝt zablokovรกn pouze tรฝdennรญm pouลพรญvรกnรญm.\n- `5h ON` + `Weekly OFF` : รบฤet mลฏลพe bรฝt zablokovรกn pouze pล™i 5hodinovรฉm pouลพรญvรกnรญ.\n- `resetAt` passed: รบฤet se automaticky znovu zapne (bez ruฤnรญho opฤ›tovnรฉho povolenรญ).\n\n### Gemini CLI (ZDARMA 180 000/mฤ›sรญc!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepลกรญ hodnota:** Obrovskรก bezplatnรก รบroveลˆ! Pouลพijte ji pล™ed placenรฝmi รบrovnฤ›mi.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n
\n๐Ÿ”‘ Poskytovatelรฉ klรญฤลฏ API\n
\n\n### NVIDIA NIM (BEZPLATNร pล™รญstup pro vรฝvojรกล™e โ€” vรญce neลพ 70 modelลฏ)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Zรญskejte zdarma klรญฤ API (vฤetnฤ› 1000 inferenฤnรญch kreditลฏ)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ NVIDIA NIM:\n - Klรญฤ API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a vรญce neลพ 50 dalลกรญch\n\n**Tip pro profesionรกly:** API kompatibilnรญ s OpenAI โ€“ funguje bez problรฉmลฏ s pล™ekladem formรกtลฏ OmniRoute!\n\n### Hlubokรฉ vyhledรกvรกnรญ\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatnรก รบroveลˆ!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Zรญskejte klรญฤ API (vฤetnฤ› bezplatnรฉ รบrovnฤ›)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionรกly:** Ultrarychlรก inference โ€“ nejlepลกรญ pro kรณdovรกnรญ v reรกlnรฉm ฤase!\n\n### OpenRouter (100+ modelลฏ)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ OpenRouter\n\n**Modely:** Zรญskejte pล™รญstup k vรญce neลพ 100 modelลฏm od vลกech hlavnรญch poskytovatelลฏ prostล™ednictvรญm jedinรฉho klรญฤe API.\n\n
\n๐Ÿ’ฐ Levnรญ poskytovatelรฉ (zรกloลพnรญ)\n
\n\n### GLM-4.7 (Dennรญ reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Zรญskejte klรญฤ API z kรณdovacรญho plรกnu\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API:\n - Poskytovatel: `glm`\n - Klรญฤ API: `your-key`\n\n**Pouลพitรญ:** `glm/glm-4.7`\n\n**Tip pro profesionรกly:** Programovacรญ plรกn nabรญzรญ 3ร— kvรณtu za cenu 1/7! Obnovuje se dennฤ› v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionรกly:** Nejlevnฤ›jลกรญ varianta pro dlouhรฝ kontext (1 milion tokenลฏ)!\n\n### Kimi K2 (pauลกรกlnรญ poplatek 9 dolarลฏ mฤ›sรญฤnฤ›)\n\n1. Odebรญrat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `kimi/kimi-latest`\n\n**Tip pro profesionรกly:** Fixnรญch 9 $/mฤ›sรญc za 10 milionลฏ tokenลฏ = efektivnรญ nรกklady 0,90 $/1 milion!\n\n
\n๐Ÿ†“ BEZPLATNร poskytovatelรฉ (nouzovรฉ zรกlohovรกnรญ)\n
\n\n### iFlow (5 BEZPLATNรCH modelลฏ pล™es OAuth)\n\n```bash\nDashboard โ†’ Connect iFlow\nโ†’ iFlow OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kรณdem zaล™รญzenรญ)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n๐ŸŽจ Vytvoล™te kombinace\n
\n\n### Pล™รญklad 1: Maximalizace pล™edplatnรฉho โ†’ Levnรฉ zรกlohovรกnรญ\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Pล™รญklad 2: Pouze zdarma (nulovรฉ nรกklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n๐Ÿ”ง Integrace s rozhranรญm pล™รญkazovรฉho ล™รกdku\n
\n\n### IDE kurzoru\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jednรญm kliknutรญm pouลพijte strรกnku **Nรกstroje CLI** na ล™รญdicรญm panelu nebo ruฤnฤ› upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Moลพnost 1 โ€“ Dashboard (doporuฤeno):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Moลพnost 2 โ€“ Manuรกlnรญ รบprava:** รšprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznรกmka:** OpenClaw funguje pouze s lokรกlnรญm OmniRoute. Mรญsto `localhost` pouลพijte `127.0.0.1` , abyste se vyhnuli problรฉmลฏm s rozliลกenรญm IPv6.\n\n### Cline / Pokraฤovat / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Pล™idรกnรญ OmniRoute jako vlastnรญho poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvoล™te/upravte `opencode.json` v koล™enovรฉm adresรกล™i projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` pล™idejte jakรฝkoli model dostupnรฝ ve vaลกem koncovรฉm bodu OmniRoute `/v1/models` . Pouลพijte formรกt `provider/model-id` z vaลกeho dashboardu OmniRoute.\n\n---\n\n## ๐Ÿ› ล˜eลกenรญ problรฉmลฏ\n\n
\nKliknutรญm rozbalรญte prลฏvodce ล™eลกenรญm problรฉmลฏ\n
\n\n**\"Jazykovรฝ model neposkytoval zprรกvy\"**\n\n- Kvรณta poskytovatele vyฤerpรกna โ†’ Zkontrolujte sledovรกnรญ kvรณt na ล™รญdicรญm panelu\n- ล˜eลกenรญ: Pouลพijte zรกloลพnรญ kombinovanou variantu nebo pล™ejdฤ›te na levnฤ›jลกรญ รบroveลˆ\n\n**Omezenรญ rychlosti**\n\n- Kvรณta pล™edplatnรฉho vyฤerpรกna โ†’ Pล™echod na GLM/MiniMax\n- Pล™idat kombo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vyprลกela**\n\n- Automaticky aktualizovรกno sluลพbou OmniRoute\n- Pokud problรฉmy pล™etrvรกvajรญ: Ovlรกdacรญ panel โ†’ Poskytovatel โ†’ Znovu pล™ipojit\n\n**Vysokรฉ nรกklady**\n\n- Zkontrolujte statistiky vyuลพitรญ v sekci Nรกstฤ›nka โ†’ Nรกklady\n- Pล™epnout primรกrnรญ model na GLM/MiniMax\n- Pro nekritickรฉ รบlohy pouลพijte bezplatnou รบroveลˆ (Gemini CLI, iFlow).\n\n**Porty ล™รญdicรญho panelu/API jsou nesprรกvnรฉ**\n\n- `PORT` je kanonickรฝ zรกkladnรญ port (a standardnฤ› port API)\n- `API_PORT` pล™episuje pouze posluchaฤ API kompatibilnรญ s OpenAI.\n- `DASHBOARD_PORT` pล™episuje pouze posluchaฤ dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaลกi veล™ejnou URL adresu ล™รญdicรญho panelu (pro zpฤ›tnรก volรกnรญ OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ovฤ›ล™te, zda `BASE_URL` odkazuje na vaลกi spuลกtฤ›nou instanci.\n- Ovฤ›ล™te, zda `CLOUD_URL` odkazuje na vรกลก oฤekรกvanรฝ cloudovรฝ koncovรฝ bod.\n- Udrลพujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na stranฤ› serveru.\n\n**Prvnรญ pล™ihlรกลกenรญ nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud nenรญ nastaveno, zรกloลพnรญ heslo je `123456`\n\n**ลฝรกdnรฉ protokoly poลพadavkลฏ**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test pล™ipojenรญ ukazuje โ€žNeplatnรฉโ€œ pro poskytovatele kompatibilnรญ s OpenAI**\n\n- Mnoho poskytovatelลฏ nezpล™รญstupลˆuje koncovรฝ bod `/models`\n- OmniRoute v1.0.6+ zahrnuje zรกloลพnรญ ovฤ›ล™enรญ pomocรญ dokonฤenรญ chatu\n- Zajistฤ›te, aby zรกkladnรญ URL adresa obsahovala pล™รญponu `/v1`\n\n### ๐Ÿ” OAuth na vzdรกlenรฉm serveru\n\n\n\n\n> **โš ๏ธ Dลฏleลพitรฉ pro uลพivatele, kteล™รญ provozujรญ OmniRoute na VPS, Dockeru nebo jakรฉmkoli vzdรกlenรฉm serveru**\n\n#### Proฤ selhรกvรก OAuth v rozhranรญ CLI Antigravity / Gemini na vzdรกlenรฝch serverech?\n\nPoskytovatelรฉ rozhranรญ CLI **Antigravity** a **Gemini** pouลพรญvajรญ **Google OAuth 2.0** . Google vyลพaduje, aby se `redirect_uri` v toku OAuth pล™esnฤ› shodoval s jednรญm z pล™edregistrovanรฝch URI v konzoli Google Cloud Console aplikace.\n\nPล™ihlaลกovacรญ รบdaje OAuth, kterรฉ jsou souฤรกstรญ OmniRoute, jsou registrovรกny **pouze pro `localhost`** . Kdyลพ pล™istupujete k OmniRoute na vzdรกlenรฉm serveru (napล™. `https://omniroute.myserver.com` ), Google odmรญtne ovฤ›ล™enรญ pomocรญ:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### ล˜eลกenรญ: Nakonfigurujte si vlastnรญ pล™ihlaลกovacรญ รบdaje OAuth\n\nV Google Cloud Console je potล™eba vytvoล™it **ID klienta OAuth 2.0** s URI vaลกeho serveru.\n\n#### Krok za krokem\n\n**1. Otevล™ete konzoli Google Cloud**\n\nPล™ejdฤ›te na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvoล™te novรฉ ID klienta OAuth 2.0**\n\n- Kliknฤ›te na **โ€ž+ Vytvoล™it pล™ihlaลกovacรญ รบdajeโ€œ** โ†’ **โ€žID klienta OAuthโ€œ**\n- Typ aplikace: **โ€žWebovรก aplikaceโ€œ**\n- Nรกzev: cokoli chcete (napล™. `OmniRoute Remote` )\n\n**3. Pล™idejte autorizovanรฉ URI pro pล™esmฤ›rovรกnรญ**\n\nDo pole **โ€žAutorizovanรฉ identifikรกtory URI pro pล™esmฤ›rovรกnรญโ€œ** pล™idejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraฤte `your-server.com` domรฉnou nebo IP adresou vaลกeho serveru (v pล™รญpadฤ› potล™eby uveฤte i port, napล™. `http://45.33.32.156:20128/callback` ).\n\n**4. Uloลพte a zkopรญrujte pล™ihlaลกovacรญ รบdaje**\n\nPo vytvoล™enรญ Google zobrazรญ **ID klienta** a **tajnรฝ kรณd klienta** .\n\n**5. Nastavenรญ promฤ›nnรฝch prostล™edรญ**\n\nVe vaลกem souboru `.env` (nebo promฤ›nnรฝch prostล™edรญ Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu pล™ipojit**\n\nล˜รญdicรญ panel โ†’ Poskytovatelรฉ โ†’ Antigravity (nebo Gemini CLI) โ†’ OAuth\n\nGoogle nynรญ bude sprรกvnฤ› pล™esmฤ›rovรกvat na `https://your-server.com/callback` .\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nPokud si teฤ nechcete nastavovat vlastnรญ pล™ihlaลกovacรญ รบdaje, mลฏลพete stรกle pouลพรญt **ruฤnรญ postup pro URL** :\n\n1. OmniRoute otevรญrรก autorizaฤnรญ URL od Googlu\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru).\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe (i kdyลพ se strรกnka nenaฤte)\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute.\n5. Kliknฤ›te na **โ€žPล™ipojitโ€œ**\n\n> To funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na to, zda se naฤetla pล™esmฤ›rovacรญ strรกnka.\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nChcete-li zรญskat pล™รญstup k pล™ihlaลกovacรญm รบdajลฏm bez vlastnรญ konfigurace, mลฏลพete pouลพรญt nรกsledujรญcรญ postup:\n\n1. OmniRoute otevล™e URL autorizace Google\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru)\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute\n5. Kliknฤ›te na **โ€žPล™ipojit\"**\n\n> Toto ล™eลกenรญ funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na naฤtenรญ pล™esmฤ›rovacรญ strรกnky.\n\n---\n\n## ๐Ÿ› ๏ธ Technologickรฝ stack\n\n
\nKliknutรญm rozbalรญte podrobnosti o technologickรฉm stacku\n
\n\n- **Runtime** : Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ **nenรญ podporovรกn** โ€” nativnรญ binรกrnรญ soubory `better-sqlite3` jsou nekompatibilnรญ)\n- **Jazyk** : TypeScript 5.9 โ€” **100% TypeScript** napล™รญฤ `src/` a `open-sse/` ( `any` v zรกkladnรญch modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databรกze** : LowDB (JSON) + SQLite (stav domรฉny + protokoly proxy + audit MCP + rozhodnutรญ o smฤ›rovรกnรญ)\n- **Schรฉmata** : Zod (validace I/O nรกstrojลฏ MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamovรกnรญ** : Udรกlosti odeslanรฉ serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klรญฤe + autorizace s rozsahem MCP\n- **Testovรกnรญ** : Node.js test runner + Vitest (900+ testลฏ vฤetnฤ› unit, integraฤnรญch, E2E)\n- **CI/CD** : Akce GitHubu (automatickรฉ publikovรกnรญ v npm + Docker Hub pล™i vydรกnรญ)\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **Balรญฤek** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistiฤ, exponenciรกlnรญ odstavenรญ, ochrana proti hromลฏm, faleลกnรฉ TLS, automatickรฉ kombinovanรฉ samoopravovรกnรญ\n\n---\n\n## ๐Ÿ“– Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uลพivatelskรก pล™รญruฤka](docs/USER_GUIDE.md) | Poskytovatelรฉ, kombinace, integrace CLI, nasazenรญ |\n| [Referenฤnรญ informace k API](docs/API_REFERENCE.md) | Vลกechny koncovรฉ body s pล™รญklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nรกstrojลฏ MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamovรกnรญ, sprรกva รบloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorovรฉ bodovรกnรญ, balรญฤky reลพimลฏ, samolรฉฤba |\n| [Odstraลˆovรกnรญ problรฉmลฏ](docs/TROUBLESHOOTING.md) | Bฤ›ลพnรฉ problรฉmy a jejich ล™eลกenรญ |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a internรญ prvky systรฉmu |\n| [Pล™ispรญvรกnรญ](CONTRIBUTING.md) | Nastavenรญ a pokyny pro vรฝvoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpeฤnostnรญ zรกsady](SECURITY.md) | Hlรกลกenรญ zranitelnostรญ a bezpeฤnostnรญ postupy |\n| [Nasazenรญ virtuรกlnรญho poฤรญtaฤe](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletnรญ prลฏvodce: Nastavenรญ virtuรกlnรญho poฤรญtaฤe + nginx + Cloudflare |\n| [Galerie funkcรญ](docs/FEATURES.md) | Vizuรกlnรญ prohlรญdka ล™รญdicรญho panelu se snรญmky obrazovky |\n| [Kontrolnรญ seznam vydรกnรญ](docs/RELEASE_CHECKLIST.md) | Kroky ovฤ›ล™enรญ pล™ed vydรกnรญm |\n\n---\n\n## ๐Ÿ—บ๏ธ Plรกn\n\nOmniRoute mรก **v plรกnu vรญce neลพ 210 funkcรญ** v nฤ›kolika fรกzรญch vรฝvoje. Zde jsou klรญฤovรฉ oblasti:\n\n| Kategorie | Plรกnovanรฉ funkce | Hlavnรญ body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| ๐Ÿง  **Smฤ›rovรกnรญ a inteligence** | 25+ | Smฤ›rovรกnรญ s nejniลพลกรญ latencรญ, smฤ›rovรกnรญ zaloลพenรฉ na tagech, kontrola kvรณt pล™ed vรฝstupem, vรฝbฤ›r รบฤtu P2C |\n| ๐Ÿ”’ **Zabezpeฤenรญ a dodrลพovรกnรญ pล™edpisลฏ** | 20+ | Zpevnฤ›nรญ SSRF, maskovรกnรญ pล™ihlaลกovacรญch รบdajลฏ, limit rychlosti pro kaลพdรฝ koncovรฝ bod, stanovenรญ rozsahu klรญฤลฏ pro sprรกvu |\n| ๐Ÿ“Š **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledovรกnรญ kvรณt v reรกlnรฉm ฤase, sledovรกnรญ nรกkladลฏ podle modelu |\n| ๐Ÿ”„ **Integrace poskytovatelลฏ** | 20+ | Dynamickรฝ registr modelลฏ, doba zchlazenรญ poskytovatelลฏ, Codex pro vรญce รบฤtลฏ, analรฝza kvรณt Copilota |\n| โšก **Vรฝkon** | 15+ | Dvojitรก vrstva mezipamฤ›ti, mezipamฤ›ลฅ vรฝzev, mezipamฤ›ลฅ odpovฤ›dรญ, udrลพovรกnรญ streamovรกnรญ, dรกvkovรฉ API |\n| ๐ŸŒ **Ekosystรฉm** | 10+ | WebSocket API, horkรฉ opฤ›tovnรฉ naฤรญtรกnรญ konfigurace, distribuovanรฉ รบloลพiลกtฤ› konfigurace, komerฤnรญ reลพim |\n\n### ๐Ÿ”œ Jiลพ brzy\n\n- ๐Ÿ”— **Integrace OpenCode** โ€” Nativnรญ podpora poskytovatelลฏ pro IDE kรณdovรกnรญ s AI v OpenCode\n- ๐Ÿ”— **Integrace TRAE** โ€” Plnรก podpora vรฝvojovรฉho rรกmce TRAE pro umฤ›lou inteligenci\n- ๐Ÿ“ฆ **Dรกvkovรฉ API** โ€” Asynchronnรญ dรกvkovรฉ zpracovรกnรญ hromadnรฝch poลพadavkลฏ\n- ๐ŸŽฏ **Smฤ›rovรกnรญ na zรกkladฤ› tagลฏ** โ€” Smฤ›rovรกnรญ poลพadavkลฏ na zรกkladฤ› vlastnรญch tagลฏ a metadat\n- ๐Ÿ’ฐ **Strategie nejniลพลกรญch nรกkladลฏ** โ€“ Automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n> ๐Ÿ“ รšplnรฉ specifikace funkcรญ jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobnรฝch specifikacรญ)\n\n---\n\n## ๐Ÿ‘ฅ Pล™ispฤ›vatelรฉ\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Pล™ispฤ›vatelรฉ](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak pล™ispฤ›t\n\n1. Vytvoล™enรญ forku repozitรกล™e\n2. Vytvoล™te si vlastnรญ vฤ›tev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrฤte zmฤ›ny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do vฤ›tve ( `git push origin feature/amazing-feature` )\n5. Otevล™รญt ลพรกdost o zmฤ›ny (pull request)\n\nPodrobnรฉ pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydรกnรญ novรฉ verze\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Hvฤ›zdnรก historie\n\n## Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## ๐Ÿ™ Podฤ›kovรกnรญ\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** โ€“ pลฏvodnรญmu projektu, kterรฝ inspiroval tento fork. OmniRoute stavรญ na tomto neuvฤ›ล™itelnรฉm zรกkladu s dalลกรญmi funkcemi, multimodรกlnรญmi API a kompletnรญm pล™epsรกnรญm TypeScriptu.\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€“ pลฏvodnรญ implementaci Go, kterรก inspirovala tento JavaScriptovรฝ port.\n\n---\n\n## ๐Ÿ“„ Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n
\n Vytvoล™eno s โค๏ธ pro vรฝvojรกล™e, kteล™รญ programujรญ 24 hodin dennฤ›, 7 dnรญ v tรฝdnu\n
\n

omniroute.online

\n
\n\n"}, "b5a145d7b336ce90a238db309951c57a508fb564": {"t": 1785764469.5980096, "n": 94491, "h": "9be6d6b894b577e6", "c": "# ๐Ÿš€ OmniRoute โ€” Bezplatnรก brรกna umฤ›lรฉ inteligence\n\n### Nikdy nepล™estรกvejte s kรณdovรกnรญm. Chytrรฉ smฤ›rovรกnรญ k **BEZPLATNรM a levnรฝm modelลฏm AI** s automatickรฝm pล™epรญnรกnรญm mezi zรกloลพnรญmi systรฉmy.\n\n_Vรกลก univerzรกlnรญ API proxy โ€“ jeden endpoint, vรญce neลพ 44 poskytovatelลฏ, nulovรฉ vรฝpadky. Nynรญ s orchestracรญ agentลฏ **MCP a A2A** ._\n\n**Dokonฤenรญ chatu โ€ข Vklรกdรกnรญ โ€ข Generovรกnรญ obrรกzkลฏ โ€ข Video โ€ข Hudba โ€ข Audio โ€ข Zmฤ›na poล™adรญ โ€ข **Vyhledรกvรกnรญ na webu** โ€ข MCP server โ€ข A2A protokol โ€ข 100% TypeScript**\n\n---\n\n
\n
\n

\"verze\"Docker\"Licence\"\"Webovรฉ\"WhatsApp\"

\n

๐ŸŒ Webovรฉ strรกnky โ€ข ๐Ÿš€ Rychlรฝ start โ€ข ๐Ÿ’ก Funkce โ€ข ๐Ÿ“– Dokumentace โ€ข ๐Ÿ’ฐ Cenรญk โ€ข ๐Ÿ’ฌ WhatsApp

\n
\n\n๐ŸŒ **Dostupnรฉ v:** ๐Ÿ‡บ๐Ÿ‡ธ [Angliฤtina](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Hlavnรญ ovlรกdacรญ panel\n\n
\"ล˜รญdicรญ
\n\n---\n\n## ๐Ÿ“ธ Nรกhled ล™รญdicรญho panelu\n\n
\nKliknutรญm zobrazรญte snรญmky obrazovky z ล™รญdicรญho panelu\n
\n\n| Strana | Snรญmek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelรฉ** | ![Poskytovatelรฉ](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdravรญ** | ![Zdravรญ](docs/screenshots/04-health.png) |\n| **Pล™ekladatel** | ![Pล™ekladatel](docs/screenshots/05-translator.png) |\n| **Nastavenรญ** | ![Nastavenรญ](docs/screenshots/06-settings.png) |\n| **Nรกstroje CLI** | ![Nรกstroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly pouลพรญvรกnรญ** | ![Pouลพรญvรกnรญ](docs/screenshots/08-usage.png) |\n| **Koncovรฉ body** | ![Koncovรฉ body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### ๐Ÿค– Bezplatnรฝ poskytovatel umฤ›lรฉ inteligence pro vaลกe oblรญbenรฉ programรกtory\n\n_Pล™ipojte libovolnรฝ nรกstroj IDE nebo CLI s umฤ›lou inteligencรญ pล™es OmniRoute โ€” bezplatnou API brรกnu pro neomezenรฉ kรณdovรกnรญ._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\"OpenClaw\"
OpenClaw
โญ 205 tisรญc 		\"NanoBot\"
NanoBot
โญ 20,9 tisรญc 		\"PicoClaw\"
PicoClaw
โญ 14,6 tisรญc 		\"ZeroClaw\"
ZeroClaw
โญ 9,9 tisรญc 		\"ลฝeleznรฝ
ลฝeleznรฝ drรกp
โญ 2,1 tisรญce
\"OpenCode\"
OpenCode
โญ 106 tisรญc 		\"Codex
Codex CLI
โญ 60,8 tisรญc 		\"Claude
Claude Code
โญ 67,3 tisรญc 		\"Gemini
Gemini CLI
โญ 94,7 tisรญc 		\"Kilo
Kilo kรณd
โญ 15,5 tisรญc
\n\n๐Ÿ“ก Vลกichni agenti se pล™ipojujรญ pล™es http://localhost:20128/v1 nebo http://cloud.omniroute.online/v1 โ€” jedna konfigurace, neomezenรฉ modely a kvรณty\n\n---\n\n## ๐Ÿค” Proฤ OmniRoute?\n\n**Pล™estaลˆte plรฝtvat penฤ›zi a narรกลพet na limity:**\n\n- Kvรณta pล™edplatnรฉho vyprลกรญ kaลพdรฝ mฤ›sรญc\n- Limity rychlosti vรกm zabrรกnรญ v kรณdovรกnรญ\n- Drahรก API (20โ€“50 USD/mฤ›sรญc na poskytovatele)\n- Ruฤnรญ pล™epรญnรกnรญ mezi poskytovateli\n\n**OmniRoute to ล™eลกรญ:**\n\n- โœ… **Maximalizujte pล™edplatnรฉ** โ€“ Sledujte kvรณtu, vyuลพijte kaลพdou ฤรกstku pล™ed resetovรกnรญm\n- โœ… **Automatickรฉ zรกloลพnรญ** โ€“ Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma, ลพรกdnรฉ vรฝpadky\n- โœ… **Vรญce รบฤtลฏ** โ€“ Round-robin mezi รบฤty u jednotlivรฝch poskytovatelลฏ\n- โœ… **Univerzรกlnรญ** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakรฝmkoli nรกstrojem CLI\n\n---\n\n## ๐Ÿ“ง Podpora\n\n> ๐Ÿ’ฌ **Pล™idejte se k naลกรญ komunitฤ›!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Zรญskejte pomoc, sdรญlejte tipy a buฤte v obraze.\n\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problรฉmy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitnรญ skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Pล™ispรญvรกnรญ** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevล™ete ลพรกdost o pล™รญspฤ›vek nebo si vyberte `good first issue`\n- **Pลฏvodnรญ projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Hlรกsรญte chybu?\n\nPล™i otevรญrรกnรญ problรฉmu spusลฅte pล™รญkaz system-info a pล™iloลพte vygenerovanรฝ soubor:\n\n```bash\nnpm run system-info\n```\n\nTรญm se vygeneruje soubor `system-info.txt` s verzรญ Node.js, verzรญ OmniRoute, podrobnostmi o operaฤnรญm systรฉmu, nainstalovanรฝmi nรกstroji CLI (iflow, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systรฉmovรฝmi balรญฤky โ€“ vลกe, co potล™ebujeme k rychlรฉ reprodukci vaลกeho problรฉmu. Soubor pล™iloลพte pล™รญmo k vaลกemu problรฉmu na GitHubu.\n\n---\n\n## ๐Ÿ”„ Jak to funguje\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ Co ล™eลกรญ OmniRoute โ€” 30 skuteฤnรฝch problรฉmลฏ a pล™รญpadลฏ pouลพitรญ\n\n> **Kaลพdรฝ vรฝvojรกล™ pouลพรญvajรญcรญ nรกstroje umฤ›lรฉ inteligence se s tฤ›mito problรฉmy setkรกvรก dennฤ›.** OmniRoute byl vytvoล™en tak, aby je vลกechny vyล™eลกil โ€“ od pล™ekroฤenรญ nรกkladลฏ po regionรกlnรญ bloky, od nefunkฤnรญch tokลฏ OAuth aลพ po operace s protokoly a sledovatelnost v podniku.\n\n
\n๐Ÿ’ธ 1. โ€žPlatรญm si drahรฉ pล™edplatnรฉ, ale stรกle mฤ› ruลกรญ limityโ€œ\n
\n\nVรฝvojรกล™i platรญ za Claude Pro, Codex Pro nebo GitHub Copilot 20โ€“200 dolarลฏ mฤ›sรญฤnฤ›. I pล™i platbฤ› mรก kvรณta strop โ€“ 5 hodin pouลพรญvรกnรญ, tรฝdennรญ limity nebo limity rychlosti za minutu. Uprostล™ed kรณdovacรญ relace poskytovatel pล™estane reagovat a vรฝvojรกล™ ztrรกcรญ plynulost a produktivitu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Inteligentnรญ ฤtyล™รบrovลˆovรก zรกloลพnรญ sluลพba** โ€“ Pokud dojde kvรณta pล™edplatnรฉho, โ€‹โ€‹automaticky se pล™esmฤ›ruje na API klรญฤ โ†’ Levnรฉ โ†’ Zdarma bez manuรกlnรญho zรกsahu\n- **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** โ€“ Zobrazuje spotล™ebu tokenลฏ v reรกlnรฉm ฤase s odpoฤรญtรกvรกnรญm resetovรกnรญ (5 hodin, dennฤ›, tรฝdnฤ›)\n- **Podpora vรญce รบฤtลฏ** โ€“ Vรญce รบฤtลฏ u jednoho poskytovatele s automatickรฝm pล™epรญnรกnรญm โ€“ kdyลพ jeden dojde, pล™epne se na dalลกรญ\n- **Vlastnรญ kombinace** โ€” Pล™izpลฏsobitelnรฉ zรกloลพnรญ ล™etฤ›zce se 6 strategiemi vyvaลพovรกnรญ (fill-first, round robin, P2C, nรกhodnรฉ, nejmรฉnฤ› pouลพรญvanรฉ, nรกkladovฤ› optimalizovanรฉ)\n- **Codex Business Quotas** โ€” Sledovรกnรญ kvรณt pracovnรญho prostoru firmy/tรฝmu pล™รญmo v dashboardu\n\n
\n๐Ÿ”Œ 2. โ€žPotล™ebuji pouลพรญt vรญce poskytovatelลฏ, ale kaลพdรฝ mรก jinรฉ APIโ€œ\n
\n\nOpenAI pouลพรญvรก jeden formรกt, Claude (Anthropic) jinรฝ a Gemini jeลกtฤ› tล™etรญ. Pokud chce vรฝvojรกล™ testovat modely od rลฏznรฝch poskytovatelลฏ nebo mezi nimi pล™echรกzet, musรญ pล™ekonfigurovat SDK, zmฤ›nit koncovรฉ body a vypoล™รกdat se s nekompatibilnรญmi formรกty. Vlastnรญ poskytovatelรฉ (FriendLI, NIM) majรญ nestandardnรญ koncovรฉ body modelลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sjednocenรฝ koncovรฝ bod** โ€” Jeden `http://localhost:20128/v1` slouลพรญ jako proxy pro vลกech 44+ poskytovatelลฏ.\n- **Pล™eklad formรกtu** โ€” Automatickรฝ a transparentnรญ: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Sanitizace odpovฤ›dรญ** โ€” Odstraลˆuje nestandardnรญ pole ( `x_groq` , `usage_breakdown` , `service_tier` ), kterรก poruลกujรญ OpenAI SDK v1.83+\n- **Normalizace rolรญ** โ€” Pล™evรกdรญ `developer` โ†’ `system` pro poskytovatele bez OpenAI; `system` โ†’ `user` pro GLM/ERNIE\n- **Extrakce tagลฏ Think** โ€” Extrahuje bloky `` z modelลฏ, jako je DeepSeek R1, do standardizovanรฉho `reasoning_content`\n- **Strukturovanรฝ vรฝstup pro Gemini** โ€” `json_schema` โ†’ automatickรก konverze `responseMimeType` / `responseSchema`\n- **Vรฝchozรญ hodnota `stream` je `false`** โ€“ Odpovรญdรก specifikaci OpenAI, ฤรญmลพ se zabrรกnรญ neoฤekรกvanรฉmu SSE v Python/Rust/Go SDK.\n\n
\n๐ŸŒ 3. โ€žMลฏj poskytovatel AI blokuje mลฏj region/zemiโ€œ\n
\n\nPoskytovatelรฉ jako OpenAI/Codex blokujรญ pล™รญstup z urฤitรฝch geografickรฝch oblastรญ. Uลพivatelรฉ se bฤ›hem pล™ipojenรญ OAuth a API dostรกvajรญ k chybรกm jako `unsupported_country_region_territory` . To je obzvlรกลกtฤ› frustrujรญcรญ pro vรฝvojรกล™e z rozvojovรฝch zemรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **3รบrovลˆovรก konfigurace proxy** โ€“ Konfigurovatelnรก proxy na 3 รบrovnรญch: globรกlnรญ (veลกkerรฝ provoz), pro jednotlivรฉ poskytovatele (pouze jeden poskytovatel) a pro jednotlivรฉ pล™ipojenรญ/klรญฤ\n- **Barevnฤ› kรณdovanรฉ odznaky proxy** โ€“ Vizuรกlnรญ indikรกtory: ๐ŸŸข globรกlnรญ proxy, ๐ŸŸก proxy poskytovatele, ๐Ÿ”ต proxy pล™ipojenรญ, vลพdy zobrazujรญcรญ IP adresu\n- **Vรฝmฤ›na tokenลฏ OAuth prostล™ednictvรญm proxy** โ€“ tok OAuth takรฉ prochรกzรญ pล™es proxy, ฤรญmลพ se ล™eลกรญ `unsupported_country_region_territory`\n- **Testy pล™ipojenรญ pล™es proxy** โ€“ Testy pล™ipojenรญ pouลพรญvajรญ nakonfigurovanรฝ proxy (jiลพ ลพรกdnรฉ pล™รญmรฉ obchรกzenรญ)\n- **Podpora SOCKS5** โ€” Plnรก podpora proxy SOCKS5 pro odchozรญ smฤ›rovรกnรญ\n- **TLS Fingerprint Spoofing** โ€” Otisk prstu TLS podobnรฝ prohlรญลพeฤi pomocรญ `wreq-js` pro obchรกzenรญ detekce botลฏ\n- **๐Ÿ” Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** โ€” Zmฤ›nรญ poล™adรญ zรกhlavรญ a polรญ v tฤ›le serveru tak, aby odpovรญdala nativnรญm binรกrnรญm podpisลฏm v CLI, ฤรญmลพ drasticky sniลพuje riziko nahlaลกovรกnรญ รบฤtu. IP adresa proxy je zachovรกna โ€” zรญskรกte souฤasnฤ› stealth **i** maskovรกnรญ IP adresy.\n\n
\n๐Ÿ†“ 4. โ€žChci pouลพรญvat umฤ›lou inteligenci pro kรณdovรกnรญ, ale nemรกm penรญzeโ€œ\n
\n\nNe kaลพdรฝ si mลฏลพe dovolit zaplatit 20โ€“200 dolarลฏ mฤ›sรญฤnฤ› za pล™edplatnรฉ AI. Studenti, vรฝvojรกล™i z rozvรญjejรญcรญch se zemรญ, amatรฉล™i a freelanceล™i potล™ebujรญ pล™รญstup ke kvalitnรญm modelลฏm za nulovou cenu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vestavฤ›nรญ poskytovatelรฉ bezplatnรฉ รบrovnฤ›** โ€” Nativnรญ podpora pro 100% bezplatnรฉ poskytovatele: iFlow (5 neomezenรฝch modelลฏ pล™es OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezenรฉ modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisรญc tokenลฏ/mฤ›sรญc zdarma)\n- **Ollama Cloud** โ€” Cloudovฤ› hostovanรฉ modely Ollama na `api.ollama.com` s bezplatnou รบrovnรญ โ€žLight usageโ€œ; pouลพijte prefix `ollamacloud/`\n- **Kombinace pouze zdarma** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = 0 $/mฤ›sรญc s nulovรฝmi prostoji\n- **NVIDIA NIM Free Access** โ€” ~40 RPM developerskรฝ pล™รญstup k vรญce neลพ 70 modelลฏm na build.nvidia.com (pล™echod z kreditลฏ na ฤistรฉ limity rychlosti)\n- **Strategie optimalizace nรกkladลฏ** โ€“ Strategie smฤ›rovรกnรญ, kterรก automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n
\n๐Ÿ”’ 5. โ€žPotล™ebuji chrรกnit svou brรกnu umฤ›lรฉ inteligence pล™ed neoprรกvnฤ›nรฝm pล™รญstupemโ€œ\n
\n\nPล™i zpล™รญstupnฤ›nรญ brรกny umฤ›lรฉ inteligence sรญti (LAN, VPS, Docker) mลฏลพe kdokoli s adresou spotล™ebovat tokeny/kvรณtu vรฝvojรกล™e. Bez ochrany jsou API zranitelnรก vลฏฤi zneuลพitรญ, prompt injection a dalลกรญmu zneuลพitรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sprรกva klรญฤลฏ API** โ€“ generovรกnรญ, rotace a vymezovรกnรญ rozsahu pro kaลพdรฉho poskytovatele s vyhrazenou strรกnkou `/dashboard/api-manager`\n- **Oprรกvnฤ›nรญ na รบrovni modelu** โ€“ Omezenรญ klรญฤลฏ API na konkrรฉtnรญ modely ( `openai/*` , zรกstupnรฉ znaky) pomocรญ pล™epรญnaฤe Povolit vลกe/Omezit\n- **Ochrana koncovรฝch bodลฏ API** โ€“ Vyลพaduje klรญฤ pro `/v1/models` a blokuje konkrรฉtnรญ poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** โ€” Vลกechny trasy dashboardu chrรกnฤ›nรฉ middlewarem `withAuth` + tokeny CSRF\n- **Omezovaฤ rychlosti** โ€” Omezovรกnรญ rychlosti na IP s konfigurovatelnรฝmi okny\n- **Filtrovรกnรญ IP adres** โ€” Seznam povolenรฝch/blokovanรฝch adres pro ล™รญzenรญ pล™รญstupu\n- **Ochrana proti vklรกdรกnรญ vรฝzev** โ€“ Sanitizace proti ลกkodlivรฝm vzorcลฏm vรฝzev\n- **ล ifrovรกnรญ AES-256-GCM** โ€“ pล™ihlaลกovacรญ รบdaje jsou v klidovรฉm stavu ลกifrovรกny\n\n
\n๐Ÿ›‘ 6. โ€žMลฏj poskytovatel selhal a jรก ztratil/a programovacรญ tokโ€œ\n
\n\nPoskytovatelรฉ umฤ›lรฉ inteligence se mohou stรกt nestabilnรญmi, vracet chyby 5xx nebo dosรกhnout doฤasnรฝch limitลฏ rychlosti. Pokud je vรฝvojรกล™ zรกvislรฝ na jedinรฉm poskytovateli, je jeho prรกce pล™eruลกena. Bez jistiฤลฏ mลฏลพe opakovanรฉ pokusy vรฉst k pรกdu aplikace.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Jistiฤ pro kaลพdรฝ model** โ€“ Automatickรฉ otevรญrรกnรญ/zavรญrรกnรญ s konfigurovatelnรฝmi prahovรฝmi hodnotami a dobou ochlazovรกnรญ (Zavล™eno/Otevล™eno/Poloviฤnรญ otevล™enรญ), rozsah definovanรฝ pro kaลพdรฝ model, aby se zabrรกnilo kaskรกdovรกnรญ blokลฏ\n- **Exponenciรกlnรญ odklad** โ€” Progresivnรญ zpoลพdฤ›nรญ opakovรกnรญ\n- **Anti-Thundering Herd** โ€” ochrana Mutex + semafor proti soubฤ›ลพnรฝm bouล™รญm s opakovanรฝmi pokusy\n- **Kombinovanรฉ zรกloลพnรญ ล™etฤ›zce** โ€“ Pokud primรกrnรญ poskytovatel selลพe, automaticky se propadne ล™etฤ›zcem bez zรกsahu.\n- **Kombinovanรฝ jistiฤ** โ€“ Automaticky deaktivuje selhรกvajรญcรญho poskytovatele v rรกmci kombinovanรฉho ล™etฤ›zce\n- **Dashboard stavu** โ€” Monitorovรกnรญ provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti, latence p50/p95/p99\n\n
\n๐Ÿ”ง 7. โ€žKonfigurace kaลพdรฉho nรกstroje umฤ›lรฉ inteligence je zdlouhavรก a opakujรญcรญ seโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Kaลพdรฝ nรกstroj potล™ebuje jinou konfiguraci (API endpoint, klรญฤ, model). Pล™ekonfigurovรกnรญ pล™i zmฤ›nฤ› poskytovatele nebo modelu je ztrรกta ฤasu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel nรกstrojลฏ CLI** โ€” Vyhrazenรก strรกnka s nastavenรญm jednรญm kliknutรญm pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generรกtor konfigurace GitHub Copilot** โ€“ Generuje `chatLanguageModels.json` pro VS Code s hromadnรฝm vรฝbฤ›rem modelu\n- **Prลฏvodce zavรกdฤ›nรญm** โ€“ 4krokovรฉ nastavenรญ pro zaฤรญnajรญcรญ uลพivatele\n- **Jeden koncovรฝ bod, vลกechny modely** โ€“ jednou nakonfigurujte `http://localhost:20128/v1` a zรญskejte pล™รญstup k vรญce neลพ 44 poskytovatelลฏm\n\n
\n๐Ÿ”‘ 8. โ€žSprรกva OAuth tokenลฏ od vรญce poskytovatelลฏ je pekloโ€œ\n
\n\nClaude Code, Codex, Gemini CLI, Copilot โ€“ vลกechny pouลพรญvajรญ OAuth 2.0 s tokeny s vyprลกenรญm platnosti. Vรฝvojรกล™i se musรญ neustรกle znovu autentizovat, ล™eลกit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdรกlenรฝch serverech. Obzvlรกลกtฤ› problematickรฝ je OAuth v LAN/VPS.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Automatickรก aktualizace tokenลฏ** โ€“ Tokeny OAuth se obnovujรญ na pozadรญ pล™ed vyprลกenรญm platnosti.\n- **Vestavฤ›nรฝ OAuth 2.0 (PKCE)** โ€“ Automatickรฝ tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow\n- **Multi-Account OAuth** โ€” Vรญce รบฤtลฏ na poskytovatele prostล™ednictvรญm extrakce tokenลฏ JWT/ID\n- **OAuth LAN/Remote Fix** โ€” Detekce privรกtnรญ IP adresy pro `redirect_uri` + manuรกlnรญ reลพim URL pro vzdรกlenรฉ servery\n- **OAuth Behind Nginx** โ€” Pouลพรญvรก `window.location.origin` pro kompatibilitu s reverznรญ proxy\n- **Prลฏvodce vzdรกlenรฝm OAuth** โ€“ Podrobnรฝ nรกvod k pล™ihlaลกovacรญm รบdajลฏm Google Cloud na VPS/Dockeru\n\n
\n๐Ÿ“Š 9. โ€žNevรญm, kolik utrรกcรญm ani kdeโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ vรญce placenรฝch poskytovatelลฏ, ale nemajรญ jednotnรฝ pล™ehled o vรฝdajรญch. Kaลพdรฝ poskytovatel mรก svลฏj vlastnรญ fakturaฤnรญ panel, ale neexistuje ลพรกdnรฝ konsolidovanรฝ pล™ehled. Mohou se hromadit neoฤekรกvanรฉ nรกklady.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard pro analรฝzu nรกkladลฏ** โ€“ Sledovรกnรญ nรกkladลฏ na token a sprรกva rozpoฤtu pro kaลพdรฉho poskytovatele\n- **Rozpoฤtovรฉ limity na รบroveลˆ** โ€“ Strop vรฝdajลฏ na รบroveลˆ, kterรฝ spouลกtรญ automatickรฝ zรกloลพnรญ reลพim\n- **Konfigurace cen podle modelu** โ€“ Konfigurovatelnรฉ ceny podle modelu\n- **Statistiky pouลพitรญ pro kaลพdรฝ klรญฤ API** โ€” Poฤet poลพadavkลฏ a ฤasovรฉ razรญtko poslednรญho pouลพitรญ pro kaลพdรฝ klรญฤ\n- **Analytickรฝ panel** โ€“ Statistickรฉ karty, graf vyuลพitรญ modelu, tabulka poskytovatelลฏ s mรญrou รบspฤ›ลกnosti a latencรญ\n\n
\n๐Ÿ› 10. โ€žNedokรกลพu diagnostikovat chyby a problรฉmy ve volรกnรญ umฤ›lรฉ inteligence.โ€œ\n
\n\nKdyลพ volรกnรญ selลพe, vรฝvojรกล™ nevรญ, zda se jednalo o limit rychlosti, vyprลกelรฝ token, ลกpatnรฝ formรกt nebo chybu poskytovatele. Fragmentovanรฉ protokoly napล™รญฤ rลฏznรฝmi terminรกly. Bez sledovatelnosti je ladฤ›nรญ metodou pokus-omyl.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel jednotnรฝch protokolลฏ** โ€“ 4 karty: Protokoly poลพadavkลฏ, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlรญลพeฤ protokolลฏ konzole** โ€” Prohlรญลพeฤ protokolลฏ v reรกlnรฉm ฤase ve stylu terminรกlu s barevnฤ› kรณdovanรฝmi รบrovnฤ›mi, automatickรฝm posouvรกnรญm, vyhledรกvรกnรญm a filtrovรกnรญm\n- **Protokoly proxy SQLite** โ€“ trvalรฉ protokoly, kterรฉ pล™eลพijรญ restart serveru\n- **Pล™ekladaฤskรฉ hล™iลกtฤ›** โ€” 4 reลพimy ladฤ›nรญ: Hล™iลกtฤ› (pล™eklad formรกtu), Tester chatu (okruลพnรญ), Testovacรญ stลฏl (dรกvkovรฝ), ลฝivรฝ monitor (v reรกlnรฉm ฤase)\n- **Telemetrie poลพadavkลฏ** โ€” latence p50/p95/p99 + trasovรกnรญ X-Request-Id\n- **Souborovรฉ protokolovรกnรญ s rotacรญ** โ€“ Konzolovรฝ interceptor zachycuje vลกe do protokolu JSON s rotacรญ na zรกkladฤ› velikosti\n- **Zprรกva o systรฉmovรฝch informacรญch** โ€” pล™รญkaz `npm run system-info` vygeneruje `system-info.txt` s kompletnรญm popisem vaลกeho prostล™edรญ (verze uzlu, verze OmniRoute, operaฤnรญ systรฉm, nรกstroje CLI, stav Dockeru/PM2). Pล™iloลพte jej pล™i hlรกลกenรญ problรฉmลฏ pro okamลพitรฉ tล™รญdฤ›nรญ.\n\n
\n๐Ÿ—๏ธ 11. โ€žNasazenรญ a รบdrลพba brรกny je sloลพitรกโ€œ\n
\n\nInstalace, konfigurace a รบdrลพba AI proxy v rลฏznรฝch prostล™edรญch (lokรกlnรญ, VPS, Docker, cloud) je pracnรก. Problรฉmy, jako jsou pevnฤ› zakรณdovanรฉ cesty, `EACCES` u adresรกล™ลฏ, konflikty portลฏ a multiplatformnรญ sestavenรญ, pล™ispรญvajรญ k obtรญลพรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **npm globรกlnรญ instalace** โ€” `npm install -g omniroute && omniroute` โ€” hotovo\n- **Docker Multi-Platform** โ€” AMD64 + nativnรญ ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** โ€” `base` (bez nรกstrojลฏ CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopovรก aplikace Electron** โ€” Nativnรญ aplikace pro Windows/macOS/Linux se systรฉmovou liลกtou, automatickรฝm spuลกtฤ›nรญm a offline reลพimem\n- **Reลพim rozdฤ›lenรฝch portลฏ** โ€“ API a ล™รญdicรญ panel na samostatnรฝch portech pro pokroฤilรฉ scรฉnรกล™e (reverznรญ proxy, sรญลฅovรกnรญ kontejnerลฏ)\n- **Cloud Sync** โ€“ Konfigurace synchronizace mezi zaล™รญzenรญmi pomocรญ Cloudflare Workers\n- **Zรกlohy databรกzรญ** โ€” Automatickรฉ zรกlohovรกnรญ, obnovenรญ, export a import vลกech nastavenรญ\n\n
\n๐ŸŒ 12. โ€žRozhranรญ je pouze v angliฤtinฤ› a mลฏj tรฝm nemluvรญ anglickyโ€œ\n
\n\nTรฝmy v neanglicky mluvรญcรญch zemรญch, zejmรฉna v Latinskรฉ Americe, Asii a Evropฤ›, se potรฝkajรญ s rozhranรญmi pouze v angliฤtinฤ›. Jazykovรฉ bariรฉry sniลพujรญ mรญru pล™ijetรญ a zvyลกujรญ chyby v konfiguraci.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard i18n โ€” 30 jazykลฏ** โ€” Vลกech 500+ klรกves je pล™eloลพeno vฤetnฤ› arabลกtiny, bulharลกtiny, dรกnลกtiny, nฤ›mฤiny, ลกpanฤ›lลกtiny, finลกtiny, francouzลกtiny, hebrejลกtiny, hindลกtiny, maฤarลกtiny, indonรฉลกtiny, italลกtiny, japonลกtiny, korejลกtiny, malajลกtiny, holandลกtiny, norลกtiny, polลกtiny, portugalลกtiny (PT/BR), rumunลกtiny, ruลกtiny, slovenลกtiny, ลกvรฉdลกtiny, thajลกtiny, ukrajinลกtiny, vietnamลกtiny, ฤรญnลกtiny, filipรญnลกtiny a angliฤtiny\n- **Podpora RTL** โ€“ Podpora psanรญ zprava doleva pro arabลกtinu a hebrejลกtinu\n- **Vรญcejazyฤnรฉ soubory README** โ€” 30 kompletnรญch pล™ekladลฏ dokumentace\n- **Vรฝbฤ›r jazyka** โ€” Ikona glรณbu v zรกhlavรญ pro pล™epรญnรกnรญ v reรกlnรฉm ฤase\n\n
\n๐Ÿ”„ 13. โ€žPotล™ebuji vรญc neลพ jen chat โ€“ potล™ebuji vloลพenรฉ soubory, obrรกzky, zvuk.โ€œ\n
\n\nUmฤ›lรก inteligence nenรญ jen dokonฤovรกnรญ chatu. Vรฝvojรกล™i potล™ebujรญ generovat obrรกzky, pล™episovat zvuk, vytvรกล™et embeddedy pro RAG, mฤ›nit poล™adรญ dokumentลฏ a moderovat obsah. Kaลพdรฉ API mรก jinรฝ koncovรฝ bod a formรกt.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vklรกdรกnรญ** โ€” `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generovรกnรญ obrรกzkลฏ** โ€” `/v1/images/generations` s 10 poskytovateli a vรญce neลพ 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Pล™evod textu na video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Pล™evod textu na hudbu** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Pล™epis zvuku** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Pล™evod textu na ล™eฤ** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a dalลกรญ stรกvajรญcรญ poskytovatelรฉ\n- **Moderovรกnรญ** โ€” `/v1/moderations` โ€” Kontroly bezpeฤnosti obsahu\n- **Zmฤ›na poล™adรญ** โ€” `/v1/rerank` โ€” Zmฤ›na poล™adรญ relevance dokumentu\n- **Responses API** โ€” Plnรก podpora `/v1/responses` pro Codex\n\n
\n๐Ÿงช 14. โ€žNemรกm zpลฏsob, jak testovat a porovnรกvat kvalitu napล™รญฤ modely.โ€œ\n
\n\nVรฝvojรกล™i chtฤ›jรญ vฤ›dฤ›t, kterรฝ model je pro jejich pล™รญpad pouลพitรญ nejlepลกรญ โ€“ kรณd, pล™eklad, uvaลพovรกnรญ โ€“ ale ruฤnรญ porovnรกvรกnรญ je pomalรฉ. Neexistujรญ ลพรกdnรฉ integrovanรฉ nรกstroje pro vyhodnocovรกnรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Hodnocenรญ LLM** โ€” Testovรกnรญ Golden setu s 10 pล™edinstalovanรฝmi pล™รญpady zahrnujรญcรญmi pozdravy, matematiku, geografii, generovรกnรญ kรณdu, dodrลพovรกnรญ JSON, pล™eklad, markdown, odmรญtnutรญ bezpeฤnostnรญch poลพadavkลฏ\n- **4 strategie shody** โ€” `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovacรญ lavice pro pล™ekladatelskรฉ hล™iลกtฤ›** โ€” Dรกvkovรฉ testovรกnรญ s vรญce vstupy a oฤekรกvanรฝmi vรฝstupy, porovnรกnรญ napล™รญฤ poskytovateli\n- **Tester chatu** โ€” Kompletnรญ okruลพnรญ cesta s vizuรกlnรญm vykreslovรกnรญm odpovฤ›dรญ\n- **ลฝivรฝ monitor** โ€” Stream vลกech poลพadavkลฏ prochรกzejรญcรญch proxy serverem v reรกlnรฉm ฤase\n\n
\n๐Ÿ“ˆ 15. โ€žPotล™ebuji ลกkรกlovat bez ztrรกty vรฝkonuโ€œ\n
\n\nS rostoucรญm objemem poลพadavkลฏ generujรญ stejnรฉ otรกzky bez uklรกdรกnรญ do mezipamฤ›ti duplicitnรญ nรกklady. Bez idempotence duplicitnรญ poลพadavky plรฝtvajรญ zpracovรกnรญm. Je nutnรฉ dodrลพovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sรฉmantickรก mezipamฤ›ลฅ** โ€” Dvouvrstvรก mezipamฤ›ลฅ (signatura + sรฉmantika) sniลพuje nรกklady a latenci\n- **Idempotence poลพadavku** โ€” 5s deduplikaฤnรญ okno pro identickรฉ poลพadavky\n- **Detekce limitu rychlosti** โ€“ sledovรกnรญ otรกฤek za minutu (RPM), minimรกlnรญ mezera a maximรกlnรญ soubฤ›ลพnรฉ sledovรกnรญ pro kaลพdรฉho poskytovatele\n- **Upravitelnรฉ limity rychlosti** โ€” Konfigurovatelnรฉ vรฝchozรญ hodnoty v Nastavenรญ โ†’ Odolnost s perzistencรญ\n- **Mezipamฤ›ลฅ pro ovฤ›ล™enรญ klรญฤลฏ API** โ€” tล™รญvrstvรก mezipamฤ›ลฅ pro vรฝkon produkฤnรญho prostล™edรญ\n- **Dashboard s telemetriรญ** โ€“ latence p50/p95/p99, statistiky mezipamฤ›ti, dostupnost\n\n
\n๐Ÿค– 16. โ€žChci mรญt chovรกnรญ modelลฏ globรกlnฤ› pod kontrolouโ€œ\n
\n\nVรฝvojรกล™i, kteล™รญ chtฤ›jรญ vลกechny odpovฤ›di v urฤitรฉm jazyce, se specifickรฝm tรณnem nebo chtฤ›jรญ omezit tokeny pro uvaลพovรกnรญ. Konfigurace tรฉto funkce v kaลพdรฉm nรกstroji/poลพadavku je nepraktickรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vloลพenรญ systรฉmovรฉho prompt** โ€“ Globรกlnรญ prompt aplikovanรฝ na vลกechny poลพadavky\n- **Validace rozpoฤtu Thinking** โ€” ล˜รญzenรญ alokace tokenลฏ na poลพadavek (prลฏchozรญ, automatickรฉ, vlastnรญ, adaptivnรญ)\n- **6 strategiรญ smฤ›rovรกnรญ** โ€“ Globรกlnรญ strategie, kterรฉ urฤujรญ, jak jsou poลพadavky distribuovรกny\n- **Smฤ›rovaฤ se zรกstupnรฝmi znaky** โ€” vzory `provider/*` dynamicky smฤ›rujรญ k libovolnรฉmu poskytovateli\n- **Pล™epรญnรกnรญ povolenรญ/zakรกzรกnรญ kombinacรญ** โ€“ Pล™epรญnรกnรญ kombinacรญ pล™รญmo z ล™รญdicรญho panelu\n- **Pล™epรญnรกnรญ poskytovatele** โ€“ Povolenรญ/zakรกzรกnรญ vลกech pล™ipojenรญ pro poskytovatele jednรญm kliknutรญm\n- **Blokovanรญ poskytovatelรฉ** โ€“ Vylouฤenรญ konkrรฉtnรญch poskytovatelลฏ ze seznamu `/v1/models`\n\n
\n๐Ÿงฐ 17. โ€žPotล™ebuji nรกstroje MCP jako prvotล™รญdnรญ produktovรฉ funkce.โ€œ\n
\n\nMnoho bran umฤ›lรฉ inteligence odhaluje MCP pouze jako skrytรฝ implementaฤnรญ detail. Tรฝmy potล™ebujรญ viditelnou a spravovatelnou operaฤnรญ vrstvu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- MCP se zobrazuje v navigaci na ล™รญdicรญm panelu a na kartฤ› protokolu koncovรฉho bodu.\n- Vyhrazenรก strรกnka pro sprรกvu MCP s procesy, nรกstroji, rozsahy a auditem\n- Vestavฤ›nรฝ rychlรฝ start pro `omniroute --mcp` a onboarding klienta\n\n
\n๐Ÿง  18. โ€žPotล™ebuji orchestraci A2A se synchronizacรญ a cestami รบloh streamu.โ€œ\n
\n\nPracovnรญ postupy agentลฏ vyลพadujรญ jak pล™รญmรฉ odpovฤ›di, tak dlouhodobรฉ streamovanรฉ provรกdฤ›nรญ s kontrolou ลพivotnรญho cyklu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Koncovรฝ bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamovรกnรญ SSE s ลกรญล™enรญm stavu terminรกlu\n- Rozhranรญ API ลพivotnรญho cyklu รบloh pro `tasks/get` a `tasks/cancel`\n\n
\n๐Ÿ›ฐ๏ธ 19. โ€žPotล™ebuji skuteฤnรฝ stav procesu MCP, ne odhadovanรฝ stav.โ€œ\n
\n\nProvoznรญ tรฝmy potล™ebujรญ vฤ›dฤ›t, zda je MCP skuteฤnฤ› aktivnรญ, nejen zda je API dosaลพitelnรฉ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Soubor bฤ›hovรฉho heartbeatu s PID, ฤasovรฝmi razรญtky, transportem, poฤtem nรกstrojลฏ a reลพimem rozsahu\n- API stavu MCP kombinujรญcรญ prezenฤnรญ signรกl a nedรกvnou aktivitu\n- Karty stavu uลพivatelskรฉho rozhranรญ pro zobrazenรญ aktuรกlnosti procesลฏ/provozuschopnosti/prezenฤnรญho signรกlu\n\n
\n๐Ÿ“‹ 20. โ€žPotล™ebuji auditovatelnรฉ provedenรญ nรกstroje MCPโ€œ\n
\n\nKdyลพ nรกstroje mฤ›nรญ konfiguraci nebo spouลกtฤ›jรญ operaฤnรญ akce, tรฝmy potล™ebujรญ forenznรญ sledovatelnost.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Protokolovรกnรญ auditu pro volรกnรญ nรกstrojลฏ MCP s podporou SQLite\n- Filtruje podle nรกstroje, รบspฤ›chu/neรบspฤ›chu, klรญฤe API a strรกnkovรกnรญ\n- Tabulka auditu dashboardu + koncovรฉ body statistik pro automatizaci\n\n
\n๐Ÿ” 21. โ€žPotล™ebuji omezenรก oprรกvnฤ›nรญ MCP pro kaลพdou integraci.โ€œ\n
\n\nRลฏznรญ klienti by mฤ›li mรญt pล™รญstup ke kategoriรญm nรกstrojลฏ s nejniลพลกรญmi oprรกvnฤ›nรญmi.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- 9 detailnรญch MCP sond pro kontrolovanรฝ pล™รญstup k nรกstrojลฏm\n- Vynucenรญ rozsahu a viditelnost v uลพivatelskรฉm rozhranรญ sprรกvy MCP\n- Bezpeฤnรก vรฝchozรญ poloha pro provoznรญ nรกstroje\n\n
\nโš™๏ธ 22. โ€žPotล™ebuji provoznรญ kontroly bez nutnosti pล™esouvรกnรญโ€œ\n
\n\nTรฝmy potล™ebujรญ rychlรฉ zmฤ›ny v bฤ›hovรฉm prostล™edรญ bฤ›hem incidentลฏ nebo nรกkladovรฝch udรกlostรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Pล™epnฤ›te aktivaci komba pล™รญmo z ล™รญdicรญho panelu MCP\n- Pouลพรญvejte profily odolnosti z pล™eddefinovanรฝch balรญฤkลฏ zรกsad\n- Resetujte stav jistiฤe ze stejnรฉho ovlรกdacรญho panelu\n\n
\n๐Ÿ”„ 23. โ€žPotล™ebuji ลพivรฝ pล™ehled o ลพivotnรญm cyklu รบkolลฏ A2A a jejich zruลกenรญ.โ€œ\n
\n\nBez pล™ehledu o ลพivotnรญm cyklu je obtรญลพnรฉ tล™รญdit incidenty รบkolลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Vรฝpis/filtrovรกnรญ รบkolลฏ podle stรกtu/dovednosti s strรกnkovรกnรญm\n- Podrobnรฝ pล™ehled metadat รบloh, udรกlostรญ a artefaktลฏ\n- Koncovรฝ bod zruลกenรญ รบlohy a akce uลพivatelskรฉho rozhranรญ s potvrzenรญm\n\n
\n๐ŸŒŠ 24. โ€žPotล™ebuji metriky aktivnรญho streamu pro A2A zรกtฤ›ลพโ€œ\n
\n\nStreamovacรญ pracovnรญ postupy vyลพadujรญ provoznรญ pล™ehled o soubฤ›ลพnosti a ลพivรฝch pล™ipojenรญch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- ฤŒรญtaฤe aktivnรญch streamลฏ integrovanรฉ do stavu A2A\n- ฤŒasovรฉ razรญtko poslednรญho รบkolu a poฤty pro jednotlivรฉ stavy\n- Karty A2A dashboardu pro monitorovรกnรญ provozu v reรกlnรฉm ฤase\n\n
\n๐Ÿชช 25. โ€žPotล™ebuji standardnรญ vyhledรกvรกnรญ agentลฏ pro klientyโ€œ\n
\n\nExternรญ klienti a orchestratoล™i potล™ebujรญ pro onboarding strojovฤ› ฤitelnรก metadata.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazenรฉ v uลพivatelskรฉm rozhranรญ pro sprรกvu\n- API pro stav A2A zahrnuje metadata pro zjiลกลฅovรกnรญ pro automatizaci\n\n
\n๐Ÿงญ 26. โ€žPotล™ebuji v uลพivatelskรฉm rozhranรญ produktu zjistitelnost protokolu.โ€œ\n
\n\nPokud uลพivatelรฉ nemohou objevit protokolovรฉ povrchy, kvalita pล™ijetรญ a podpory klesรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Strรกnka Konsolidovanรฉ **koncovรฉ body** s kartami pro koncovรฉ body Proxy, MCP, A2A a API\n- Pล™epรญnรกnรญ stavu inline sluลพby (Online/Offline) pro MCP a A2A\n- Odkazy z pล™ehledu na vyhrazenรฉ karty pro sprรกvu\n\n
\n๐Ÿงช 27. โ€žPotล™ebuji komplexnรญ ovฤ›ล™enรญ protokolu se skuteฤnรฝmi klienty.โ€œ\n
\n\nSimulovanรฉ testy nestaฤรญ k ovฤ›ล™enรญ kompatibility protokolu pล™ed vydรกnรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sada E2E, kterรก spouลกtรญ aplikaci a pouลพรญvรก skuteฤnรฝ transport klienta MCP SDK.\n- Klientskรฉ testy A2A pro toky zjiลกลฅovรกnรญ, odesรญlรกnรญ, streamovรกnรญ, naฤรญtรกnรญ a zruลกenรญ\n- Kล™รญลพovรก kontrola tvrzenรญ oproti API pro audit MCP a รบkoly A2A\n\n
\n๐Ÿ“ก 28. โ€žPotล™ebuji jednotnou pozorovatelnost napล™รญฤ vลกemi rozhranรญmiโ€œ\n
\n\nRozdฤ›lenรญ pozorovatelnosti podle protokolu vytvรกล™รญ slepรก mรญsta a delลกรญ MTTR.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรฉ dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie poลพadavkลฏ napล™รญฤ vrstvami OpenAI, MCP a A2A\n- Provoznรญ API pro stav a automatizaci\n\n
\n๐Ÿ’ผ 29. โ€žPotล™ebuji jeden runtime pro proxy + nรกstroje + orchestraci agentลฏโ€œ\n
\n\nSpouลกtฤ›nรญ mnoha samostatnรฝch sluลพeb zvyลกuje provoznรญ nรกklady a poฤet poruch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Proxy, MCP server a A2A server kompatibilnรญ s OpenAI v jednom balรญฤku\n- Sdรญlenรฉ ovฤ›ล™ovรกnรญ, odolnost, รบloลพiลกtฤ› dat a pozorovatelnost\n- Konzistentnรญ model politik napล™รญฤ vลกemi interakฤnรญmi plochami\n\n
\n๐Ÿš€ 30. โ€žPotล™ebuji agentskรฉ pracovnรญ postupy bez slepenรญ kรณdu.โ€œ\n
\n\nTรฝmy ztrรกcejรญ rychlost pล™i spojovรกnรญ vรญce ad-hoc sluลพeb a skriptลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรก strategie koncovรฝch bodลฏ pro klienty a agenty\n- Vestavฤ›nรก uลพivatelskรก rozhranรญ pro sprรกvu protokolลฏ a cesty pro ovฤ›ล™ovรกnรญ kouล™e\n- Zรกklady pล™ipravenรฉ pro produkฤnรญ prostล™edรญ (zabezpeฤenรญ, protokolovรกnรญ, odolnost, zรกlohovรกnรญ)\n\n### Pล™รญklady hernรญch plรกnลฏ (integrovanรฉ pล™รญpady uลพitรญ)\n\n**Pล™รญruฤka A: Maximalizace placenรฉho pล™edplatnรฉho + levnรฉ zรกlohovรกnรญ**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Pล™รญruฤka B: Kรณdovacรญ stack s nulovรฝmi nรกklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Pล™รญruฤka C: Nonstop zรกloลพnรญ ล™etฤ›zec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Pล™รญruฤka D: Operace agentลฏ s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Zaฤnฤ›te zdarma โ€” Nulovรฉ nรกklady na konfiguraci\n\n> Nastavte si kรณdovรกnรญ s umฤ›lou inteligencรญ bฤ›hem nฤ›kolika minut za **0 $/mฤ›sรญc** . Propojte tyto bezplatnรฉ รบฤty a vyuลพijte vestavฤ›nou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelรฉ odemฤeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Pล™ipojenรญ **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€“ **neomezenฤ›** |\n| 2 | Pล™ipojenรญ k **iFlow** (Google OAuth) | kimi-k2-myลกlenรญ, qwen3-coder-plus, deepseek-r1... โ€” **neomezenฤ›** |\n| 3 | Pล™ipojenรญ **Qwen** (kรณd zaล™รญzenรญ) | qwen3-coder-plus, qwen3-coder-flash... โ€” **neomezenฤ›** |\n| 4 | Pล™ipojenรญ **rozhranรญ pล™รญkazovรฉho ล™รกdku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180 000 GBP/mฤ›sรญc zdarma** |\n| 5 | `/dashboard/combos` โ†’ ล ablona **Free Stack (0 $)** | Automatickรฉ zaล™azenรญ vลกech bezplatnรฝch poskytovatelลฏ do routingu |\n\n**V libovolnรฉm IDE/CLI naveฤte:** `http://localhost:20128/v1` ยท Klรญฤ API: `any-string` ยท Hotovo.\n\n> **Volitelnรฉ doplลˆkovรฉ krytรญ (takรฉ zdarma):** Groq API klรญฤ (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelลฏ), Cerebras (1 milion tok/den).\n\n## โšก Rychlรฝ start\n\n### 1) Nainstalujte a spusลฅte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uลพivatelรฉ pnpm:** Po instalaci spusลฅte `pnpm approve-builds -g` , abyste povolili nativnรญ skripty pro sestavenรญ vyลพadovanรฉ programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard se otevรญrรก na `http://localhost:20128` a zรกkladnรญ URL API je `http://localhost:20128/v1` .\n\n| Pล™รญkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuลกtฤ›nรญ serveru ( `PORT=20128` , API a dashboard na stejnรฉm portu) |\n| `omniroute --port 3000` | Nastavte kanonickรฝ/API port na 3000 |\n| `omniroute --mcp` | Spuลกtฤ›nรญ MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevรญrat prohlรญลพeฤ automaticky |\n| `omniroute --help` | Zobrazit nรกpovฤ›du |\n\nVolitelnรฝ reลพim s rozdฤ›lenรฝm portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Pล™ipojte poskytovatele a vytvoล™te si klรญฤ API\n\n1. Otevล™ete Dashboard โ†’ `Providers` a pล™ipojte alespoลˆ jednoho poskytovatele (klรญฤ OAuth nebo API).\n2. Otevล™ete Dashboard โ†’ `Endpoints` a vytvoล™te API klรญฤ.\n3. (Volitelnรฉ) Otevล™ete Dashboard โ†’ `Combos` a nastavte zรกloลพnรญ ล™etฤ›zec.\n\n### 3) Nasmฤ›rujte svลฏj kรณdovacรญ nรกstroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilnรญmi s OpenAI.\n\n### 4) Povolenรญ a ovฤ›ล™enรญ protokolลฏ (v2.0)\n\n**MCP (pro operace ล™รญzenรฉ nรกstroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak pล™ipojte svรฉho MCP klienta pล™es `stdio` a otestujte nรกstroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovnรญ postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ovฤ›ล™te vลกe od zaฤรกtku do konce (doporuฤeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ovฤ›ล™uje skuteฤnรฉ toky klientลฏ MCP a A2A v porovnรกnรญ se spuลกtฤ›nou aplikacรญ.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute je k dispozici jako veล™ejnรฝ obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlรฝ bฤ›h:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostล™edรญ:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Pouลพรญvรกnรญ Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | ล tรญtek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovฤ›jลกรญ stabilnรญ verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuรกlnรญ verze |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktopovรก aplikace โ€“ offline a vลพdy zapnutรก\n\n> ๐Ÿ†• **NOVINKA!** OmniRoute je nynรญ k dispozici jako **nativnรญ desktopovรก aplikace** pro Windows, macOS a Linux.\n\nSpusลฅte OmniRoute jako samostatnou desktopovou aplikaci โ€“ pro lokรกlnรญ modely nenรญ potล™eba ลพรกdnรฝ terminรกl, prohlรญลพeฤ ani internet. Aplikace zaloลพenรก na platformฤ› Electron obsahuje:\n\n- ๐Ÿ–ฅ๏ธ **Nativnรญ okno** โ€” Vyhrazenรฉ okno aplikace s integracรญ do systรฉmovรฉ liลกty\n- ๐Ÿ”„ **Automatickรฉ spuลกtฤ›nรญ** โ€” Spuลกtฤ›nรญ OmniRoute po pล™ihlรกลกenรญ do systรฉmu\n- ๐Ÿ”” **Nativnรญ oznรกmenรญ** โ€“ Zรญskejte upozornฤ›nรญ na vyฤerpรกnรญ kvรณty nebo problรฉmy s poskytovateli\n- โšก **Instalace jednรญm kliknutรญm** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline reลพim** โ€” Funguje plnฤ› offline s pล™iloลพenรฝm serverem\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systรฉmovรฝ zรกsobnรญk\n\nPo minimalizaci se OmniRoute nachรกzรญ v systรฉmovรฉ liลกtฤ› a nabรญzรญ rychlรฉ akce:\n\n- Otevล™รญt ล™รญdicรญ panel\n- Zmฤ›nit port serveru\n- Ukonฤit aplikaci\n\n๐Ÿ“– รšplnรก dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pล™ehled cen\n\n| รšroveลˆ | Poskytovatel | Nรกklady | Obnovenรญ kvรณty | Nejlepลกรญ pro |\n| --------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **๐Ÿ’ณ Pล˜EDPLATNร‰** | Claude Code (profesionรกl) | 20 dolarลฏ mฤ›sรญฤnฤ› | 5 hodin + tรฝdnฤ› | Jiลพ pล™ihlรกลกen/a k odbฤ›ru |\n| Kodex (Plus/Pro) | 20โ€“200 USD/mฤ›sรญc | 5 hodin + tรฝdnฤ› | Uลพivatelรฉ OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisรญc mฤ›sรญฤnฤ› + 1 tisรญc dennฤ› | Kaลพdรฝ! |\n| GitHub Copilot | 10โ€“19 USD/mฤ›sรญc | Mฤ›sรญฤnรญ | Uลพivatelรฉ GitHubu |\n| **๐Ÿ”‘ KLรฤŒ API** | NVIDIA NIM | **ZDARMA** (vรฝvoj navลพdy) | ~40 ot./min | 70+ otevล™enรฝch modelลฏ |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ na svฤ›tฤ› |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisรญc otรกฤek za minutu | Ultrarychlรก lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | ลฝรกdnรฝ | Nejlepลกรญ zdลฏvodnฤ›nรญ ceny a kvality |\n| xAI Grok-4 Rychlรฝ | **0,20/0,50 USD za 1 milion** ๐Ÿ†• | ลฝรกdnรฝ | Nejrychlejลกรญ + volรกnรญ nรกstroje, ultranรญzkรฉ |\n| xAI Grok-4 (standardnรญ) | 0,20/1,50 USD za 1 milion ๐Ÿ†• | ลฝรกdnรฝ | Vlajkovรก loฤ Reasoning od xAI |\n| Mistral | Zkuลกebnรญ verze zdarma + placenรฉ | Omezenรก sazba | Evropskรก umฤ›lรก inteligence |\n| OpenRouter | Platba za pouลพitรญ | ลฝรกdnรฝ | Vรญce neลพ 100 modelลฏ agregovรกno. |\n| **๐Ÿ’ฐ LEVNร‰** | GLM-5 (pล™es Z.AI) ๐Ÿ†• | 0,5 USD/1 milion | Dennฤ› v 10:00 | Vรฝstup 128 tisรญc obrazovรฝch bodลฏ, nejnovฤ›jลกรญ vlajkovรก loฤ |\n| GLM-4.7 | 0,6 USD/1 milion | Dennฤ› v 10:00 | Zรกloha rozpoฤtu |\n| MiniMax M2.5 ๐Ÿ†• | Vstup 0,3 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | รšvaha + agentnรญ รบkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | Nejlevnฤ›jลกรญ varianta |\n| Kimi K2.5 (Moonshot API) ๐Ÿ†• | Platba za pouลพitรญ | ลฝรกdnรฝ | Pล™รญmรฝ pล™รญstup k Moonshot API |\n| Kimi K2 | 9 dolarลฏ mฤ›sรญฤnฤ› bez zรกvazkลฏ | 10 milionลฏ tokenลฏ/mฤ›sรญc | Pล™edvรญdatelnรฉ nรกklady |\n| **๐Ÿ†“ ZDARMA** | iFlow | **0 dolarลฏ** | Neomezenรฝ | 5 modelลฏ neomezenฤ› |\n| Qwen | **0 dolarลฏ** | Neomezenรฝ | 4 modely neomezenฤ› |\n| Kiro | **0 dolarลฏ** | Neomezenรฝ | Claude Sonnet/Haiku (tvorce AWS) |\n\n> ๐Ÿ†• **Pล™idรกny novรฉ modely (bล™ezen 2026):** ล™ada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkovรกno na 1143 ms โ€“ o 30 % rychlejลกรญ neลพ Gemini 2.5 Flash), GLM-5 pล™es Z.AI s vรฝstupem 128K, uvaลพovรกnรญ MiniMax M2.5, aktualizovanรฉ ceny DeepSeek V3.2, Kimi K2.5 pล™es Moonshot Direct API.\n\n**๐Ÿ’ก Kombinovanรฝ balรญk za 0 $ โ€” Kompletnรญ bezplatnรก instalace:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\niFlow (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Nulovรฉ nรกklady. Nikdy nepล™estรกvejte s kรณdovรกnรญm.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a vลกechny zรกloลพnรญ reลพimy se provede automaticky โ€“ ลพรกdnรฉ ruฤnรญ pล™epรญnรกnรญ.\n\n---\n\n---\n\n## ๐Ÿ†“ Bezplatnรฉ modely โ€“ Co skuteฤnฤ› zรญskรกte\n\n> Vลกechny nรญลพe uvedenรฉ modely jsou **100% zdarma a nevyลพadujรญ ลพรกdnou kreditnรญ kartu** . OmniRoute mezi nimi automaticky propojรญ trasy, kdyลพ dojde jedna kvรณta โ€“ zkombinujte je vลกechny a zรญskejte tak nerozluฤnou kombinaci za 0 dolarลฏ.\n\n### ๐Ÿ”ต CLAUDE MODELS (pล™es Kiro โ€” AWS Builder ID)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-opus-4.6` | `kr/` | **Neomezenรฝ** | Nejnovฤ›jลกรญ opus od Kira |\n\n### ๐ŸŸข MODELY IFLOW (Bezplatnรฉ OAuth โ€” bez nutnosti platit kreditnรญ kartou)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-plus` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `deepseek-r1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `minimax-m2.1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `kimi-k2` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n\n### ๐ŸŸก MODELY QWEN (Ovฤ›ล™enรญ kรณdu zaล™รญzenรญ)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-next` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `vision-model` | `qw/` | **Neomezenรฝ** | Multimodรกlnรญ (obrรกzky) |\n\n### ๐ŸŸฃ Rozhranรญ GEMINI CLI (Google OAuth)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisรญc tok/mฤ›sรญc** + 1 tisรญc/den | Mฤ›sรญฤnรญ reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisรญc mฤ›sรญฤnฤ› (sdรญlenรฝ bazรฉn) | Vysokรก kvalita |\n\n### โšซ NVIDIA NIM (Bezplatnรฝ klรญฤ API โ€” build.nvidia.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vรฝvojรกล™) | ลฝรกdnรฝ limit tokenลฏ | **~40 ot./min** | Vรญce neลพ 70 modelลฏ; pล™echod na ฤistรฉ limity sazeb v polovinฤ› roku 2025 |\n\nOblรญbenรฉ bezplatnรฉ modely: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct` , `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Bezplatnรฝ klรญฤ API โ€” inference.cerebras.ai)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenลฏ/den** | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ inference LLM na svฤ›tฤ›; dennฤ› se resetuje |\n\nDostupnรฉ zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Bezplatnรฝ API klรญฤ โ€” console.groq.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisรญc otรกฤek za minutu** | 30 ot./min na model | ลฝรกdnรก kreditnรญ karta; limit 429, neรบฤtovรกno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **๐Ÿ’ก Ultimรกtnรญ bezplatnรฝ zรกsobnรญk:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> โ†’ iFlow (5 models, unlimited)\n> โ†’ Qwen (4 models, unlimited)\n> โ†’ Gemini CLI (180K/mo)\n> โ†’ Cerebras (1M tok/day)\n> โ†’ Groq (14.4K req/day)\n> โ†’ NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a uลพ nikdy nebudete platit za umฤ›lou inteligenci.\n\n## ๐ŸŽ™๏ธ Kombinovanรก transkripce zdarma\n\n> Pล™episujte libovolnรฉ audio/video za **0 $** โ€“ Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako zรกloลพnรญ nรกstroj, Groq Whisper jako neomezenรก nouzovรก zรกloha.\n\n| Poskytovatel | Bezplatnรฉ kredity | Nejlepลกรญ model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| ๐ŸŸข **Deepgram** | **200 dolarลฏ zdarma** (registrace) | `nova-3` โ€” nejvyลกลกรญ pล™esnost, vรญce neลพ 30 jazykลฏ | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ต **AssemblyAI** | **50 dolarลฏ zdarma** (registrace) | `universal-3-pro` โ€” kapitoly, sentiment, osobnรญ รบdaje | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ด **Groq** | **Navลพdy zdarma** | `whisper-large-v3` โ€” OpenAI ล epot | 30 ot./min (omezenรก rychlost) |\n\n**Navrhovanรก kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nPak v `/dashboard/media` โ†’ zรกloลพka **Pล™epis** : nahrajte libovolnรฝ zvukovรฝ nebo video soubor โ†’ vyberte kombinovanรฝ koncovรฝ bod โ†’ zรญskejte pล™epis v podporovanรฝch formรกtech.\n\n## ๐Ÿ’ก Klรญฤovรฉ vlastnosti\n\nOmniRoute v2.0 je navrลพen jako operaฤnรญ platforma, nikoli pouze jako proxy pro relรฉ.\n\n### ๐Ÿ†• Novรฉ โ€” Vylepลกenรญ inspirovanรก ClawRouterem (bล™ezen 2026)\n\n| Funkce | Co to dฤ›lรก |\n| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Rychlรก rodina** | Modely xAI za 0,20 USD/0,50 USD/M โ€“ v benchmarku 1143 ms (o 30 % rychlejลกรญ neลพ Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 pล™es Z.AI** | 128 tisรญc vรฝstupnรญch dat, 0,5 USD/1 milion USD โ€“ nejnovฤ›jลกรญ vlajkovรก loฤ rodiny GLM |\n| ๐Ÿ”ฎ **MiniMax M2.5** | รšvaha + agentnรญ รบkoly za 0,30 USD/1 milion โ€“ vรฝznamnรฝ upgrade oproti M2.1 |\n| ๐ŸŽฏ **Pล™รญznak volรกnรญ nรกstroje pro kaลพdรฝ model** | `toolCalling: true/false` v registru โ€” AutoCombo pล™eskakuje modely, kterรฉ nepodporujรญ nรกstroje. |\n| ๐ŸŒ **Detekce vรญcejazyฤnรฉho zรกmฤ›ru** | Klรญฤovรก slova PT/ZH/ES/AR v bodovรกnรญ AutoCombo โ€“ lepลกรญ vรฝbฤ›r modelu pro neanglickรฝ obsah |\n| ๐Ÿ“Š **Zรกloลพnรญ metody ล™รญzenรฉ benchmarkem** | Skuteฤnรก latence p95 z ลพivรฝch poลพadavkลฏ poskytuje kombinovanรฉ skรณre โ€“ AutoCombo se uฤรญ ze skuteฤnรฝch dat |\n| ๐Ÿ” **Poลพรกdat o deduplikaci** | Okno pro deduplikaci na zรกkladฤ› hashovรกnรญ obsahu โ€“ bezpeฤnรฉ pro vรญce agentลฏ, zabraลˆuje duplicitnรญm platbรกm |\n| ๐Ÿ”Œ **Strategie pro zรกsuvnรฉ routery** | Rozลกiล™itelnรฉ rozhranรญ `RouterStrategy` โ€“ pล™idejte si vlastnรญ logiku smฤ›rovรกnรญ jako pluginy |\n\n### ๐Ÿš€ Pล™edchozรญ verze v2.0.9+ โ€” Hล™iลกtฤ›, otisky prstลฏ v CLI a ACP\n\n| Funkce | Co to dฤ›lรก |\n| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Modelovรฉ hล™iลกtฤ›** | Strรกnka ล™รญdicรญho panelu pro pล™รญmรฉ testovรกnรญ libovolnรฉho modelu โ€“ selektory poskytovatele/modelu/koncovรฉho bodu, editor Monaco, streamovรกnรญ, pล™eruลกenรญ, naฤasovรกnรญ |\n| ๐Ÿ” **Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** | ล˜azenรญ hlaviฤek/tฤ›l serveru podle poskytovatele tak, aby odpovรญdalo nativnรญm podpisลฏm CLI โ€“ pล™epรญnรกnรญ pro jednotlivรฉ poskytovatele v Nastavenรญ > Zabezpeฤenรญ. **Vaลกe IP adresa proxy serveru je zachovรกna.** |\n| ๐Ÿค **Podpora ACP (Agent Client Protocol)** | Vyhledรกvรกnรญ agentลฏ CLI (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 dalลกรญch), generรกtor procesลฏ, koncovรฝ bod `/api/acp/agents` |\n| ๐Ÿค– **ล˜รญdicรญ panel agentลฏ ACP** | Ladฤ›nรญ โ€บ Strรกnka Agenti โ€” mล™รญลพka 14 agentลฏ se stavem instalace, verzรญ a formulรกล™em pro vlastnรญ agenta pro libovolnรฝ nรกstroj CLI. Uลพivatelรฉ **OpenCode** zรญskajรญ tlaฤรญtko โ€žStรกhnout opencode.jsonโ€œ, kterรฉ automaticky vygeneruje konfiguraci pล™ipravenou k pouลพitรญ se vลกemi dostupnรฝmi modely. |\n| ๐Ÿ”ง **Smฤ›rovรกnรญ `apiFormat` pro vlastnรญ model** | Vlastnรญ modely s `apiFormat: \"responses\"` nynรญ sprรกvnฤ› smฤ›rujรญ do pล™ekladaฤe Responses API. |\n| ๐Ÿข **Izolace pracovnรญho prostoru Codexu** | Vรญce pracovnรญch prostorลฏ Codexu na jeden e-mail โ€“ OAuth sprรกvnฤ› oddฤ›luje pล™ipojenรญ podle ID pracovnรญho prostoru |\n| ๐Ÿ”„ **Automatickรก aktualizace elektronลฏ** | Desktopovรก aplikace kontroluje aktualizace + automaticky se instaluje po restartu |\n\n### ๐Ÿค– Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dฤ›lรก |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (16 nรกstrojลฏ)** | Nรกstroje IDE/agent prostล™ednictvรญm 3 transportลฏ: stdio, SSE ( `/api/mcp/sse` ), Streamovatelnรฝ HTTP ( `/api/mcp/stream` ) |\n| ๐Ÿค **A2A server (JSON-RPC + SSE)** | Spouลกtฤ›nรญ รบloh mezi agenty se synchronizacรญ a streamovรกnรญm |\n| ๐Ÿงญ **Konsolidovanรก strรกnka koncovรฝch bodลฏ** | Strรกnka pro sprรกvu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| ๐ŸŽš๏ธ **Pล™epรญnaฤe pro povolenรญ/zakรกzรกnรญ sluลพby** | Pล™epรญnaฤe ZAP/VYP pro MCP a A2A s trvalรฝm nastavenรญm (vรฝchozรญ: VYP) |\n| ๐Ÿ›ฐ๏ธ **Srdeฤnรญ tep za bฤ›hu MCP** | Skuteฤnรฝ stav procesu (pid, doba provozuschopnosti, stรกล™รญ heartbeatu, transport, reลพim rozsahu) |\n| ๐Ÿ“‹ **Auditnรญ zรกznam MCP** | Filtrovatelnรฉ protokoly auditu s hodnocenรญm รบspฤ›chu/neรบspฤ›chu a klรญฤovรฝm pล™iล™azenรญm |\n| ๐Ÿ” **Vynucovรกnรญ rozsahu MCP** | 9 podrobnรฝch oprรกvnฤ›nรญ pro ล™รญzenรฝ pล™รญstup k nรกstrojลฏm |\n| ๐Ÿ“ก **Sprรกva ลพivotnรญho cyklu รบkolลฏ A2A** | Seznam/filtrovรกnรญ รบloh, kontrola udรกlostรญ/artefaktลฏ, zruลกenรญ spuลกtฤ›nรฝch รบloh |\n| ๐Ÿ“‹ **Objevenรญ karty agenta** | `/.well-known/agent.json` pro automatickรฉ vyhledรกvรกnรญ klientลฏ |\n| ๐Ÿงช **Testovacรญ postroj Protocol E2E** | Skuteฤnรฉ MCP SDK + toky klientลฏ A2A v `test:protocols:e2e` |\n| โš™๏ธ **Provoznรญ kontroly** | Kombinace pล™epรญnaฤลฏ, pouลพitรญ profilลฏ odolnosti, resetovรกnรญ jistiฤลฏ z jednoho ovlรกdacรญho panelu |\n\n### ๐Ÿง  Smฤ›rovรกnรญ a inteligence\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| ๐ŸŽฏ **Inteligentnรญ ฤtyล™รบrovลˆovรฝ zรกloลพnรญ systรฉm** | Automatickรก trasa: Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma |\n| ๐Ÿ“Š **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** | Poฤet tokenลฏ v reรกlnรฉm ฤase + odpoฤet resetovรกnรญ pro kaลพdรฉho poskytovatele |\n| ๐Ÿ”„ **Pล™eklad formรกtu** | OpenAI โ†” Claude โ†” Gemini โ†” Odpovฤ›di s konverzemi bezpeฤnรฝmi pro schรฉma |\n| ๐Ÿ‘ฅ **Podpora vรญce รบฤtลฏ** | Vรญce รบฤtลฏ na poskytovatele s inteligentnรญm vรฝbฤ›rem |\n| ๐Ÿ”„ **Automatickรก aktualizace tokenลฏ** | Tokeny OAuth se automaticky obnovujรญ pล™i opakovanรฉm pokusu. |\n| ๐ŸŽจ **Vlastnรญ kombinace** | 6 vyvaลพovacรญch strategiรญ + ล™รญzenรญ zรกloลพnรญho ล™etฤ›zce |\n| ๐ŸŒ **Smฤ›rovaฤ se zรกstupnรฝmi znaky** | dynamickรฉ smฤ›rovรกnรญ `provider/*` |\n| ๐Ÿง  **Pล™emรฝลกlenรญ o rozpoฤtovรฝch kontrolรกch** | Limity pro prลฏchozรญ, automatickรฉ, vlastnรญ a adaptivnรญ uvaลพovรกnรญ |\n| ๐Ÿ”€ **Aliasy modelลฏ** | Vestavฤ›nรฉ + vlastnรญ aliasovรกnรญ modelลฏ a bezpeฤnost migrace |\n| โšก **Degradace pozadรญ** | Smฤ›rujte รบlohy na pozadรญ s nรญzkou prioritou na levnฤ›jลกรญ modely |\n| ๐Ÿงช **Chytrรฉ smฤ›rovรกnรญ s ohledem na รบkoly** | Automatickรฝ vรฝbฤ›r modelu podle typu obsahu (kรณdovรกnรญ/vize/analรฝza/sumarizace) |\n| ๐Ÿ’ฌ **Vstล™ikovรกnรญ do systรฉmu** | Globรกlnรญ kontroly chovรกnรญ uplatลˆovanรฉ konzistentnฤ› |\n| ๐Ÿ“„ **Kompatibilita API pro odpovฤ›di** | Plnรก podpora `/v1/responses` pro Codex a pokroฤilรฉ agentickรฉ pracovnรญ postupy |\n\n### ๐ŸŽต Multimodรกlnรญ API\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Generovรกnรญ obrรกzkลฏ** | `/v1/images/generations` s cloudovรฝm a lokรกlnรญm backendem |\n| ๐Ÿ“ **Vloลพenรญ** | `/v1/embeddings` pro vyhledรกvรกnรญ a RAG pipelines |\n| ๐ŸŽค **Pล™epis zvuku** | `/v1/audio/transcriptions` (Whisper a dalลกรญ poskytovatelรฉ) |\n| ๐Ÿ”Š **Pล™evod textu na ล™eฤ** | `/v1/audio/speech` (vรญce enginลฏ/poskytovatelลฏ) |\n| ๐ŸŽฌ **Generovรกnรญ videa** | `/v1/videos/generations` (pracovnรญ postupy ComfyUI + SD WebUI) |\n| ๐ŸŽต **Hudebnรญ generace** | `/v1/music/generations` (pracovnรญ postupy ComfyUI) |\n| ๐Ÿ›ก๏ธ **Moderovรกnรญ** | Bezpeฤnostnรญ kontroly `/v1/moderations` |\n| ๐Ÿ”€ **Zmฤ›na poล™adรญ** | `/v1/rerank` pro hodnocenรญ relevance |\n| ๐Ÿ” **Vyhledรกvรกnรญ na webu** ๐Ÿ†• | `/v1/search` โ€” 5 poskytovatelลฏ (Serper, Brave, Perplexity, Exa, Tavily), vรญce neลพ 6 500 zdarma/mฤ›sรญc, automatickรฉ pล™epnutรญ na zรกloลพnรญ systรฉm, mezipamฤ›ลฅ |\n\n### ๐Ÿ›ก๏ธ Odolnost, bezpeฤnost a sprรกva vฤ›cรญ veล™ejnรฝch\n\n| Funkce | Co to dฤ›lรก |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Jistiฤe** | Vypnutรญ/obnovenรญ pro kaลพdรฝ model s ovlรกdรกnรญm prahovรฝch hodnot |\n| ๐ŸŽฏ **Modely s ohledem na koncovรฉ body** | Vlastnรญ modely deklarujรญ podporovanรฉ koncovรฉ body + formรกt API |\n| ๐Ÿ›ก๏ธ **Stรกdo proti hromลฏm** | Ochrana mutexu a semaforu pล™i udรกlostech opakovรกnรญ/rychlosti |\n| ๐Ÿง  **Sรฉmantickรก + podpisovรก mezipamฤ›ลฅ** | Snรญลพenรญ nรกkladลฏ/latence dรญky dvฤ›ma vrstvรกm mezipamฤ›ti |\n| โšก **ลฝรกdost o idempotenci** | Okno ochrany proti duplikacรญm |\n| ๐Ÿ”’ **Falลกovรกnรญ otiskลฏ prstลฏ pomocรญ TLS** | Otisk TLS podobnรฝ prohlรญลพeฤi โ€“ **sniลพuje detekci botลฏ a nahlaลกovรกnรญ รบฤtลฏ** |\n| ๐Ÿ” **Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** | Shoduje se s nativnรญmi podpisy poลพadavkลฏ CLI โ€“ **sniลพuje riziko zablokovรกnรญ a zรกroveลˆ zachovรกvรก IP adresu proxy** |\n| ๐ŸŒ **Filtrovรกnรญ IP adres** | Ovlรกdรกnรญ seznamu povolenรฝch/blokovanรฝch poloลพek pro odhalenรก nasazenรญ |\n| ๐Ÿ“Š **Upravitelnรฉ limity rychlosti** | Konfigurovatelnรฉ globรกlnรญ/na รบrovni poskytovatele limity s perzistencรญ |\n| ๐Ÿ”‘ **Sprรกva klรญฤลฏ API a stanovenรญ rozsahu** | Bezpeฤnรฉ vydรกvรกnรญ/rotace klรญฤลฏ a kontroly modelu/poskytovatele |\n| ๐Ÿ›ก๏ธ **Chrรกnฤ›nรฉ `/models`** | Volitelnรฉ ovฤ›ล™ovรกnรญ a skrytรญ poskytovatele pro katalog modelลฏ |\n\n### ๐Ÿ“Š Pozorovatelnost a analytika\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| ๐Ÿ“ **ลฝรกdost + protokolovรกnรญ proxy** | รšplnรฉ protokolovรกnรญ poลพadavkลฏ/odpovฤ›dรญ a proxy |\n| ๐Ÿ“‹ **Sjednocenรฝ panel protokolลฏ** | Zobrazenรญ poลพadavkลฏ, proxy, auditu a konzole na jednรฉ strรกnce |\n| ๐Ÿ” **Vyลพรกdat si telemetrii** | Latence p50/p95/p99 a trasovรกnรญ poลพadavkลฏ |\n| ๐Ÿฅ **Panel zdravรญ** | Doba provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti |\n| ๐Ÿ’ฐ **Sledovรกnรญ nรกkladลฏ** | Kontrola rozpoฤtu a pล™ehled o cenรกch pro jednotlivรฉ modely |\n| ๐Ÿ“ˆ **Analytickรฉ vizualizace** | Pล™ehledy vyuลพitรญ modelลฏ/poskytovatelลฏ a zobrazenรญ trendลฏ |\n| ๐Ÿงช **Rรกmec hodnocenรญ** | Testovรกnรญ zlatรฉ sady s konfigurovatelnรฝmi strategiemi shody |\n\n### โ˜๏ธ Nasazenรญ a platforma\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| ๐ŸŒ **Nasazenรญ kdekoli** | Localhost, VPS, Docker, cloudovรก prostล™edรญ |\n| ๐Ÿ’พ **Synchronizace s cloudem** | Synchronizace konfigurace pล™es cloud worker |\n| ๐Ÿ”„ **Zรกlohovรกnรญ/Obnovenรญ** | Toky exportu/importu a obnovy po havรกrii |\n| ๐Ÿง™ **Prลฏvodce nรกstupem** | Prลฏvodce prvnรญm spuลกtฤ›nรญm |\n| ๐Ÿ”ง **Panel nรกstrojลฏ CLI** | Nastavenรญ oblรญbenรฝch kรณdovacรญch nรกstrojลฏ jednรญm kliknutรญm |\n| ๐ŸŽฎ **Modelovรฉ hล™iลกtฤ›** | Otestujte libovolnรฉho poskytovatele/model/koncovรฝ bod z ล™รญdicรญho panelu |\n| ๐Ÿ” **Pล™epรญnaฤ otiskลฏ prstลฏ v pล™รญkazovรฉm ล™รกdku** | Porovnรกvรกnรญ otiskลฏ prstลฏ podle poskytovatele v Nastavenรญ > Zabezpeฤenรญ |\n| ๐ŸŒ **i18n (30 jazykลฏ)** | Plnรก jazykovรก podpora dashboardu a dokumentace s psanรญm zprava doleva |\n| ๐Ÿ“‚ **Adresรกล™ vlastnรญch dat** | Pล™epsรกnรญ `DATA_DIR` pro umรญstฤ›nรญ รบloลพiลกtฤ› |\n\n### Hlubokรฝ pohled na funkce\n\n#### Chytrรก zรกloลพnรญ funkce s praktickou kontrolou nรกkladลฏ\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyลพ selลพe kvรณta, rychlost nebo stav, OmniRoute automaticky pล™ejde k dalลกรญmu kandidรกtovi bez nutnosti ruฤnรญho pล™epรญnรกnรญ.\n\n#### Sprรกva protokolลฏ, kterรก je viditelnรก a ovladatelnรก\n\n- MCP + A2A jsou viditelnรฉ v uลพivatelskรฉm rozhranรญ a dokumentaci (nejsou skrytรฉ)\n- API pro stav protokolu zpล™รญstupลˆujรญ ลพivรก provoznรญ data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnujรญ akce pro operace 2. dne (pล™epรญnรกnรญ kombinacรญ, resetovรกnรญ jistiฤลฏ, zruลกenรญ รบkolลฏ)\n\n#### Pracovnรญ postup pล™ekladatele + validace\n\nOblast pล™ekladatele zahrnuje:\n\n- **Hล™iลกtฤ›** : kontroly transformace poลพadavkลฏ\n- **Tester chatu** : kompletnรญ okruลพnรญ cesta poลพadavku/odpovฤ›di\n- **Testovacรญ stolice** : vรญce pล™รญpadลฏ v jednom bฤ›hu\n- **ลฝivรฝ monitor** : zobrazenรญ provozu v reรกlnรฉm ฤase\n\nPlus validace protokolu se skuteฤnรฝmi klienty pomocรญ `npm run test:protocols:e2e` .\n\n> ๐Ÿ“– **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** โ€” Referenฤnรญ informace o nรกstrojรญch, konfigurace IDE a pล™รญklady klientลฏ\n>\n> ๐Ÿ“– **[Soubor README pro A2A Server](src/lib/a2a/README.md)** โ€” Dovednosti, metody JSON-RPC, streamovรกnรญ a ลพivotnรญ cyklus รบloh\n\n## ๐Ÿงช Hodnocenรญ (Evals)\n\nOmniRoute obsahuje vestavฤ›nรฝ hodnotรญcรญ rรกmec pro testovรกnรญ kvality odpovฤ›dรญ LLM v porovnรกnรญ se zlatou sadou. Pล™รญstup k nฤ›mu je moลพnรฝ pล™es **Analรฝzy โ†’ Hodnocenรญ** v dashboardu.\n\n### Vestavฤ›nรก zlatรก sada\n\nPล™edinstalovanรก sada โ€žOmniRoute Golden Setโ€œ obsahuje testovacรญ pล™รญpady pro:\n\n- Zdravรญm, matematika, zemฤ›pis, generovรกnรญ kรณdu\n- Shoda s formรกtem JSON, pล™eklad, generovรกnรญ markdownลฏ\n- Bezpeฤnostnรญ odmรญtnutรญ (ลกkodlivรฝ obsah), poฤรญtรกnรญ, booleovskรก logika\n\n### Strategie hodnocenรญ\n\n| Strategie | Popis | Pล™รญklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Vรฝstup se musรญ pล™esnฤ› shodovat | `\"4\"` |\n| `contains` | Vรฝstup musรญ obsahovat podล™etฤ›zec (bez rozliลกenรญ velkรฝch a malรฝch pรญsmen) | `\"Paris\"` |\n| `regex` | Vรฝstup musรญ odpovรญdat vzoru regulรกrnรญch vรฝrazลฏ | `\"1.*2.*3\"` |\n| `custom` | Vlastnรญ JS funkce vracรญ true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Prลฏvodce nastavenรญm\n\n### Nastavenรญ protokolu (MCP + A2A)\n\n
\n๐Ÿงฉ Nastavenรญ MCP (Model Context Protocol)\n
\n\nSpuลกtฤ›nรญ MCP transportu v reลพimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporuฤenรฝ postup ovฤ›ล™enรญ:\n\n1. Pล™ipojte svรฉho MCP klienta pล™es stdio.\n2. Spusลฅte `omniroute_get_health` .\n3. Spusลฅte `omniroute_list_combos` .\n4. Otevล™ete `/dashboard/mcp` pro ovฤ›ล™enรญ prezenฤnรญho signรกlu, aktivity a auditu.\n\nUลพiteฤnรก API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n๐Ÿค Nastavenรญ A2A (Agent2Agent)\n
\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat รบkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSprรกva ลพivotnรญho cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvoznรญ uลพivatelskรฉ rozhranรญ:\n\n- `/dashboard/a2a` pro pozorovatelnost รบloh/stavลฏ/streamลฏ a akce kouล™enรญ\n\n
\n๐Ÿงช Komplexnรญ validace protokolu\n
\n\nOvฤ›ล™te oba protokoly se skuteฤnรฝmi klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTรญm se ovฤ›ล™uje:\n\n- Pล™ipojenรญ/seznam/volรกnรญ klienta MCP SDK\n- A2A objevovรกnรญ/odesรญlรกnรญ/streamovรกnรญ/zรญskรกvรกnรญ/zruลกenรญ\n- Kล™รญลพovรก kontrola dat v auditu MCP a API pro sprรกvu รบloh A2A\n\n
\n๐Ÿ’ณ Poskytovatelรฉ pล™edplatnรฉho\n
\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionรกly:** Pro sloลพitรฉ รบkoly pouลพรญvejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvรณtu pro kaลพdรฝ model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Sprรกva limitลฏ รบฤtu Codex (5h + tรฝdnฤ›)\n\nKaลพdรฝ รบฤet Codex mรก nynรญ pล™epรญnaฤe zรกsad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinovรฉho prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zรกsadu tรฝdennรญho prahu okna.\n- Prahovรฉ chovรกnรญ: kdyลพ povolenรฉ okno dosรกhne vyuลพitรญ >=90 %, je danรฝ รบฤet pล™eskoฤen.\n- Chovรกnรญ rotace: OmniRoute automaticky pล™esmฤ›ruje na dalลกรญ zpลฏsobilรฝ รบฤet Codex.\n- Chovรกnรญ pล™i resetovรกnรญ: Po `resetAt` urฤitรฉ doby se รบฤet automaticky opฤ›t stane zpลฏsobilรฝm.\n\nScรฉnรกล™e:\n\n- `5h ON` + `Weekly ON` : รบฤet je pล™eskoฤen, kdyลพ kterรฉkoli z oken dosรกhne prahovรฉ hodnoty.\n- `5h OFF` + `Weekly ON` : รบฤet mลฏลพe bรฝt zablokovรกn pouze tรฝdennรญm pouลพรญvรกnรญm.\n- `5h ON` + `Weekly OFF` : รบฤet mลฏลพe bรฝt zablokovรกn pouze pล™i 5hodinovรฉm pouลพรญvรกnรญ.\n- `resetAt` passed: รบฤet se automaticky znovu zapne (bez ruฤnรญho opฤ›tovnรฉho povolenรญ).\n\n### Gemini CLI (ZDARMA 180 000/mฤ›sรญc!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepลกรญ hodnota:** Obrovskรก bezplatnรก รบroveลˆ! Pouลพijte ji pล™ed placenรฝmi รบrovnฤ›mi.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n
\n๐Ÿ”‘ Poskytovatelรฉ klรญฤลฏ API\n
\n\n### NVIDIA NIM (BEZPLATNร pล™รญstup pro vรฝvojรกล™e โ€” vรญce neลพ 70 modelลฏ)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Zรญskejte zdarma klรญฤ API (vฤetnฤ› 1000 inferenฤnรญch kreditลฏ)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ NVIDIA NIM:\n - Klรญฤ API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a vรญce neลพ 50 dalลกรญch\n\n**Tip pro profesionรกly:** API kompatibilnรญ s OpenAI โ€“ funguje bez problรฉmลฏ s pล™ekladem formรกtลฏ OmniRoute!\n\n### Hlubokรฉ vyhledรกvรกnรญ\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatnรก รบroveลˆ!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Zรญskejte klรญฤ API (vฤetnฤ› bezplatnรฉ รบrovnฤ›)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionรกly:** Ultrarychlรก inference โ€“ nejlepลกรญ pro kรณdovรกnรญ v reรกlnรฉm ฤase!\n\n### OpenRouter (100+ modelลฏ)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ OpenRouter\n\n**Modely:** Zรญskejte pล™รญstup k vรญce neลพ 100 modelลฏm od vลกech hlavnรญch poskytovatelลฏ prostล™ednictvรญm jedinรฉho klรญฤe API.\n\n
\n๐Ÿ’ฐ Levnรญ poskytovatelรฉ (zรกloลพnรญ)\n
\n\n### GLM-4.7 (Dennรญ reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Zรญskejte klรญฤ API z kรณdovacรญho plรกnu\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API:\n - Poskytovatel: `glm`\n - Klรญฤ API: `your-key`\n\n**Pouลพitรญ:** `glm/glm-4.7`\n\n**Tip pro profesionรกly:** Programovacรญ plรกn nabรญzรญ 3ร— kvรณtu za cenu 1/7! Obnovuje se dennฤ› v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionรกly:** Nejlevnฤ›jลกรญ varianta pro dlouhรฝ kontext (1 milion tokenลฏ)!\n\n### Kimi K2 (pauลกรกlnรญ poplatek 9 dolarลฏ mฤ›sรญฤnฤ›)\n\n1. Odebรญrat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `kimi/kimi-latest`\n\n**Tip pro profesionรกly:** Fixnรญch 9 $/mฤ›sรญc za 10 milionลฏ tokenลฏ = efektivnรญ nรกklady 0,90 $/1 milion!\n\n
\n๐Ÿ†“ BEZPLATNร poskytovatelรฉ (nouzovรฉ zรกlohovรกnรญ)\n
\n\n### iFlow (5 BEZPLATNรCH modelลฏ pล™es OAuth)\n\n```bash\nDashboard โ†’ Connect iFlow\nโ†’ iFlow OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kรณdem zaล™รญzenรญ)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n๐ŸŽจ Vytvoล™te kombinace\n
\n\n### Pล™รญklad 1: Maximalizace pล™edplatnรฉho โ†’ Levnรฉ zรกlohovรกnรญ\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Pล™รญklad 2: Pouze zdarma (nulovรฉ nรกklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n๐Ÿ”ง Integrace s rozhranรญm pล™รญkazovรฉho ล™รกdku\n
\n\n### IDE kurzoru\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jednรญm kliknutรญm pouลพijte strรกnku **Nรกstroje CLI** na ล™รญdicรญm panelu nebo ruฤnฤ› upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Moลพnost 1 โ€“ Dashboard (doporuฤeno):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Moลพnost 2 โ€“ Manuรกlnรญ รบprava:** รšprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznรกmka:** OpenClaw funguje pouze s lokรกlnรญm OmniRoute. Mรญsto `localhost` pouลพijte `127.0.0.1` , abyste se vyhnuli problรฉmลฏm s rozliลกenรญm IPv6.\n\n### Cline / Pokraฤovat / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Pล™idรกnรญ OmniRoute jako vlastnรญho poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvoล™te/upravte `opencode.json` v koล™enovรฉm adresรกล™i projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` pล™idejte jakรฝkoli model dostupnรฝ ve vaลกem koncovรฉm bodu OmniRoute `/v1/models` . Pouลพijte formรกt `provider/model-id` z vaลกeho dashboardu OmniRoute.\n\n---\n\n## ๐Ÿ› ล˜eลกenรญ problรฉmลฏ\n\n
\nKliknutรญm rozbalรญte prลฏvodce ล™eลกenรญm problรฉmลฏ\n
\n\n**\"Jazykovรฝ model neposkytoval zprรกvy\"**\n\n- Kvรณta poskytovatele vyฤerpรกna โ†’ Zkontrolujte sledovรกnรญ kvรณt na ล™รญdicรญm panelu\n- ล˜eลกenรญ: Pouลพijte zรกloลพnรญ kombinovanou variantu nebo pล™ejdฤ›te na levnฤ›jลกรญ รบroveลˆ\n\n**Omezenรญ rychlosti**\n\n- Kvรณta pล™edplatnรฉho vyฤerpรกna โ†’ Pล™echod na GLM/MiniMax\n- Pล™idat kombo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vyprลกela**\n\n- Automaticky aktualizovรกno sluลพbou OmniRoute\n- Pokud problรฉmy pล™etrvรกvajรญ: Ovlรกdacรญ panel โ†’ Poskytovatel โ†’ Znovu pล™ipojit\n\n**Vysokรฉ nรกklady**\n\n- Zkontrolujte statistiky vyuลพitรญ v sekci Nรกstฤ›nka โ†’ Nรกklady\n- Pล™epnout primรกrnรญ model na GLM/MiniMax\n- Pro nekritickรฉ รบlohy pouลพijte bezplatnou รบroveลˆ (Gemini CLI, iFlow).\n\n**Porty ล™รญdicรญho panelu/API jsou nesprรกvnรฉ**\n\n- `PORT` je kanonickรฝ zรกkladnรญ port (a standardnฤ› port API)\n- `API_PORT` pล™episuje pouze posluchaฤ API kompatibilnรญ s OpenAI.\n- `DASHBOARD_PORT` pล™episuje pouze posluchaฤ dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaลกi veล™ejnou URL adresu ล™รญdicรญho panelu (pro zpฤ›tnรก volรกnรญ OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ovฤ›ล™te, zda `BASE_URL` odkazuje na vaลกi spuลกtฤ›nou instanci.\n- Ovฤ›ล™te, zda `CLOUD_URL` odkazuje na vรกลก oฤekรกvanรฝ cloudovรฝ koncovรฝ bod.\n- Udrลพujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na stranฤ› serveru.\n\n**Prvnรญ pล™ihlรกลกenรญ nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud nenรญ nastaveno, zรกloลพnรญ heslo je `123456`\n\n**ลฝรกdnรฉ protokoly poลพadavkลฏ**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test pล™ipojenรญ ukazuje โ€žNeplatnรฉโ€œ pro poskytovatele kompatibilnรญ s OpenAI**\n\n- Mnoho poskytovatelลฏ nezpล™รญstupลˆuje koncovรฝ bod `/models`\n- OmniRoute v1.0.6+ zahrnuje zรกloลพnรญ ovฤ›ล™enรญ pomocรญ dokonฤenรญ chatu\n- Zajistฤ›te, aby zรกkladnรญ URL adresa obsahovala pล™รญponu `/v1`\n\n### ๐Ÿ” OAuth na vzdรกlenรฉm serveru\n\n\n\n\n> **โš ๏ธ Dลฏleลพitรฉ pro uลพivatele, kteล™รญ provozujรญ OmniRoute na VPS, Dockeru nebo jakรฉmkoli vzdรกlenรฉm serveru**\n\n#### Proฤ selhรกvรก OAuth v rozhranรญ CLI Antigravity / Gemini na vzdรกlenรฝch serverech?\n\nPoskytovatelรฉ rozhranรญ CLI **Antigravity** a **Gemini** pouลพรญvajรญ **Google OAuth 2.0** . Google vyลพaduje, aby se `redirect_uri` v toku OAuth pล™esnฤ› shodoval s jednรญm z pล™edregistrovanรฝch URI v konzoli Google Cloud Console aplikace.\n\nPล™ihlaลกovacรญ รบdaje OAuth, kterรฉ jsou souฤรกstรญ OmniRoute, jsou registrovรกny **pouze pro `localhost`** . Kdyลพ pล™istupujete k OmniRoute na vzdรกlenรฉm serveru (napล™. `https://omniroute.myserver.com` ), Google odmรญtne ovฤ›ล™enรญ pomocรญ:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### ล˜eลกenรญ: Nakonfigurujte si vlastnรญ pล™ihlaลกovacรญ รบdaje OAuth\n\nV Google Cloud Console je potล™eba vytvoล™it **ID klienta OAuth 2.0** s URI vaลกeho serveru.\n\n#### Krok za krokem\n\n**1. Otevล™ete konzoli Google Cloud**\n\nPล™ejdฤ›te na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvoล™te novรฉ ID klienta OAuth 2.0**\n\n- Kliknฤ›te na **โ€ž+ Vytvoล™it pล™ihlaลกovacรญ รบdajeโ€œ** โ†’ **โ€žID klienta OAuthโ€œ**\n- Typ aplikace: **โ€žWebovรก aplikaceโ€œ**\n- Nรกzev: cokoli chcete (napล™. `OmniRoute Remote` )\n\n**3. Pล™idejte autorizovanรฉ URI pro pล™esmฤ›rovรกnรญ**\n\nDo pole **โ€žAutorizovanรฉ identifikรกtory URI pro pล™esmฤ›rovรกnรญโ€œ** pล™idejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraฤte `your-server.com` domรฉnou nebo IP adresou vaลกeho serveru (v pล™รญpadฤ› potล™eby uveฤte i port, napล™. `http://45.33.32.156:20128/callback` ).\n\n**4. Uloลพte a zkopรญrujte pล™ihlaลกovacรญ รบdaje**\n\nPo vytvoล™enรญ Google zobrazรญ **ID klienta** a **tajnรฝ kรณd klienta** .\n\n**5. Nastavenรญ promฤ›nnรฝch prostล™edรญ**\n\nVe vaลกem souboru `.env` (nebo promฤ›nnรฝch prostล™edรญ Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu pล™ipojit**\n\nล˜รญdicรญ panel โ†’ Poskytovatelรฉ โ†’ Antigravity (nebo Gemini CLI) โ†’ OAuth\n\nGoogle nynรญ bude sprรกvnฤ› pล™esmฤ›rovรกvat na `https://your-server.com/callback` .\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nPokud si teฤ nechcete nastavovat vlastnรญ pล™ihlaลกovacรญ รบdaje, mลฏลพete stรกle pouลพรญt **ruฤnรญ postup pro URL** :\n\n1. OmniRoute otevรญrรก autorizaฤnรญ URL od Googlu\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru).\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe (i kdyลพ se strรกnka nenaฤte)\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute.\n5. Kliknฤ›te na **โ€žPล™ipojitโ€œ**\n\n> To funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na to, zda se naฤetla pล™esmฤ›rovacรญ strรกnka.\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nChcete-li zรญskat pล™รญstup k pล™ihlaลกovacรญm รบdajลฏm bez vlastnรญ konfigurace, mลฏลพete pouลพรญt nรกsledujรญcรญ postup:\n\n1. OmniRoute otevล™e URL autorizace Google\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru)\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute\n5. Kliknฤ›te na **โ€žPล™ipojit\"**\n\n> Toto ล™eลกenรญ funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na naฤtenรญ pล™esmฤ›rovacรญ strรกnky.\n\n---\n\n## ๐Ÿ› ๏ธ Technologickรฝ stack\n\n
\nKliknutรญm rozbalรญte podrobnosti o technologickรฉm stacku\n
\n\n- **Runtime** : Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ **nenรญ podporovรกn** โ€” nativnรญ binรกrnรญ soubory `better-sqlite3` jsou nekompatibilnรญ)\n- **Jazyk** : TypeScript 5.9 โ€” **100% TypeScript** napล™รญฤ `src/` a `open-sse/` ( `any` v zรกkladnรญch modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databรกze** : LowDB (JSON) + SQLite (stav domรฉny + protokoly proxy + audit MCP + rozhodnutรญ o smฤ›rovรกnรญ)\n- **Schรฉmata** : Zod (validace I/O nรกstrojลฏ MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamovรกnรญ** : Udรกlosti odeslanรฉ serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klรญฤe + autorizace s rozsahem MCP\n- **Testovรกnรญ** : Node.js test runner + Vitest (900+ testลฏ vฤetnฤ› unit, integraฤnรญch, E2E)\n- **CI/CD** : Akce GitHubu (automatickรฉ publikovรกnรญ v npm + Docker Hub pล™i vydรกnรญ)\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **Balรญฤek** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistiฤ, exponenciรกlnรญ odstavenรญ, ochrana proti hromลฏm, faleลกnรฉ TLS, automatickรฉ kombinovanรฉ samoopravovรกnรญ\n\n---\n\n## ๐Ÿ“– Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uลพivatelskรก pล™รญruฤka](docs/USER_GUIDE.md) | Poskytovatelรฉ, kombinace, integrace CLI, nasazenรญ |\n| [Referenฤnรญ informace k API](docs/API_REFERENCE.md) | Vลกechny koncovรฉ body s pล™รญklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nรกstrojลฏ MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamovรกnรญ, sprรกva รบloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorovรฉ bodovรกnรญ, balรญฤky reลพimลฏ, samolรฉฤba |\n| [Odstraลˆovรกnรญ problรฉmลฏ](docs/TROUBLESHOOTING.md) | Bฤ›ลพnรฉ problรฉmy a jejich ล™eลกenรญ |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a internรญ prvky systรฉmu |\n| [Pล™ispรญvรกnรญ](CONTRIBUTING.md) | Nastavenรญ a pokyny pro vรฝvoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpeฤnostnรญ zรกsady](SECURITY.md) | Hlรกลกenรญ zranitelnostรญ a bezpeฤnostnรญ postupy |\n| [Nasazenรญ virtuรกlnรญho poฤรญtaฤe](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletnรญ prลฏvodce: Nastavenรญ virtuรกlnรญho poฤรญtaฤe + nginx + Cloudflare |\n| [Galerie funkcรญ](docs/FEATURES.md) | Vizuรกlnรญ prohlรญdka ล™รญdicรญho panelu se snรญmky obrazovky |\n| [Kontrolnรญ seznam vydรกnรญ](docs/RELEASE_CHECKLIST.md) | Kroky ovฤ›ล™enรญ pล™ed vydรกnรญm |\n\n---\n\n## ๐Ÿ—บ๏ธ Plรกn\n\nOmniRoute mรก **v plรกnu vรญce neลพ 210 funkcรญ** v nฤ›kolika fรกzรญch vรฝvoje. Zde jsou klรญฤovรฉ oblasti:\n\n| Kategorie | Plรกnovanรฉ funkce | Hlavnรญ body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| ๐Ÿง  **Smฤ›rovรกnรญ a inteligence** | 25+ | Smฤ›rovรกnรญ s nejniลพลกรญ latencรญ, smฤ›rovรกnรญ zaloลพenรฉ na tagech, kontrola kvรณt pล™ed vรฝstupem, vรฝbฤ›r รบฤtu P2C |\n| ๐Ÿ”’ **Zabezpeฤenรญ a dodrลพovรกnรญ pล™edpisลฏ** | 20+ | Zpevnฤ›nรญ SSRF, maskovรกnรญ pล™ihlaลกovacรญch รบdajลฏ, limit rychlosti pro kaลพdรฝ koncovรฝ bod, stanovenรญ rozsahu klรญฤลฏ pro sprรกvu |\n| ๐Ÿ“Š **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledovรกnรญ kvรณt v reรกlnรฉm ฤase, sledovรกnรญ nรกkladลฏ podle modelu |\n| ๐Ÿ”„ **Integrace poskytovatelลฏ** | 20+ | Dynamickรฝ registr modelลฏ, doba zchlazenรญ poskytovatelลฏ, Codex pro vรญce รบฤtลฏ, analรฝza kvรณt Copilota |\n| โšก **Vรฝkon** | 15+ | Dvojitรก vrstva mezipamฤ›ti, mezipamฤ›ลฅ vรฝzev, mezipamฤ›ลฅ odpovฤ›dรญ, udrลพovรกnรญ streamovรกnรญ, dรกvkovรฉ API |\n| ๐ŸŒ **Ekosystรฉm** | 10+ | WebSocket API, horkรฉ opฤ›tovnรฉ naฤรญtรกnรญ konfigurace, distribuovanรฉ รบloลพiลกtฤ› konfigurace, komerฤnรญ reลพim |\n\n### ๐Ÿ”œ Jiลพ brzy\n\n- ๐Ÿ”— **Integrace OpenCode** โ€” Nativnรญ podpora poskytovatelลฏ pro IDE kรณdovรกnรญ s AI v OpenCode\n- ๐Ÿ”— **Integrace TRAE** โ€” Plnรก podpora vรฝvojovรฉho rรกmce TRAE pro umฤ›lou inteligenci\n- ๐Ÿ“ฆ **Dรกvkovรฉ API** โ€” Asynchronnรญ dรกvkovรฉ zpracovรกnรญ hromadnรฝch poลพadavkลฏ\n- ๐ŸŽฏ **Smฤ›rovรกnรญ na zรกkladฤ› tagลฏ** โ€” Smฤ›rovรกnรญ poลพadavkลฏ na zรกkladฤ› vlastnรญch tagลฏ a metadat\n- ๐Ÿ’ฐ **Strategie nejniลพลกรญch nรกkladลฏ** โ€“ Automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n> ๐Ÿ“ รšplnรฉ specifikace funkcรญ jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobnรฝch specifikacรญ)\n\n---\n\n## ๐Ÿ‘ฅ Pล™ispฤ›vatelรฉ\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Pล™ispฤ›vatelรฉ](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak pล™ispฤ›t\n\n1. Vytvoล™enรญ forku repozitรกล™e\n2. Vytvoล™te si vlastnรญ vฤ›tev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrฤte zmฤ›ny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do vฤ›tve ( `git push origin feature/amazing-feature` )\n5. Otevล™รญt ลพรกdost o zmฤ›ny (pull request)\n\nPodrobnรฉ pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydรกnรญ novรฉ verze\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Hvฤ›zdnรก historie\n\n## Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## ๐Ÿ™ Podฤ›kovรกnรญ\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** โ€“ pลฏvodnรญmu projektu, kterรฝ inspiroval tento fork. OmniRoute stavรญ na tomto neuvฤ›ล™itelnรฉm zรกkladu s dalลกรญmi funkcemi, multimodรกlnรญmi API a kompletnรญm pล™epsรกnรญm TypeScriptu.\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€“ pลฏvodnรญ implementaci Go, kterรก inspirovala tento JavaScriptovรฝ port.\n\n---\n\n## ๐Ÿ“„ Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n
\n Vytvoล™eno s โค๏ธ pro vรฝvojรกล™e, kteล™รญ programujรญ 24 hodin dennฤ›, 7 dnรญ v tรฝdnu\n
\n

omniroute.online

\n
\n\n"}, "5d82ffa5035fe613056f43fb25172a0126d21323": {"t": 1785764471.6996114, "n": 94606, "h": "63d505373ea22e39", "c": "# ๐Ÿš€ OmniRoute โ€” Bezplatnรก brรกna umฤ›lรฉ inteligence\n\n### Nikdy nepล™estรกvejte s kรณdovรกnรญm. Chytrรฉ smฤ›rovรกnรญ k **BEZPLATNรM a levnรฝm modelลฏm AI** s automatickรฝm pล™epรญnรกnรญm mezi zรกloลพnรญmi systรฉmy.\n\n_Vรกลก univerzรกlnรญ API proxy โ€“ jeden endpoint, vรญce neลพ 44 poskytovatelลฏ, nulovรฉ vรฝpadky. Nynรญ s orchestracรญ agentลฏ **MCP a A2A** ._\n\n**Dokonฤenรญ chatu โ€ข Vklรกdรกnรญ โ€ข Generovรกnรญ obrรกzkลฏ โ€ข Video โ€ข Hudba โ€ข Audio โ€ข Zmฤ›na poล™adรญ โ€ข **Vyhledรกvรกnรญ na webu** โ€ข MCP server โ€ข A2A protokol โ€ข 100% TypeScript**\n\n---\n\n
\n
\n

\"verze\"Docker\"Licence\"\"Webovรฉ\"WhatsApp\"

\n

๐ŸŒ Webovรฉ strรกnky โ€ข ๐Ÿš€ Rychlรฝ start โ€ข ๐Ÿ’ก Funkce โ€ข ๐Ÿ“– Dokumentace โ€ข ๐Ÿ’ฐ Cenรญk โ€ข ๐Ÿ’ฌ WhatsApp

\n
\n\n๐ŸŒ **Dostupnรฉ v:** ๐Ÿ‡บ๐Ÿ‡ธ [Angliฤtina](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md)\n\n---\n\n## ๐Ÿ–ผ๏ธ Hlavnรญ ovlรกdacรญ panel\n\n
\"ล˜รญdicรญ
\n\n---\n\n## ๐Ÿ“ธ Nรกhled ล™รญdicรญho panelu\n\n
\nKliknutรญm zobrazรญte snรญmky obrazovky z ล™รญdicรญho panelu\n
\n\n| Strana | Snรญmek obrazovky |\n| ----------------------- | --------------------------------------------------- |\n| **Poskytovatelรฉ** | ![Poskytovatelรฉ](docs/screenshots/01-providers.png) |\n| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) |\n| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) |\n| **Zdravรญ** | ![Zdravรญ](docs/screenshots/04-health.png) |\n| **Pล™ekladatel** | ![Pล™ekladatel](docs/screenshots/05-translator.png) |\n| **Nastavenรญ** | ![Nastavenรญ](docs/screenshots/06-settings.png) |\n| **Nรกstroje CLI** | ![Nรกstroje CLI](docs/screenshots/07-cli-tools.png) |\n| **Protokoly pouลพรญvรกnรญ** | ![Pouลพรญvรกnรญ](docs/screenshots/08-usage.png) |\n| **Koncovรฉ body** | ![Koncovรฉ body](docs/screenshots/09-endpoint.png) |\n\n---\n\n### ๐Ÿค– Bezplatnรฝ poskytovatel umฤ›lรฉ inteligence pro vaลกe oblรญbenรฉ programรกtory\n\n_Pล™ipojte libovolnรฝ nรกstroj IDE nebo CLI s umฤ›lou inteligencรญ pล™es OmniRoute โ€” bezplatnou API brรกnu pro neomezenรฉ kรณdovรกnรญ._\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\"OpenClaw\"
OpenClaw
โญ 205 tisรญc 		\"NanoBot\"
NanoBot
โญ 20,9 tisรญc 		\"PicoClaw\"
PicoClaw
โญ 14,6 tisรญc 		\"ZeroClaw\"
ZeroClaw
โญ 9,9 tisรญc 		\"ลฝeleznรฝ
ลฝeleznรฝ drรกp
โญ 2,1 tisรญce
\"OpenCode\"
OpenCode
โญ 106 tisรญc 		\"Codex
Codex CLI
โญ 60,8 tisรญc 		\"Claude
Claude Code
โญ 67,3 tisรญc 		\"Gemini
Gemini CLI
โญ 94,7 tisรญc 		\"Kilo
Kilo kรณd
โญ 15,5 tisรญc
\n\n๐Ÿ“ก Vลกichni agenti se pล™ipojujรญ pล™es http://localhost:20128/v1 nebo http://cloud.omniroute.online/v1 โ€” jedna konfigurace, neomezenรฉ modely a kvรณty\n\n---\n\n## ๐Ÿค” Proฤ OmniRoute?\n\n**Pล™estaลˆte plรฝtvat penฤ›zi a narรกลพet na limity:**\n\n- Kvรณta pล™edplatnรฉho vyprลกรญ kaลพdรฝ mฤ›sรญc\n- Limity rychlosti vรกm zabrรกnรญ v kรณdovรกnรญ\n- Drahรก API (20โ€“50 USD/mฤ›sรญc na poskytovatele)\n- Ruฤnรญ pล™epรญnรกnรญ mezi poskytovateli\n\n**OmniRoute to ล™eลกรญ:**\n\n- โœ… **Maximalizujte pล™edplatnรฉ** โ€“ Sledujte kvรณtu, vyuลพijte kaลพdou ฤรกstku pล™ed resetovรกnรญm\n- โœ… **Automatickรฉ zรกloลพnรญ** โ€“ Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma, ลพรกdnรฉ vรฝpadky\n- โœ… **Vรญce รบฤtลฏ** โ€“ Round-robin mezi รบฤty u jednotlivรฝch poskytovatelลฏ\n- โœ… **Univerzรกlnรญ** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakรฝmkoli nรกstrojem CLI\n\n---\n\n## ๐Ÿ“ง Podpora\n\n> ๐Ÿ’ฌ **Pล™idejte se k naลกรญ komunitฤ›!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Zรญskejte pomoc, sdรญlejte tipy a buฤte v obraze.\n\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)\n- **Problรฉmy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)\n- **WhatsApp** : [Komunitnรญ skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)\n- **Pล™ispรญvรกnรญ** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevล™ete ลพรกdost o pล™รญspฤ›vek nebo si vyberte `good first issue`\n- **Pลฏvodnรญ projekt** : [9router od decolua](https://github.com/decolua/9router)\n\n### ๐Ÿ› Hlรกsรญte chybu?\n\nPล™i otevรญrรกnรญ problรฉmu spusลฅte pล™รญkaz system-info a pล™iloลพte vygenerovanรฝ soubor:\n\n```bash\nnpm run system-info\n```\n\nTรญm se vygeneruje soubor `system-info.txt` s verzรญ Node.js, verzรญ OmniRoute, podrobnostmi o operaฤnรญm systรฉmu, nainstalovanรฝmi nรกstroji CLI (iflow, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systรฉmovรฝmi balรญฤky โ€“ vลกe, co potล™ebujeme k rychlรฉ reprodukci vaลกeho problรฉmu. Soubor pล™iloลพte pล™รญmo k vaลกemu problรฉmu na GitHubu.\n\n---\n\n## ๐Ÿ”„ Jak to funguje\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)\nโ”‚ Tool โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ http://localhost:20128/v1\n โ†“\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ OmniRoute (Smart Router) โ”‚\nโ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚\nโ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚\nโ”‚ โ€ข Auto token refresh โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI\n โ”‚ โ†“ quota exhausted\n โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.\n โ”‚ โ†“ budget limit\n โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)\n โ”‚ โ†“ budget limit\n โ””โ”€โ†’ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)\n\nResult: Never stop coding, minimal cost\n```\n\n---\n\n## ๐ŸŽฏ Co ล™eลกรญ OmniRoute โ€” 30 skuteฤnรฝch problรฉmลฏ a pล™รญpadลฏ pouลพitรญ\n\n> **Kaลพdรฝ vรฝvojรกล™ pouลพรญvajรญcรญ nรกstroje umฤ›lรฉ inteligence se s tฤ›mito problรฉmy setkรกvรก dennฤ›.** OmniRoute byl vytvoล™en tak, aby je vลกechny vyล™eลกil โ€“ od pล™ekroฤenรญ nรกkladลฏ po regionรกlnรญ bloky, od nefunkฤnรญch tokลฏ OAuth aลพ po operace s protokoly a sledovatelnost v podniku.\n\n
\n๐Ÿ’ธ 1. โ€žPlatรญm si drahรฉ pล™edplatnรฉ, ale stรกle mฤ› ruลกรญ limityโ€œ\n
\n\nVรฝvojรกล™i platรญ za Claude Pro, Codex Pro nebo GitHub Copilot 20โ€“200 dolarลฏ mฤ›sรญฤnฤ›. I pล™i platbฤ› mรก kvรณta strop โ€“ 5 hodin pouลพรญvรกnรญ, tรฝdennรญ limity nebo limity rychlosti za minutu. Uprostล™ed kรณdovacรญ relace poskytovatel pล™estane reagovat a vรฝvojรกล™ ztrรกcรญ plynulost a produktivitu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Inteligentnรญ ฤtyล™รบrovลˆovรก zรกloลพnรญ sluลพba** โ€“ Pokud dojde kvรณta pล™edplatnรฉho, โ€‹โ€‹automaticky se pล™esmฤ›ruje na API klรญฤ โ†’ Levnรฉ โ†’ Zdarma bez manuรกlnรญho zรกsahu\n- **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** โ€“ Zobrazuje spotล™ebu tokenลฏ v reรกlnรฉm ฤase s odpoฤรญtรกvรกnรญm resetovรกnรญ (5 hodin, dennฤ›, tรฝdnฤ›)\n- **Podpora vรญce รบฤtลฏ** โ€“ Vรญce รบฤtลฏ u jednoho poskytovatele s automatickรฝm pล™epรญnรกnรญm โ€“ kdyลพ jeden dojde, pล™epne se na dalลกรญ\n- **Vlastnรญ kombinace** โ€” Pล™izpลฏsobitelnรฉ zรกloลพnรญ ล™etฤ›zce se 6 strategiemi vyvaลพovรกnรญ (fill-first, round robin, P2C, nรกhodnรฉ, nejmรฉnฤ› pouลพรญvanรฉ, nรกkladovฤ› optimalizovanรฉ)\n- **Codex Business Quotas** โ€” Sledovรกnรญ kvรณt pracovnรญho prostoru firmy/tรฝmu pล™รญmo v dashboardu\n\n
\n๐Ÿ”Œ 2. โ€žPotล™ebuji pouลพรญt vรญce poskytovatelลฏ, ale kaลพdรฝ mรก jinรฉ APIโ€œ\n
\n\nOpenAI pouลพรญvรก jeden formรกt, Claude (Anthropic) jinรฝ a Gemini jeลกtฤ› tล™etรญ. Pokud chce vรฝvojรกล™ testovat modely od rลฏznรฝch poskytovatelลฏ nebo mezi nimi pล™echรกzet, musรญ pล™ekonfigurovat SDK, zmฤ›nit koncovรฉ body a vypoล™รกdat se s nekompatibilnรญmi formรกty. Vlastnรญ poskytovatelรฉ (FriendLI, NIM) majรญ nestandardnรญ koncovรฉ body modelลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sjednocenรฝ koncovรฝ bod** โ€” Jeden `http://localhost:20128/v1` slouลพรญ jako proxy pro vลกech 44+ poskytovatelลฏ.\n- **Pล™eklad formรกtu** โ€” Automatickรฝ a transparentnรญ: OpenAI โ†” Claude โ†” Gemini โ†” Responses API\n- **Sanitizace odpovฤ›dรญ** โ€” Odstraลˆuje nestandardnรญ pole ( `x_groq` , `usage_breakdown` , `service_tier` ), kterรก poruลกujรญ OpenAI SDK v1.83+\n- **Normalizace rolรญ** โ€” Pล™evรกdรญ `developer` โ†’ `system` pro poskytovatele bez OpenAI; `system` โ†’ `user` pro GLM/ERNIE\n- **Extrakce tagลฏ Think** โ€” Extrahuje bloky `` z modelลฏ, jako je DeepSeek R1, do standardizovanรฉho `reasoning_content`\n- **Strukturovanรฝ vรฝstup pro Gemini** โ€” `json_schema` โ†’ automatickรก konverze `responseMimeType` / `responseSchema`\n- **Vรฝchozรญ hodnota `stream` je `false`** โ€“ Odpovรญdรก specifikaci OpenAI, ฤรญmลพ se zabrรกnรญ neoฤekรกvanรฉmu SSE v Python/Rust/Go SDK.\n\n
\n๐ŸŒ 3. โ€žMลฏj poskytovatel AI blokuje mลฏj region/zemiโ€œ\n
\n\nPoskytovatelรฉ jako OpenAI/Codex blokujรญ pล™รญstup z urฤitรฝch geografickรฝch oblastรญ. Uลพivatelรฉ se bฤ›hem pล™ipojenรญ OAuth a API dostรกvajรญ k chybรกm jako `unsupported_country_region_territory` . To je obzvlรกลกtฤ› frustrujรญcรญ pro vรฝvojรกล™e z rozvojovรฝch zemรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **3รบrovลˆovรก konfigurace proxy** โ€“ Konfigurovatelnรก proxy na 3 รบrovnรญch: globรกlnรญ (veลกkerรฝ provoz), pro jednotlivรฉ poskytovatele (pouze jeden poskytovatel) a pro jednotlivรฉ pล™ipojenรญ/klรญฤ\n- **Barevnฤ› kรณdovanรฉ odznaky proxy** โ€“ Vizuรกlnรญ indikรกtory: ๐ŸŸข globรกlnรญ proxy, ๐ŸŸก proxy poskytovatele, ๐Ÿ”ต proxy pล™ipojenรญ, vลพdy zobrazujรญcรญ IP adresu\n- **Vรฝmฤ›na tokenลฏ OAuth prostล™ednictvรญm proxy** โ€“ tok OAuth takรฉ prochรกzรญ pล™es proxy, ฤรญmลพ se ล™eลกรญ `unsupported_country_region_territory`\n- **Testy pล™ipojenรญ pล™es proxy** โ€“ Testy pล™ipojenรญ pouลพรญvajรญ nakonfigurovanรฝ proxy (jiลพ ลพรกdnรฉ pล™รญmรฉ obchรกzenรญ)\n- **Podpora SOCKS5** โ€” Plnรก podpora proxy SOCKS5 pro odchozรญ smฤ›rovรกnรญ\n- **TLS Fingerprint Spoofing** โ€” Otisk prstu TLS podobnรฝ prohlรญลพeฤi pomocรญ `wreq-js` pro obchรกzenรญ detekce botลฏ\n- **๐Ÿ” Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** โ€” Zmฤ›nรญ poล™adรญ zรกhlavรญ a polรญ v tฤ›le serveru tak, aby odpovรญdala nativnรญm binรกrnรญm podpisลฏm v CLI, ฤรญmลพ drasticky sniลพuje riziko nahlaลกovรกnรญ รบฤtu. IP adresa proxy je zachovรกna โ€” zรญskรกte souฤasnฤ› stealth **i** maskovรกnรญ IP adresy.\n\n
\n๐Ÿ†“ 4. โ€žChci pouลพรญvat umฤ›lou inteligenci pro kรณdovรกnรญ, ale nemรกm penรญzeโ€œ\n
\n\nNe kaลพdรฝ si mลฏลพe dovolit zaplatit 20โ€“200 dolarลฏ mฤ›sรญฤnฤ› za pล™edplatnรฉ AI. Studenti, vรฝvojรกล™i z rozvรญjejรญcรญch se zemรญ, amatรฉล™i a freelanceล™i potล™ebujรญ pล™รญstup ke kvalitnรญm modelลฏm za nulovou cenu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vestavฤ›nรญ poskytovatelรฉ bezplatnรฉ รบrovnฤ›** โ€” Nativnรญ podpora pro 100% bezplatnรฉ poskytovatele: iFlow (5 neomezenรฝch modelลฏ pล™es OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezenรฉ modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisรญc tokenลฏ/mฤ›sรญc zdarma)\n- **Ollama Cloud** โ€” Cloudovฤ› hostovanรฉ modely Ollama na `api.ollama.com` s bezplatnou รบrovnรญ โ€žLight usageโ€œ; pouลพijte prefix `ollamacloud/`\n- **Kombinace pouze zdarma** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = 0 $/mฤ›sรญc s nulovรฝmi prostoji\n- **NVIDIA NIM Free Access** โ€” ~40 RPM developerskรฝ pล™รญstup k vรญce neลพ 70 modelลฏm na build.nvidia.com (pล™echod z kreditลฏ na ฤistรฉ limity rychlosti)\n- **Strategie optimalizace nรกkladลฏ** โ€“ Strategie smฤ›rovรกnรญ, kterรก automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n
\n๐Ÿ”’ 5. โ€žPotล™ebuji chrรกnit svou brรกnu umฤ›lรฉ inteligence pล™ed neoprรกvnฤ›nรฝm pล™รญstupemโ€œ\n
\n\nPล™i zpล™รญstupnฤ›nรญ brรกny umฤ›lรฉ inteligence sรญti (LAN, VPS, Docker) mลฏลพe kdokoli s adresou spotล™ebovat tokeny/kvรณtu vรฝvojรกล™e. Bez ochrany jsou API zranitelnรก vลฏฤi zneuลพitรญ, prompt injection a dalลกรญmu zneuลพitรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sprรกva klรญฤลฏ API** โ€“ generovรกnรญ, rotace a vymezovรกnรญ rozsahu pro kaลพdรฉho poskytovatele s vyhrazenou strรกnkou `/dashboard/api-manager`\n- **Oprรกvnฤ›nรญ na รบrovni modelu** โ€“ Omezenรญ klรญฤลฏ API na konkrรฉtnรญ modely ( `openai/*` , zรกstupnรฉ znaky) pomocรญ pล™epรญnaฤe Povolit vลกe/Omezit\n- **Ochrana koncovรฝch bodลฏ API** โ€“ Vyลพaduje klรญฤ pro `/v1/models` a blokuje konkrรฉtnรญ poskytovatele ze seznamu\n- **Auth Guard + CSRF Protection** โ€” Vลกechny trasy dashboardu chrรกnฤ›nรฉ middlewarem `withAuth` + tokeny CSRF\n- **Omezovaฤ rychlosti** โ€” Omezovรกnรญ rychlosti na IP s konfigurovatelnรฝmi okny\n- **Filtrovรกnรญ IP adres** โ€” Seznam povolenรฝch/blokovanรฝch adres pro ล™รญzenรญ pล™รญstupu\n- **Ochrana proti vklรกdรกnรญ vรฝzev** โ€“ Sanitizace proti ลกkodlivรฝm vzorcลฏm vรฝzev\n- **ล ifrovรกnรญ AES-256-GCM** โ€“ pล™ihlaลกovacรญ รบdaje jsou v klidovรฉm stavu ลกifrovรกny\n\n
\n๐Ÿ›‘ 6. โ€žMลฏj poskytovatel selhal a jรก ztratil/a programovacรญ tokโ€œ\n
\n\nPoskytovatelรฉ umฤ›lรฉ inteligence se mohou stรกt nestabilnรญmi, vracet chyby 5xx nebo dosรกhnout doฤasnรฝch limitลฏ rychlosti. Pokud je vรฝvojรกล™ zรกvislรฝ na jedinรฉm poskytovateli, je jeho prรกce pล™eruลกena. Bez jistiฤลฏ mลฏลพe opakovanรฉ pokusy vรฉst k pรกdu aplikace.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Jistiฤ pro kaลพdรฝ model** โ€“ Automatickรฉ otevรญrรกnรญ/zavรญrรกnรญ s konfigurovatelnรฝmi prahovรฝmi hodnotami a dobou ochlazovรกnรญ (Zavล™eno/Otevล™eno/Poloviฤnรญ otevล™enรญ), rozsah definovanรฝ pro kaลพdรฝ model, aby se zabrรกnilo kaskรกdovรกnรญ blokลฏ\n- **Exponenciรกlnรญ odklad** โ€” Progresivnรญ zpoลพdฤ›nรญ opakovรกnรญ\n- **Anti-Thundering Herd** โ€” ochrana Mutex + semafor proti soubฤ›ลพnรฝm bouล™รญm s opakovanรฝmi pokusy\n- **Kombinovanรฉ zรกloลพnรญ ล™etฤ›zce** โ€“ Pokud primรกrnรญ poskytovatel selลพe, automaticky se propadne ล™etฤ›zcem bez zรกsahu.\n- **Kombinovanรฝ jistiฤ** โ€“ Automaticky deaktivuje selhรกvajรญcรญho poskytovatele v rรกmci kombinovanรฉho ล™etฤ›zce\n- **Dashboard stavu** โ€” Monitorovรกnรญ provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti, latence p50/p95/p99\n\n
\n๐Ÿ”ง 7. โ€žKonfigurace kaลพdรฉho nรกstroje umฤ›lรฉ inteligence je zdlouhavรก a opakujรญcรญ seโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Kaลพdรฝ nรกstroj potล™ebuje jinou konfiguraci (API endpoint, klรญฤ, model). Pล™ekonfigurovรกnรญ pล™i zmฤ›nฤ› poskytovatele nebo modelu je ztrรกta ฤasu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel nรกstrojลฏ CLI** โ€” Vyhrazenรก strรกnka s nastavenรญm jednรญm kliknutรญm pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline\n- **Generรกtor konfigurace GitHub Copilot** โ€“ Generuje `chatLanguageModels.json` pro VS Code s hromadnรฝm vรฝbฤ›rem modelu\n- **Prลฏvodce zavรกdฤ›nรญm** โ€“ 4krokovรฉ nastavenรญ pro zaฤรญnajรญcรญ uลพivatele\n- **Jeden koncovรฝ bod, vลกechny modely** โ€“ jednou nakonfigurujte `http://localhost:20128/v1` a zรญskejte pล™รญstup k vรญce neลพ 44 poskytovatelลฏm\n\n
\n๐Ÿ”‘ 8. โ€žSprรกva OAuth tokenลฏ od vรญce poskytovatelลฏ je pekloโ€œ\n
\n\nClaude Code, Codex, Gemini CLI, Copilot โ€“ vลกechny pouลพรญvajรญ OAuth 2.0 s tokeny s vyprลกenรญm platnosti. Vรฝvojรกล™i se musรญ neustรกle znovu autentizovat, ล™eลกit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdรกlenรฝch serverech. Obzvlรกลกtฤ› problematickรฝ je OAuth v LAN/VPS.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Automatickรก aktualizace tokenลฏ** โ€“ Tokeny OAuth se obnovujรญ na pozadรญ pล™ed vyprลกenรญm platnosti.\n- **Vestavฤ›nรฝ OAuth 2.0 (PKCE)** โ€“ Automatickรฝ tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow\n- **Multi-Account OAuth** โ€” Vรญce รบฤtลฏ na poskytovatele prostล™ednictvรญm extrakce tokenลฏ JWT/ID\n- **OAuth LAN/Remote Fix** โ€” Detekce privรกtnรญ IP adresy pro `redirect_uri` + manuรกlnรญ reลพim URL pro vzdรกlenรฉ servery\n- **OAuth Behind Nginx** โ€” Pouลพรญvรก `window.location.origin` pro kompatibilitu s reverznรญ proxy\n- **Prลฏvodce vzdรกlenรฝm OAuth** โ€“ Podrobnรฝ nรกvod k pล™ihlaลกovacรญm รบdajลฏm Google Cloud na VPS/Dockeru\n\n
\n๐Ÿ“Š 9. โ€žNevรญm, kolik utrรกcรญm ani kdeโ€œ\n
\n\nVรฝvojรกล™i pouลพรญvajรญ vรญce placenรฝch poskytovatelลฏ, ale nemajรญ jednotnรฝ pล™ehled o vรฝdajรญch. Kaลพdรฝ poskytovatel mรก svลฏj vlastnรญ fakturaฤnรญ panel, ale neexistuje ลพรกdnรฝ konsolidovanรฝ pล™ehled. Mohou se hromadit neoฤekรกvanรฉ nรกklady.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard pro analรฝzu nรกkladลฏ** โ€“ Sledovรกnรญ nรกkladลฏ na token a sprรกva rozpoฤtu pro kaลพdรฉho poskytovatele\n- **Rozpoฤtovรฉ limity na รบroveลˆ** โ€“ Strop vรฝdajลฏ na รบroveลˆ, kterรฝ spouลกtรญ automatickรฝ zรกloลพnรญ reลพim\n- **Konfigurace cen podle modelu** โ€“ Konfigurovatelnรฉ ceny podle modelu\n- **Statistiky pouลพitรญ pro kaลพdรฝ klรญฤ API** โ€” Poฤet poลพadavkลฏ a ฤasovรฉ razรญtko poslednรญho pouลพitรญ pro kaลพdรฝ klรญฤ\n- **Analytickรฝ panel** โ€“ Statistickรฉ karty, graf vyuลพitรญ modelu, tabulka poskytovatelลฏ s mรญrou รบspฤ›ลกnosti a latencรญ\n\n
\n๐Ÿ› 10. โ€žNedokรกลพu diagnostikovat chyby a problรฉmy ve volรกnรญ umฤ›lรฉ inteligence.โ€œ\n
\n\nKdyลพ volรกnรญ selลพe, vรฝvojรกล™ nevรญ, zda se jednalo o limit rychlosti, vyprลกelรฝ token, ลกpatnรฝ formรกt nebo chybu poskytovatele. Fragmentovanรฉ protokoly napล™รญฤ rลฏznรฝmi terminรกly. Bez sledovatelnosti je ladฤ›nรญ metodou pokus-omyl.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Panel jednotnรฝch protokolลฏ** โ€“ 4 karty: Protokoly poลพadavkลฏ, Protokoly proxy, Protokoly auditu, Konzole\n- **Prohlรญลพeฤ protokolลฏ konzole** โ€” Prohlรญลพeฤ protokolลฏ v reรกlnรฉm ฤase ve stylu terminรกlu s barevnฤ› kรณdovanรฝmi รบrovnฤ›mi, automatickรฝm posouvรกnรญm, vyhledรกvรกnรญm a filtrovรกnรญm\n- **Protokoly proxy SQLite** โ€“ trvalรฉ protokoly, kterรฉ pล™eลพijรญ restart serveru\n- **Pล™ekladaฤskรฉ hล™iลกtฤ›** โ€” 4 reลพimy ladฤ›nรญ: Hล™iลกtฤ› (pล™eklad formรกtu), Tester chatu (okruลพnรญ), Testovacรญ stลฏl (dรกvkovรฝ), ลฝivรฝ monitor (v reรกlnรฉm ฤase)\n- **Telemetrie poลพadavkลฏ** โ€” latence p50/p95/p99 + trasovรกnรญ X-Request-Id\n- **Souborovรฉ protokolovรกnรญ s rotacรญ** โ€“ Konzolovรฝ interceptor zachycuje vลกe do protokolu JSON s rotacรญ na zรกkladฤ› velikosti\n- **Zprรกva o systรฉmovรฝch informacรญch** โ€” pล™รญkaz `npm run system-info` vygeneruje `system-info.txt` s kompletnรญm popisem vaลกeho prostล™edรญ (verze uzlu, verze OmniRoute, operaฤnรญ systรฉm, nรกstroje CLI, stav Dockeru/PM2). Pล™iloลพte jej pล™i hlรกลกenรญ problรฉmลฏ pro okamลพitรฉ tล™รญdฤ›nรญ.\n\n
\n๐Ÿ—๏ธ 11. โ€žNasazenรญ a รบdrลพba brรกny je sloลพitรกโ€œ\n
\n\nInstalace, konfigurace a รบdrลพba AI proxy v rลฏznรฝch prostล™edรญch (lokรกlnรญ, VPS, Docker, cloud) je pracnรก. Problรฉmy, jako jsou pevnฤ› zakรณdovanรฉ cesty, `EACCES` u adresรกล™ลฏ, konflikty portลฏ a multiplatformnรญ sestavenรญ, pล™ispรญvajรญ k obtรญลพรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **npm globรกlnรญ instalace** โ€” `npm install -g omniroute && omniroute` โ€” hotovo\n- **Docker Multi-Platform** โ€” AMD64 + nativnรญ ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi)\n- **Profily Docker Compose** โ€” `base` (bez nรกstrojลฏ CLI) a `cli` (s Claude Code, Codex, OpenClaw)\n- **Desktopovรก aplikace Electron** โ€” Nativnรญ aplikace pro Windows/macOS/Linux se systรฉmovou liลกtou, automatickรฝm spuลกtฤ›nรญm a offline reลพimem\n- **Reลพim rozdฤ›lenรฝch portลฏ** โ€“ API a ล™รญdicรญ panel na samostatnรฝch portech pro pokroฤilรฉ scรฉnรกล™e (reverznรญ proxy, sรญลฅovรกnรญ kontejnerลฏ)\n- **Cloud Sync** โ€“ Konfigurace synchronizace mezi zaล™รญzenรญmi pomocรญ Cloudflare Workers\n- **Zรกlohy databรกzรญ** โ€” Automatickรฉ zรกlohovรกnรญ, obnovenรญ, export a import vลกech nastavenรญ\n\n
\n๐ŸŒ 12. โ€žRozhranรญ je pouze v angliฤtinฤ› a mลฏj tรฝm nemluvรญ anglickyโ€œ\n
\n\nTรฝmy v neanglicky mluvรญcรญch zemรญch, zejmรฉna v Latinskรฉ Americe, Asii a Evropฤ›, se potรฝkajรญ s rozhranรญmi pouze v angliฤtinฤ›. Jazykovรฉ bariรฉry sniลพujรญ mรญru pล™ijetรญ a zvyลกujรญ chyby v konfiguraci.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Dashboard i18n โ€” 30 jazykลฏ** โ€” Vลกech 500+ klรกves je pล™eloลพeno vฤetnฤ› arabลกtiny, bulharลกtiny, dรกnลกtiny, nฤ›mฤiny, ลกpanฤ›lลกtiny, finลกtiny, francouzลกtiny, hebrejลกtiny, hindลกtiny, maฤarลกtiny, indonรฉลกtiny, italลกtiny, japonลกtiny, korejลกtiny, malajลกtiny, holandลกtiny, norลกtiny, polลกtiny, portugalลกtiny (PT/BR), rumunลกtiny, ruลกtiny, slovenลกtiny, ลกvรฉdลกtiny, thajลกtiny, ukrajinลกtiny, vietnamลกtiny, ฤรญnลกtiny, filipรญnลกtiny a angliฤtiny\n- **Podpora RTL** โ€“ Podpora psanรญ zprava doleva pro arabลกtinu a hebrejลกtinu\n- **Vรญcejazyฤnรฉ soubory README** โ€” 30 kompletnรญch pล™ekladลฏ dokumentace\n- **Vรฝbฤ›r jazyka** โ€” Ikona glรณbu v zรกhlavรญ pro pล™epรญnรกnรญ v reรกlnรฉm ฤase\n\n
\n๐Ÿ”„ 13. โ€žPotล™ebuji vรญc neลพ jen chat โ€“ potล™ebuji vloลพenรฉ soubory, obrรกzky, zvuk.โ€œ\n
\n\nUmฤ›lรก inteligence nenรญ jen dokonฤovรกnรญ chatu. Vรฝvojรกล™i potล™ebujรญ generovat obrรกzky, pล™episovat zvuk, vytvรกล™et embeddedy pro RAG, mฤ›nit poล™adรญ dokumentลฏ a moderovat obsah. Kaลพdรฉ API mรก jinรฝ koncovรฝ bod a formรกt.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vklรกdรกnรญ** โ€” `/v1/embeddings` s 6 poskytovateli a 9+ modely\n- **Generovรกnรญ obrรกzkลฏ** โ€” `/v1/images/generations` s 10 poskytovateli a vรญce neลพ 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)\n- **Pล™evod textu na video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) a SD WebUI\n- **Pล™evod textu na hudbu** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen)\n- **Pล™epis zvuku** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3\n- **Pล™evod textu na ล™eฤ** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a dalลกรญ stรกvajรญcรญ poskytovatelรฉ\n- **Moderovรกnรญ** โ€” `/v1/moderations` โ€” Kontroly bezpeฤnosti obsahu\n- **Zmฤ›na poล™adรญ** โ€” `/v1/rerank` โ€” Zmฤ›na poล™adรญ relevance dokumentu\n- **Responses API** โ€” Plnรก podpora `/v1/responses` pro Codex\n\n
\n๐Ÿงช 14. โ€žNemรกm zpลฏsob, jak testovat a porovnรกvat kvalitu napล™รญฤ modely.โ€œ\n
\n\nVรฝvojรกล™i chtฤ›jรญ vฤ›dฤ›t, kterรฝ model je pro jejich pล™รญpad pouลพitรญ nejlepลกรญ โ€“ kรณd, pล™eklad, uvaลพovรกnรญ โ€“ ale ruฤnรญ porovnรกvรกnรญ je pomalรฉ. Neexistujรญ ลพรกdnรฉ integrovanรฉ nรกstroje pro vyhodnocovรกnรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Hodnocenรญ LLM** โ€” Testovรกnรญ Golden setu s 10 pล™edinstalovanรฝmi pล™รญpady zahrnujรญcรญmi pozdravy, matematiku, geografii, generovรกnรญ kรณdu, dodrลพovรกnรญ JSON, pล™eklad, markdown, odmรญtnutรญ bezpeฤnostnรญch poลพadavkลฏ\n- **4 strategie shody** โ€” `exact` , `contains` , `regex` , `custom` (JS funkce)\n- **Testovacรญ lavice pro pล™ekladatelskรฉ hล™iลกtฤ›** โ€” Dรกvkovรฉ testovรกnรญ s vรญce vstupy a oฤekรกvanรฝmi vรฝstupy, porovnรกnรญ napล™รญฤ poskytovateli\n- **Tester chatu** โ€” Kompletnรญ okruลพnรญ cesta s vizuรกlnรญm vykreslovรกnรญm odpovฤ›dรญ\n- **ลฝivรฝ monitor** โ€” Stream vลกech poลพadavkลฏ prochรกzejรญcรญch proxy serverem v reรกlnรฉm ฤase\n\n
\n๐Ÿ“ˆ 15. โ€žPotล™ebuji ลกkรกlovat bez ztrรกty vรฝkonuโ€œ\n
\n\nS rostoucรญm objemem poลพadavkลฏ generujรญ stejnรฉ otรกzky bez uklรกdรกnรญ do mezipamฤ›ti duplicitnรญ nรกklady. Bez idempotence duplicitnรญ poลพadavky plรฝtvajรญ zpracovรกnรญm. Je nutnรฉ dodrลพovat limity rychlosti na poskytovatele.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Sรฉmantickรก mezipamฤ›ลฅ** โ€” Dvouvrstvรก mezipamฤ›ลฅ (signatura + sรฉmantika) sniลพuje nรกklady a latenci\n- **Idempotence poลพadavku** โ€” 5s deduplikaฤnรญ okno pro identickรฉ poลพadavky\n- **Detekce limitu rychlosti** โ€“ sledovรกnรญ otรกฤek za minutu (RPM), minimรกlnรญ mezera a maximรกlnรญ soubฤ›ลพnรฉ sledovรกnรญ pro kaลพdรฉho poskytovatele\n- **Upravitelnรฉ limity rychlosti** โ€” Konfigurovatelnรฉ vรฝchozรญ hodnoty v Nastavenรญ โ†’ Odolnost s perzistencรญ\n- **Mezipamฤ›ลฅ pro ovฤ›ล™enรญ klรญฤลฏ API** โ€” tล™รญvrstvรก mezipamฤ›ลฅ pro vรฝkon produkฤnรญho prostล™edรญ\n- **Dashboard s telemetriรญ** โ€“ latence p50/p95/p99, statistiky mezipamฤ›ti, dostupnost\n\n
\n๐Ÿค– 16. โ€žChci mรญt chovรกnรญ modelลฏ globรกlnฤ› pod kontrolouโ€œ\n
\n\nVรฝvojรกล™i, kteล™รญ chtฤ›jรญ vลกechny odpovฤ›di v urฤitรฉm jazyce, se specifickรฝm tรณnem nebo chtฤ›jรญ omezit tokeny pro uvaลพovรกnรญ. Konfigurace tรฉto funkce v kaลพdรฉm nรกstroji/poลพadavku je nepraktickรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- **Vloลพenรญ systรฉmovรฉho prompt** โ€“ Globรกlnรญ prompt aplikovanรฝ na vลกechny poลพadavky\n- **Validace rozpoฤtu Thinking** โ€” ล˜รญzenรญ alokace tokenลฏ na poลพadavek (prลฏchozรญ, automatickรฉ, vlastnรญ, adaptivnรญ)\n- **6 strategiรญ smฤ›rovรกnรญ** โ€“ Globรกlnรญ strategie, kterรฉ urฤujรญ, jak jsou poลพadavky distribuovรกny\n- **Smฤ›rovaฤ se zรกstupnรฝmi znaky** โ€” vzory `provider/*` dynamicky smฤ›rujรญ k libovolnรฉmu poskytovateli\n- **Pล™epรญnรกnรญ povolenรญ/zakรกzรกnรญ kombinacรญ** โ€“ Pล™epรญnรกnรญ kombinacรญ pล™รญmo z ล™รญdicรญho panelu\n- **Pล™epรญnรกnรญ poskytovatele** โ€“ Povolenรญ/zakรกzรกnรญ vลกech pล™ipojenรญ pro poskytovatele jednรญm kliknutรญm\n- **Blokovanรญ poskytovatelรฉ** โ€“ Vylouฤenรญ konkrรฉtnรญch poskytovatelลฏ ze seznamu `/v1/models`\n\n
\n๐Ÿงฐ 17. โ€žPotล™ebuji nรกstroje MCP jako prvotล™รญdnรญ produktovรฉ funkce.โ€œ\n
\n\nMnoho bran umฤ›lรฉ inteligence odhaluje MCP pouze jako skrytรฝ implementaฤnรญ detail. Tรฝmy potล™ebujรญ viditelnou a spravovatelnou operaฤnรญ vrstvu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- MCP se zobrazuje v navigaci na ล™รญdicรญm panelu a na kartฤ› protokolu koncovรฉho bodu.\n- Vyhrazenรก strรกnka pro sprรกvu MCP s procesy, nรกstroji, rozsahy a auditem\n- Vestavฤ›nรฝ rychlรฝ start pro `omniroute --mcp` a onboarding klienta\n\n
\n๐Ÿง  18. โ€žPotล™ebuji orchestraci A2A se synchronizacรญ a cestami รบloh streamu.โ€œ\n
\n\nPracovnรญ postupy agentลฏ vyลพadujรญ jak pล™รญmรฉ odpovฤ›di, tak dlouhodobรฉ streamovanรฉ provรกdฤ›nรญ s kontrolou ลพivotnรญho cyklu.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Koncovรฝ bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream`\n- Streamovรกnรญ SSE s ลกรญล™enรญm stavu terminรกlu\n- Rozhranรญ API ลพivotnรญho cyklu รบloh pro `tasks/get` a `tasks/cancel`\n\n
\n๐Ÿ›ฐ๏ธ 19. โ€žPotล™ebuji skuteฤnรฝ stav procesu MCP, ne odhadovanรฝ stav.โ€œ\n
\n\nProvoznรญ tรฝmy potล™ebujรญ vฤ›dฤ›t, zda je MCP skuteฤnฤ› aktivnรญ, nejen zda je API dosaลพitelnรฉ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Soubor bฤ›hovรฉho heartbeatu s PID, ฤasovรฝmi razรญtky, transportem, poฤtem nรกstrojลฏ a reลพimem rozsahu\n- API stavu MCP kombinujรญcรญ prezenฤnรญ signรกl a nedรกvnou aktivitu\n- Karty stavu uลพivatelskรฉho rozhranรญ pro zobrazenรญ aktuรกlnosti procesลฏ/provozuschopnosti/prezenฤnรญho signรกlu\n\n
\n๐Ÿ“‹ 20. โ€žPotล™ebuji auditovatelnรฉ provedenรญ nรกstroje MCPโ€œ\n
\n\nKdyลพ nรกstroje mฤ›nรญ konfiguraci nebo spouลกtฤ›jรญ operaฤnรญ akce, tรฝmy potล™ebujรญ forenznรญ sledovatelnost.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Protokolovรกnรญ auditu pro volรกnรญ nรกstrojลฏ MCP s podporou SQLite\n- Filtruje podle nรกstroje, รบspฤ›chu/neรบspฤ›chu, klรญฤe API a strรกnkovรกnรญ\n- Tabulka auditu dashboardu + koncovรฉ body statistik pro automatizaci\n\n
\n๐Ÿ” 21. โ€žPotล™ebuji omezenรก oprรกvnฤ›nรญ MCP pro kaลพdou integraci.โ€œ\n
\n\nRลฏznรญ klienti by mฤ›li mรญt pล™รญstup ke kategoriรญm nรกstrojลฏ s nejniลพลกรญmi oprรกvnฤ›nรญmi.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- 9 detailnรญch MCP sond pro kontrolovanรฝ pล™รญstup k nรกstrojลฏm\n- Vynucenรญ rozsahu a viditelnost v uลพivatelskรฉm rozhranรญ sprรกvy MCP\n- Bezpeฤnรก vรฝchozรญ poloha pro provoznรญ nรกstroje\n\n
\nโš™๏ธ 22. โ€žPotล™ebuji provoznรญ kontroly bez nutnosti pล™esouvรกnรญโ€œ\n
\n\nTรฝmy potล™ebujรญ rychlรฉ zmฤ›ny v bฤ›hovรฉm prostล™edรญ bฤ›hem incidentลฏ nebo nรกkladovรฝch udรกlostรญ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Pล™epnฤ›te aktivaci komba pล™รญmo z ล™รญdicรญho panelu MCP\n- Pouลพรญvejte profily odolnosti z pล™eddefinovanรฝch balรญฤkลฏ zรกsad\n- Resetujte stav jistiฤe ze stejnรฉho ovlรกdacรญho panelu\n\n
\n๐Ÿ”„ 23. โ€žPotล™ebuji ลพivรฝ pล™ehled o ลพivotnรญm cyklu รบkolลฏ A2A a jejich zruลกenรญ.โ€œ\n
\n\nBez pล™ehledu o ลพivotnรญm cyklu je obtรญลพnรฉ tล™รญdit incidenty รบkolลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Vรฝpis/filtrovรกnรญ รบkolลฏ podle stรกtu/dovednosti s strรกnkovรกnรญm\n- Podrobnรฝ pล™ehled metadat รบloh, udรกlostรญ a artefaktลฏ\n- Koncovรฝ bod zruลกenรญ รบlohy a akce uลพivatelskรฉho rozhranรญ s potvrzenรญm\n\n
\n๐ŸŒŠ 24. โ€žPotล™ebuji metriky aktivnรญho streamu pro A2A zรกtฤ›ลพโ€œ\n
\n\nStreamovacรญ pracovnรญ postupy vyลพadujรญ provoznรญ pล™ehled o soubฤ›ลพnosti a ลพivรฝch pล™ipojenรญch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- ฤŒรญtaฤe aktivnรญch streamลฏ integrovanรฉ do stavu A2A\n- ฤŒasovรฉ razรญtko poslednรญho รบkolu a poฤty pro jednotlivรฉ stavy\n- Karty A2A dashboardu pro monitorovรกnรญ provozu v reรกlnรฉm ฤase\n\n
\n๐Ÿชช 25. โ€žPotล™ebuji standardnรญ vyhledรกvรกnรญ agentลฏ pro klientyโ€œ\n
\n\nExternรญ klienti a orchestratoล™i potล™ebujรญ pro onboarding strojovฤ› ฤitelnรก metadata.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Karta agenta je k dispozici v souboru `/.well-known/agent.json`\n- Schopnosti a dovednosti zobrazenรฉ v uลพivatelskรฉm rozhranรญ pro sprรกvu\n- API pro stav A2A zahrnuje metadata pro zjiลกลฅovรกnรญ pro automatizaci\n\n
\n๐Ÿงญ 26. โ€žPotล™ebuji v uลพivatelskรฉm rozhranรญ produktu zjistitelnost protokolu.โ€œ\n
\n\nPokud uลพivatelรฉ nemohou objevit protokolovรฉ povrchy, kvalita pล™ijetรญ a podpory klesรก.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Strรกnka Konsolidovanรฉ **koncovรฉ body** s kartami pro koncovรฉ body Proxy, MCP, A2A a API\n- Pล™epรญnรกnรญ stavu inline sluลพby (Online/Offline) pro MCP a A2A\n- Odkazy z pล™ehledu na vyhrazenรฉ karty pro sprรกvu\n\n
\n๐Ÿงช 27. โ€žPotล™ebuji komplexnรญ ovฤ›ล™enรญ protokolu se skuteฤnรฝmi klienty.โ€œ\n
\n\nSimulovanรฉ testy nestaฤรญ k ovฤ›ล™enรญ kompatibility protokolu pล™ed vydรกnรญm.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sada E2E, kterรก spouลกtรญ aplikaci a pouลพรญvรก skuteฤnรฝ transport klienta MCP SDK.\n- Klientskรฉ testy A2A pro toky zjiลกลฅovรกnรญ, odesรญlรกnรญ, streamovรกnรญ, naฤรญtรกnรญ a zruลกenรญ\n- Kล™รญลพovรก kontrola tvrzenรญ oproti API pro audit MCP a รบkoly A2A\n\n
\n๐Ÿ“ก 28. โ€žPotล™ebuji jednotnou pozorovatelnost napล™รญฤ vลกemi rozhranรญmiโ€œ\n
\n\nRozdฤ›lenรญ pozorovatelnosti podle protokolu vytvรกล™รญ slepรก mรญsta a delลกรญ MTTR.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรฉ dashboardy/logy/analytiky v jednom produktu\n- Stav + audit + telemetrie poลพadavkลฏ napล™รญฤ vrstvami OpenAI, MCP a A2A\n- Provoznรญ API pro stav a automatizaci\n\n
\n๐Ÿ’ผ 29. โ€žPotล™ebuji jeden runtime pro proxy + nรกstroje + orchestraci agentลฏโ€œ\n
\n\nSpouลกtฤ›nรญ mnoha samostatnรฝch sluลพeb zvyลกuje provoznรญ nรกklady a poฤet poruch.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Proxy, MCP server a A2A server kompatibilnรญ s OpenAI v jednom balรญฤku\n- Sdรญlenรฉ ovฤ›ล™ovรกnรญ, odolnost, รบloลพiลกtฤ› dat a pozorovatelnost\n- Konzistentnรญ model politik napล™รญฤ vลกemi interakฤnรญmi plochami\n\n
\n๐Ÿš€ 30. โ€žPotล™ebuji agentskรฉ pracovnรญ postupy bez slepenรญ kรณdu.โ€œ\n
\n\nTรฝmy ztrรกcejรญ rychlost pล™i spojovรกnรญ vรญce ad-hoc sluลพeb a skriptลฏ.\n\n**Jak to OmniRoute ล™eลกรญ:**\n\n- Sjednocenรก strategie koncovรฝch bodลฏ pro klienty a agenty\n- Vestavฤ›nรก uลพivatelskรก rozhranรญ pro sprรกvu protokolลฏ a cesty pro ovฤ›ล™ovรกnรญ kouล™e\n- Zรกklady pล™ipravenรฉ pro produkฤnรญ prostล™edรญ (zabezpeฤenรญ, protokolovรกnรญ, odolnost, zรกlohovรกnรญ)\n\n### Pล™รญklady hernรญch plรกnลฏ (integrovanรฉ pล™รญpady uลพitรญ)\n\n**Pล™รญruฤka A: Maximalizace placenรฉho pล™edplatnรฉho + levnรฉ zรกlohovรกnรญ**\n\n```txt\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-6\n 2. glm/glm-4.7\n 3. if/kimi-k2-thinking\n\nMonthly cost: $20 + small backup spend\nOutcome: higher quality, near-zero interruption\n```\n\n**Pล™รญruฤka B: Kรณdovacรญ stack s nulovรฝmi nรกklady**\n\n```txt\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash\n 2. if/kimi-k2-thinking\n 3. qw/qwen3-coder-plus\n\nMonthly cost: $0\nOutcome: stable free coding workflow\n```\n\n**Pล™รญruฤka C: Nonstop zรกloลพnรญ ล™etฤ›zec**\n\n```txt\nCombo: \"always-on\"\n 1. cc/claude-opus-4-6\n 2. cx/gpt-5.2-codex\n 3. glm/glm-4.7\n 4. minimax/MiniMax-M2.1\n 5. if/kimi-k2-thinking\n\nOutcome: deep fallback depth for deadline-critical workloads\n```\n\n**Pล™รญruฤka D: Operace agentลฏ s MCP + A2A**\n\n```txt\n1) Start MCP transport (`omniroute --mcp`) for tool-driven operations\n2) Run A2A tasks via `message/send` and `message/stream`\n3) Observe via /dashboard/endpoint (MCP and A2A tabs)\n4) Toggle services via inline status controls\n```\n\n---\n\n## ๐Ÿ†“ Zaฤnฤ›te zdarma โ€” Nulovรฉ nรกklady na konfiguraci\n\n> Nastavte si kรณdovรกnรญ s umฤ›lou inteligencรญ bฤ›hem nฤ›kolika minut za **0 $/mฤ›sรญc** . Propojte tyto bezplatnรฉ รบฤty a vyuลพijte vestavฤ›nou kombinaci **Free Stack** .\n\n| Krok | Akce | Poskytovatelรฉ odemฤeni |\n| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- |\n| 1 | Pล™ipojenรญ **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€“ **neomezenฤ›** |\n| 2 | Pล™ipojenรญ k **iFlow** (Google OAuth) | kimi-k2-myลกlenรญ, qwen3-coder-plus, deepseek-r1... โ€” **neomezenฤ›** |\n| 3 | Pล™ipojenรญ **Qwen** (kรณd zaล™รญzenรญ) | qwen3-coder-plus, qwen3-coder-flash... โ€” **neomezenฤ›** |\n| 4 | Pล™ipojenรญ **rozhranรญ pล™รญkazovรฉho ล™รกdku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180 000 GBP/mฤ›sรญc zdarma** |\n| 5 | `/dashboard/combos` โ†’ ล ablona **Free Stack (0 $)** | Automatickรฉ zaล™azenรญ vลกech bezplatnรฝch poskytovatelลฏ do routingu |\n\n**V libovolnรฉm IDE/CLI naveฤte:** `http://localhost:20128/v1` ยท Klรญฤ API: `any-string` ยท Hotovo.\n\n> **Volitelnรฉ doplลˆkovรฉ krytรญ (takรฉ zdarma):** Groq API klรญฤ (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelลฏ), Cerebras (1 milion tok/den).\n\n## โšก Rychlรฝ start\n\n### 1) Nainstalujte a spusลฅte\n\n```bash\nnpm install -g omniroute\nomniroute\n```\n\n> **Uลพivatelรฉ pnpm:** Po instalaci spusลฅte `pnpm approve-builds -g` , abyste povolili nativnรญ skripty pro sestavenรญ vyลพadovanรฉ programy `better-sqlite3` a `@swc/core` :\n>\n> ```bash\n> pnpm install -g omniroute\n> pnpm approve-builds -g # Select all packages โ†’ approve\n> omniroute\n> ```\n\nDashboard se otevรญrรก na `http://localhost:20128` a zรกkladnรญ URL API je `http://localhost:20128/v1` .\n\n| Pล™รญkaz | Popis |\n| ----------------------- | ------------------------------------------------------------------- |\n| `omniroute` | Spuลกtฤ›nรญ serveru ( `PORT=20128` , API a dashboard na stejnรฉm portu) |\n| `omniroute --port 3000` | Nastavte kanonickรฝ/API port na 3000 |\n| `omniroute --mcp` | Spuลกtฤ›nรญ MCP serveru (transport stdio) |\n| `omniroute --no-open` | Neotevรญrat prohlรญลพeฤ automaticky |\n| `omniroute --help` | Zobrazit nรกpovฤ›du |\n\nVolitelnรฝ reลพim s rozdฤ›lenรฝm portem:\n\n```bash\nPORT=20128 DASHBOARD_PORT=20129 omniroute\n# API: http://localhost:20128/v1\n# Dashboard: http://localhost:20129\n```\n\n### 2) Pล™ipojte poskytovatele a vytvoล™te si klรญฤ API\n\n1. Otevล™ete Dashboard โ†’ `Providers` a pล™ipojte alespoลˆ jednoho poskytovatele (klรญฤ OAuth nebo API).\n2. Otevล™ete Dashboard โ†’ `Endpoints` a vytvoล™te API klรญฤ.\n3. (Volitelnรฉ) Otevล™ete Dashboard โ†’ `Combos` a nastavte zรกloลพnรญ ล™etฤ›zec.\n\n### 3) Nasmฤ›rujte svลฏj kรณdovacรญ nรกstroj na OmniRoute\n\n```txt\nBase URL: http://localhost:20128/v1\nAPI Key: [copy from Endpoint page]\nModel: if/kimi-k2-thinking (or any provider/model prefix)\n```\n\nFunguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilnรญmi s OpenAI.\n\n### 4) Povolenรญ a ovฤ›ล™enรญ protokolลฏ (v2.0)\n\n**MCP (pro operace ล™รญzenรฉ nรกstroji):**\n\n```bash\nomniroute --mcp\n```\n\nPak pล™ipojte svรฉho MCP klienta pล™es `stdio` a otestujte nรกstroje jako:\n\n- `omniroute_get_health`\n- `omniroute_list_combos`\n\n**A2A (pro pracovnรญ postupy mezi agenty):**\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"quickstart\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Give me a short quota summary.\"}]}}'\n```\n\n### 5) Ovฤ›ล™te vลกe od zaฤรกtku do konce (doporuฤeno)\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTato sada ovฤ›ล™uje skuteฤnรฉ toky klientลฏ MCP a A2A v porovnรกnรญ se spuลกtฤ›nou aplikacรญ.\n\n### Alternativa: spustit ze zdroje\n\n```bash\ncp .env.example .env\nnpm install\nPORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev\n```\n\n---\n\n## ๐Ÿณ Docker\n\nOmniRoute je k dispozici jako veล™ejnรฝ obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) .\n\n**Rychlรฝ bฤ›h:**\n\n```bash\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Se souborem prostล™edรญ:**\n\n```bash\n# Copy and edit .env first\ncp .env.example .env\n\ndocker run -d \\\n --name omniroute \\\n --restart unless-stopped \\\n --env-file .env \\\n -p 20128:20128 \\\n -v omniroute-data:/app/data \\\n diegosouzapw/omniroute:latest\n```\n\n**Pouลพรญvรกnรญ Docker Compose:**\n\n```bash\n# Base profile (no CLI tools)\ndocker compose --profile base up -d\n\n# CLI profile (Claude Code, Codex, OpenClaw built-in)\ndocker compose --profile cli up -d\n```\n\n| Obraz | ล tรญtek | Velikost | Popis |\n| ------------------------ | -------- | -------- | ------------------------- |\n| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovฤ›jลกรญ stabilnรญ verze |\n| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuรกlnรญ verze |\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktopovรก aplikace โ€“ offline a vลพdy zapnutรก\n\n> ๐Ÿ†• **NOVINKA!** OmniRoute je nynรญ k dispozici jako **nativnรญ desktopovรก aplikace** pro Windows, macOS a Linux.\n\nSpusลฅte OmniRoute jako samostatnou desktopovou aplikaci โ€“ pro lokรกlnรญ modely nenรญ potล™eba ลพรกdnรฝ terminรกl, prohlรญลพeฤ ani internet. Aplikace zaloลพenรก na platformฤ› Electron obsahuje:\n\n- ๐Ÿ–ฅ๏ธ **Nativnรญ okno** โ€” Vyhrazenรฉ okno aplikace s integracรญ do systรฉmovรฉ liลกty\n- ๐Ÿ”„ **Automatickรฉ spuลกtฤ›nรญ** โ€” Spuลกtฤ›nรญ OmniRoute po pล™ihlรกลกenรญ do systรฉmu\n- ๐Ÿ”” **Nativnรญ oznรกmenรญ** โ€“ Zรญskejte upozornฤ›nรญ na vyฤerpรกnรญ kvรณty nebo problรฉmy s poskytovateli\n- โšก **Instalace jednรญm kliknutรญm** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux)\n- ๐ŸŒ **Offline reลพim** โ€” Funguje plnฤ› offline s pล™iloลพenรฝm serverem\n\n### Rychlรฝ start\n\n```bash\n# Development mode\nnpm run electron:dev\n\n# Build for your platform\nnpm run electron:build # Current platform\nnpm run electron:build:win # Windows (.exe)\nnpm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64\nnpm run electron:build:linux # Linux (.AppImage)\n```\n\n### Systรฉmovรฝ zรกsobnรญk\n\nPo minimalizaci se OmniRoute nachรกzรญ v systรฉmovรฉ liลกtฤ› a nabรญzรญ rychlรฉ akce:\n\n- Otevล™รญt ล™รญdicรญ panel\n- Zmฤ›nit port serveru\n- Ukonฤit aplikaci\n\n๐Ÿ“– รšplnรก dokumentace: [`electron/README.md`](electron/README.md)\n\n---\n\n## ๐Ÿ’ฐ Pล™ehled cen\n\n| รšroveลˆ | Poskytovatel | Nรกklady | Obnovenรญ kvรณty | Nejlepลกรญ pro |\n| --------------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- |\n| **๐Ÿ’ณ Pล˜EDPLATNร‰** | Claude Code (profesionรกl) | 20 dolarลฏ mฤ›sรญฤnฤ› | 5 hodin + tรฝdnฤ› | Jiลพ pล™ihlรกลกen/a k odbฤ›ru |\n| Kodex (Plus/Pro) | 20โ€“200 USD/mฤ›sรญc | 5 hodin + tรฝdnฤ› | Uลพivatelรฉ OpenAI |\n| Gemini CLI | **UVOLNIT** | 180 tisรญc mฤ›sรญฤnฤ› + 1 tisรญc dennฤ› | Kaลพdรฝ! |\n| GitHub Copilot | 10โ€“19 USD/mฤ›sรญc | Mฤ›sรญฤnรญ | Uลพivatelรฉ GitHubu |\n| **๐Ÿ”‘ KLรฤŒ API** | NVIDIA NIM | **ZDARMA** (vรฝvoj navลพdy) | ~40 ot./min | 70+ otevล™enรฝch modelลฏ |\n| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ na svฤ›tฤ› |\n| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisรญc otรกฤek za minutu | Ultrarychlรก lama/gema |\n| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | ลฝรกdnรฝ | Nejlepลกรญ zdลฏvodnฤ›nรญ ceny a kvality |\n| xAI Grok-4 Rychlรฝ | **0,20/0,50 USD za 1 milion** ๐Ÿ†• | ลฝรกdnรฝ | Nejrychlejลกรญ + volรกnรญ nรกstroje, ultranรญzkรฉ |\n| xAI Grok-4 (standardnรญ) | 0,20/1,50 USD za 1 milion ๐Ÿ†• | ลฝรกdnรฝ | Vlajkovรก loฤ Reasoning od xAI |\n| Mistral | Zkuลกebnรญ verze zdarma + placenรฉ | Omezenรก sazba | Evropskรก umฤ›lรก inteligence |\n| OpenRouter | Platba za pouลพitรญ | ลฝรกdnรฝ | Vรญce neลพ 100 modelลฏ agregovรกno. |\n| **๐Ÿ’ฐ LEVNร‰** | GLM-5 (pล™es Z.AI) ๐Ÿ†• | 0,5 USD/1 milion | Dennฤ› v 10:00 | Vรฝstup 128 tisรญc obrazovรฝch bodลฏ, nejnovฤ›jลกรญ vlajkovรก loฤ |\n| GLM-4.7 | 0,6 USD/1 milion | Dennฤ› v 10:00 | Zรกloha rozpoฤtu |\n| MiniMax M2.5 ๐Ÿ†• | Vstup 0,3 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | รšvaha + agentnรญ รบkoly |\n| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | Nejlevnฤ›jลกรญ varianta |\n| Kimi K2.5 (Moonshot API) ๐Ÿ†• | Platba za pouลพitรญ | ลฝรกdnรฝ | Pล™รญmรฝ pล™รญstup k Moonshot API |\n| Kimi K2 | 9 dolarลฏ mฤ›sรญฤnฤ› bez zรกvazkลฏ | 10 milionลฏ tokenลฏ/mฤ›sรญc | Pล™edvรญdatelnรฉ nรกklady |\n| **๐Ÿ†“ ZDARMA** | iFlow | **0 dolarลฏ** | Neomezenรฝ | 5 modelลฏ neomezenฤ› |\n| Qwen | **0 dolarลฏ** | Neomezenรฝ | 4 modely neomezenฤ› |\n| Kiro | **0 dolarลฏ** | Neomezenรฝ | Claude Sonnet/Haiku (tvorce AWS) |\n\n> ๐Ÿ†• **Pล™idรกny novรฉ modely (bล™ezen 2026):** ล™ada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkovรกno na 1143 ms โ€“ o 30 % rychlejลกรญ neลพ Gemini 2.5 Flash), GLM-5 pล™es Z.AI s vรฝstupem 128K, uvaลพovรกnรญ MiniMax M2.5, aktualizovanรฉ ceny DeepSeek V3.2, Kimi K2.5 pล™es Moonshot Direct API.\n\n**๐Ÿ’ก Kombinovanรฝ balรญk za 0 $ โ€” Kompletnรญ bezplatnรก instalace:**\n\n```\n# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever\nKiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED\niFlow (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED\nLongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ\nPollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed\nQwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED\nGemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key\nCloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day\nScaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU)\nGroq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day\nNVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever\nCerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day\n```\n\n**Nulovรฉ nรกklady. Nikdy nepล™estรกvejte s kรณdovรกnรญm.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a vลกechny zรกloลพnรญ reลพimy se provede automaticky โ€“ ลพรกdnรฉ ruฤnรญ pล™epรญnรกnรญ.\n\n---\n\n---\n\n## ๐Ÿ†“ Bezplatnรฉ modely โ€“ Co skuteฤnฤ› zรญskรกte\n\n> Vลกechny nรญลพe uvedenรฉ modely jsou **100% zdarma a nevyลพadujรญ ลพรกdnou kreditnรญ kartu** . OmniRoute mezi nimi automaticky propojรญ trasy, kdyลพ dojde jedna kvรณta โ€“ zkombinujte je vลกechny a zรญskejte tak nerozluฤnou kombinaci za 0 dolarลฏ.\n\n### ๐Ÿ”ต CLAUDE MODELS (pล™es Kiro โ€” AWS Builder ID)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ------------------------- |\n| `claude-sonnet-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-haiku-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit |\n| `claude-opus-4.6` | `kr/` | **Neomezenรฝ** | Nejnovฤ›jลกรญ opus od Kira |\n\n### ๐ŸŸข MODELY IFLOW (Bezplatnรฉ OAuth โ€” bez nutnosti platit kreditnรญ kartou)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------ | -------- | ------------- | ------------------- |\n| `kimi-k2-thinking` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-plus` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `deepseek-r1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `minimax-m2.1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `kimi-k2` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n\n### ๐ŸŸก MODELY QWEN (Ovฤ›ล™enรญ kรณdu zaล™รญzenรญ)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------- | -------- | ------------- | ---------------------- |\n| `qwen3-coder-plus` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-flash` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `qwen3-coder-next` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop |\n| `vision-model` | `qw/` | **Neomezenรฝ** | Multimodรกlnรญ (obrรกzky) |\n\n### ๐ŸŸฃ Rozhranรญ GEMINI CLI (Google OAuth)\n\n| Model | Pล™edpona | Omezit | Limit rychlosti |\n| ------------------------ | -------- | ------------------------------------- | --------------- |\n| `gemini-3-flash-preview` | `gc/` | **180 tisรญc tok/mฤ›sรญc** + 1 tisรญc/den | Mฤ›sรญฤnรญ reset |\n| `gemini-2.5-pro` | `gc/` | 180 tisรญc mฤ›sรญฤnฤ› (sdรญlenรฝ bazรฉn) | Vysokรก kvalita |\n\n### โšซ NVIDIA NIM (Bezplatnรฝ klรญฤ API โ€” build.nvidia.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |\n| Zdarma (vรฝvojรกล™) | ลฝรกdnรฝ limit tokenลฏ | **~40 ot./min** | Vรญce neลพ 70 modelลฏ; pล™echod na ฤistรฉ limity sazeb v polovinฤ› roku 2025 |\n\nOblรญbenรฉ bezplatnรฉ modely: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct` , `deepseek/deepseek-r1`\n\n### โšช CEREBRAS (Bezplatnรฝ klรญฤ API โ€” inference.cerebras.ai)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ |\n| Uvolnit | **1 milion tokenลฏ/den** | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ inference LLM na svฤ›tฤ›; dennฤ› se resetuje |\n\nDostupnรฉ zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b`\n\n### ๐Ÿ”ด GROQ (Bezplatnรฝ API klรญฤ โ€” console.groq.com)\n\n| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky |\n| ------- | ------------------------------- | ------------------- | ------------------------------------------- |\n| Uvolnit | **14,4 tisรญc otรกฤek za minutu** | 30 ot./min na model | ลฝรกdnรก kreditnรญ karta; limit 429, neรบฤtovรกno |\n\nK dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3`\n\n> **๐Ÿ’ก Ultimรกtnรญ bezplatnรฝ zรกsobnรญk:**\n>\n> ```\n> Kiro (Claude, unlimited)\n> โ†’ iFlow (5 models, unlimited)\n> โ†’ Qwen (4 models, unlimited)\n> โ†’ Gemini CLI (180K/mo)\n> โ†’ Cerebras (1M tok/day)\n> โ†’ Groq (14.4K req/day)\n> โ†’ NVIDIA NIM (40 RPM, 70+ models)\n> ```\n>\n> Nakonfigurujte si to jako kombinaci OmniRoute a uลพ nikdy nebudete platit za umฤ›lou inteligenci.\n\n## ๐ŸŽ™๏ธ Kombinovanรก transkripce zdarma\n\n> Pล™episujte libovolnรฉ audio/video za **0 $** โ€“ Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako zรกloลพnรญ nรกstroj, Groq Whisper jako neomezenรก nouzovรก zรกloha.\n\n| Poskytovatel | Bezplatnรฉ kredity | Nejlepลกรญ model | Limit rychlosti |\n| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- |\n| ๐ŸŸข **Deepgram** | **200 dolarลฏ zdarma** (registrace) | `nova-3` โ€” nejvyลกลกรญ pล™esnost, vรญce neลพ 30 jazykลฏ | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ต **AssemblyAI** | **50 dolarลฏ zdarma** (registrace) | `universal-3-pro` โ€” kapitoly, sentiment, osobnรญ รบdaje | ลฝรกdnรฝ limit RPM pro kredity zdarma |\n| ๐Ÿ”ด **Groq** | **Navลพdy zdarma** | `whisper-large-v3` โ€” OpenAI ล epot | 30 ot./min (omezenรก rychlost) |\n\n**Navrhovanรก kombinace v `/dashboard/combos` :**\n\n```\nName: free-transcription\nStrategy: Priority\nNodes:\n [1] deepgram/nova-3 โ†’ uses $200 free first\n [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out\n [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback\n```\n\nPak v `/dashboard/media` โ†’ zรกloลพka **Pล™epis** : nahrajte libovolnรฝ zvukovรฝ nebo video soubor โ†’ vyberte kombinovanรฝ koncovรฝ bod โ†’ zรญskejte pล™epis v podporovanรฝch formรกtech.\n\n## ๐Ÿ’ก Klรญฤovรฉ vlastnosti\n\nOmniRoute v2.0 je navrลพen jako operaฤnรญ platforma, nikoli pouze jako proxy pro relรฉ.\n\n### ๐Ÿ†• Novรฉ โ€” Vylepลกenรญ inspirovanรก ClawRouterem (bล™ezen 2026)\n\n| Funkce | Co to dฤ›lรก |\n| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |\n| โšก **Grok-4 Rychlรก rodina** | Modely xAI za 0,20 USD/0,50 USD/M โ€“ v benchmarku 1143 ms (o 30 % rychlejลกรญ neลพ Gemini 2.5 Flash) |\n| ๐Ÿง  **GLM-5 pล™es Z.AI** | 128 tisรญc vรฝstupnรญch dat, 0,5 USD/1 milion USD โ€“ nejnovฤ›jลกรญ vlajkovรก loฤ rodiny GLM |\n| ๐Ÿ”ฎ **MiniMax M2.5** | รšvaha + agentnรญ รบkoly za 0,30 USD/1 milion โ€“ vรฝznamnรฝ upgrade oproti M2.1 |\n| ๐ŸŽฏ **Pล™รญznak volรกnรญ nรกstroje pro kaลพdรฝ model** | `toolCalling: true/false` v registru โ€” AutoCombo pล™eskakuje modely, kterรฉ nepodporujรญ nรกstroje. |\n| ๐ŸŒ **Detekce vรญcejazyฤnรฉho zรกmฤ›ru** | Klรญฤovรก slova PT/ZH/ES/AR v bodovรกnรญ AutoCombo โ€“ lepลกรญ vรฝbฤ›r modelu pro neanglickรฝ obsah |\n| ๐Ÿ“Š **Zรกloลพnรญ metody ล™รญzenรฉ benchmarkem** | Skuteฤnรก latence p95 z ลพivรฝch poลพadavkลฏ poskytuje kombinovanรฉ skรณre โ€“ AutoCombo se uฤรญ ze skuteฤnรฝch dat |\n| ๐Ÿ” **Poลพรกdat o deduplikaci** | Okno pro deduplikaci na zรกkladฤ› hashovรกnรญ obsahu โ€“ bezpeฤnรฉ pro vรญce agentลฏ, zabraลˆuje duplicitnรญm platbรกm |\n| ๐Ÿ”Œ **Strategie pro zรกsuvnรฉ routery** | Rozลกiล™itelnรฉ rozhranรญ `RouterStrategy` โ€“ pล™idejte si vlastnรญ logiku smฤ›rovรกnรญ jako pluginy |\n\n### ๐Ÿš€ Pล™edchozรญ verze v2.0.9+ โ€” Hล™iลกtฤ›, otisky prstลฏ v CLI a ACP\n\n| Funkce | Co to dฤ›lรก |\n| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐ŸŽฎ **Modelovรฉ hล™iลกtฤ›** | Strรกnka ล™รญdicรญho panelu pro pล™รญmรฉ testovรกnรญ libovolnรฉho modelu โ€“ selektory poskytovatele/modelu/koncovรฉho bodu, editor Monaco, streamovรกnรญ, pล™eruลกenรญ, naฤasovรกnรญ |\n| ๐Ÿ” **Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** | ล˜azenรญ hlaviฤek/tฤ›l serveru podle poskytovatele tak, aby odpovรญdalo nativnรญm podpisลฏm CLI โ€“ pล™epรญnรกnรญ pro jednotlivรฉ poskytovatele v Nastavenรญ > Zabezpeฤenรญ. **Vaลกe IP adresa proxy serveru je zachovรกna.** |\n| ๐Ÿค **Podpora ACP (Agent Client Protocol)** | Vyhledรกvรกnรญ agentลฏ CLI (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 dalลกรญch), generรกtor procesลฏ, koncovรฝ bod `/api/acp/agents` |\n| ๐Ÿค– **ล˜รญdicรญ panel agentลฏ ACP** | Ladฤ›nรญ โ€บ Strรกnka Agenti โ€” mล™รญลพka 14 agentลฏ se stavem instalace, verzรญ a formulรกล™em pro vlastnรญ agenta pro libovolnรฝ nรกstroj CLI. Uลพivatelรฉ **OpenCode** zรญskajรญ tlaฤรญtko โ€žStรกhnout opencode.jsonโ€œ, kterรฉ automaticky vygeneruje konfiguraci pล™ipravenou k pouลพitรญ se vลกemi dostupnรฝmi modely. |\n| ๐Ÿ”ง **Smฤ›rovรกnรญ `apiFormat` pro vlastnรญ model** | Vlastnรญ modely s `apiFormat: \"responses\"` nynรญ sprรกvnฤ› smฤ›rujรญ do pล™ekladaฤe Responses API. |\n| ๐Ÿข **Izolace pracovnรญho prostoru Codexu** | Vรญce pracovnรญch prostorลฏ Codexu na jeden e-mail โ€“ OAuth sprรกvnฤ› oddฤ›luje pล™ipojenรญ podle ID pracovnรญho prostoru |\n| ๐Ÿ”„ **Automatickรก aktualizace elektronลฏ** | Desktopovรก aplikace kontroluje aktualizace + automaticky se instaluje po restartu |\n\n### ๐Ÿค– Operace s agenty a protokoly (v2.0)\n\n| Funkce | Co to dฤ›lรก |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”ง **MCP Server (16 nรกstrojลฏ)** | Nรกstroje IDE/agent prostล™ednictvรญm 3 transportลฏ: stdio, SSE ( `/api/mcp/sse` ), Streamovatelnรฝ HTTP ( `/api/mcp/stream` ) |\n| ๐Ÿค **A2A server (JSON-RPC + SSE)** | Spouลกtฤ›nรญ รบloh mezi agenty se synchronizacรญ a streamovรกnรญm |\n| ๐Ÿงญ **Konsolidovanรก strรกnka koncovรฝch bodลฏ** | Strรกnka pro sprรกvu s kartami Endpoint Proxy, MCP, A2A a API Endpoints |\n| ๐ŸŽš๏ธ **Pล™epรญnaฤe pro povolenรญ/zakรกzรกnรญ sluลพby** | Pล™epรญnaฤe ZAP/VYP pro MCP a A2A s trvalรฝm nastavenรญm (vรฝchozรญ: VYP) |\n| ๐Ÿ›ฐ๏ธ **Srdeฤnรญ tep za bฤ›hu MCP** | Skuteฤnรฝ stav procesu (pid, doba provozuschopnosti, stรกล™รญ heartbeatu, transport, reลพim rozsahu) |\n| ๐Ÿ“‹ **Auditnรญ zรกznam MCP** | Filtrovatelnรฉ protokoly auditu s hodnocenรญm รบspฤ›chu/neรบspฤ›chu a klรญฤovรฝm pล™iล™azenรญm |\n| ๐Ÿ” **Vynucovรกnรญ rozsahu MCP** | 9 podrobnรฝch oprรกvnฤ›nรญ pro ล™รญzenรฝ pล™รญstup k nรกstrojลฏm |\n| ๐Ÿ“ก **Sprรกva ลพivotnรญho cyklu รบkolลฏ A2A** | Seznam/filtrovรกnรญ รบloh, kontrola udรกlostรญ/artefaktลฏ, zruลกenรญ spuลกtฤ›nรฝch รบloh |\n| ๐Ÿ“‹ **Objevenรญ karty agenta** | `/.well-known/agent.json` pro automatickรฉ vyhledรกvรกnรญ klientลฏ |\n| ๐Ÿงช **Testovacรญ postroj Protocol E2E** | Skuteฤnรฉ MCP SDK + toky klientลฏ A2A v `test:protocols:e2e` |\n| โš™๏ธ **Provoznรญ kontroly** | Kombinace pล™epรญnaฤลฏ, pouลพitรญ profilลฏ odolnosti, resetovรกnรญ jistiฤลฏ z jednoho ovlรกdacรญho panelu |\n\n### ๐Ÿง  Smฤ›rovรกnรญ a inteligence\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ----------------------------------------------------------------------------- |\n| ๐ŸŽฏ **Inteligentnรญ ฤtyล™รบrovลˆovรฝ zรกloลพnรญ systรฉm** | Automatickรก trasa: Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma |\n| ๐Ÿ“Š **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** | Poฤet tokenลฏ v reรกlnรฉm ฤase + odpoฤet resetovรกnรญ pro kaลพdรฉho poskytovatele |\n| ๐Ÿ”„ **Pล™eklad formรกtu** | OpenAI โ†” Claude โ†” Gemini โ†” Odpovฤ›di s konverzemi bezpeฤnรฝmi pro schรฉma |\n| ๐Ÿ‘ฅ **Podpora vรญce รบฤtลฏ** | Vรญce รบฤtลฏ na poskytovatele s inteligentnรญm vรฝbฤ›rem |\n| ๐Ÿ”„ **Automatickรก aktualizace tokenลฏ** | Tokeny OAuth se automaticky obnovujรญ pล™i opakovanรฉm pokusu. |\n| ๐ŸŽจ **Vlastnรญ kombinace** | 6 vyvaลพovacรญch strategiรญ + ล™รญzenรญ zรกloลพnรญho ล™etฤ›zce |\n| ๐ŸŒ **Smฤ›rovaฤ se zรกstupnรฝmi znaky** | dynamickรฉ smฤ›rovรกnรญ `provider/*` |\n| ๐Ÿง  **Pล™emรฝลกlenรญ o rozpoฤtovรฝch kontrolรกch** | Limity pro prลฏchozรญ, automatickรฉ, vlastnรญ a adaptivnรญ uvaลพovรกnรญ |\n| ๐Ÿ”€ **Aliasy modelลฏ** | Vestavฤ›nรฉ + vlastnรญ aliasovรกnรญ modelลฏ a bezpeฤnost migrace |\n| โšก **Degradace pozadรญ** | Smฤ›rujte รบlohy na pozadรญ s nรญzkou prioritou na levnฤ›jลกรญ modely |\n| ๐Ÿงช **Chytrรฉ smฤ›rovรกnรญ s ohledem na รบkoly** | Automatickรฝ vรฝbฤ›r modelu podle typu obsahu (kรณdovรกnรญ/vize/analรฝza/sumarizace) |\n| ๐Ÿ’ฌ **Vstล™ikovรกnรญ do systรฉmu** | Globรกlnรญ kontroly chovรกnรญ uplatลˆovanรฉ konzistentnฤ› |\n| ๐Ÿ“„ **Kompatibilita API pro odpovฤ›di** | Plnรก podpora `/v1/responses` pro Codex a pokroฤilรฉ agentickรฉ pracovnรญ postupy |\n\n### ๐ŸŽต Multimodรกlnรญ API\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ–ผ๏ธ **Generovรกnรญ obrรกzkลฏ** | `/v1/images/generations` s cloudovรฝm a lokรกlnรญm backendem |\n| ๐Ÿ“ **Vloลพenรญ** | `/v1/embeddings` pro vyhledรกvรกnรญ a RAG pipelines |\n| ๐ŸŽค **Pล™epis zvuku** | `/v1/audio/transcriptions` (Whisper a dalลกรญ poskytovatelรฉ) |\n| ๐Ÿ”Š **Pล™evod textu na ล™eฤ** | `/v1/audio/speech` (vรญce enginลฏ/poskytovatelลฏ) |\n| ๐ŸŽฌ **Generovรกnรญ videa** | `/v1/videos/generations` (pracovnรญ postupy ComfyUI + SD WebUI) |\n| ๐ŸŽต **Hudebnรญ generace** | `/v1/music/generations` (pracovnรญ postupy ComfyUI) |\n| ๐Ÿ›ก๏ธ **Moderovรกnรญ** | Bezpeฤnostnรญ kontroly `/v1/moderations` |\n| ๐Ÿ”€ **Zmฤ›na poล™adรญ** | `/v1/rerank` pro hodnocenรญ relevance |\n| ๐Ÿ” **Vyhledรกvรกnรญ na webu** ๐Ÿ†• | `/v1/search` โ€” 5 poskytovatelลฏ (Serper, Brave, Perplexity, Exa, Tavily), vรญce neลพ 6 500 zdarma/mฤ›sรญc, automatickรฉ pล™epnutรญ na zรกloลพnรญ systรฉm, mezipamฤ›ลฅ |\n\n### ๐Ÿ›ก๏ธ Odolnost, bezpeฤnost a sprรกva vฤ›cรญ veล™ejnรฝch\n\n| Funkce | Co to dฤ›lรก |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| ๐Ÿ”Œ **Jistiฤe** | Vypnutรญ/obnovenรญ pro kaลพdรฝ model s ovlรกdรกnรญm prahovรฝch hodnot |\n| ๐ŸŽฏ **Modely s ohledem na koncovรฉ body** | Vlastnรญ modely deklarujรญ podporovanรฉ koncovรฉ body + formรกt API |\n| ๐Ÿ›ก๏ธ **Stรกdo proti hromลฏm** | Ochrana mutexu a semaforu pล™i udรกlostech opakovรกnรญ/rychlosti |\n| ๐Ÿง  **Sรฉmantickรก + podpisovรก mezipamฤ›ลฅ** | Snรญลพenรญ nรกkladลฏ/latence dรญky dvฤ›ma vrstvรกm mezipamฤ›ti |\n| โšก **ลฝรกdost o idempotenci** | Okno ochrany proti duplikacรญm |\n| ๐Ÿ”’ **Falลกovรกnรญ otiskลฏ prstลฏ pomocรญ TLS** | Otisk TLS podobnรฝ prohlรญลพeฤi โ€“ **sniลพuje detekci botลฏ a nahlaลกovรกnรญ รบฤtลฏ** |\n| ๐Ÿ” **Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** | Shoduje se s nativnรญmi podpisy poลพadavkลฏ CLI โ€“ **sniลพuje riziko zablokovรกnรญ a zรกroveลˆ zachovรกvรก IP adresu proxy** |\n| ๐ŸŒ **Filtrovรกnรญ IP adres** | Ovlรกdรกnรญ seznamu povolenรฝch/blokovanรฝch poloลพek pro odhalenรก nasazenรญ |\n| ๐Ÿ“Š **Upravitelnรฉ limity rychlosti** | Konfigurovatelnรฉ globรกlnรญ/na รบrovni poskytovatele limity s perzistencรญ |\n| ๐Ÿ”‘ **Sprรกva klรญฤลฏ API a stanovenรญ rozsahu** | Bezpeฤnรฉ vydรกvรกnรญ/rotace klรญฤลฏ a kontroly modelu/poskytovatele |\n| ๐Ÿ›ก๏ธ **Chrรกnฤ›nรฉ `/models`** | Volitelnรฉ ovฤ›ล™ovรกnรญ a skrytรญ poskytovatele pro katalog modelลฏ |\n\n### ๐Ÿ“Š Pozorovatelnost a analytika\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------- | ---------------------------------------------------------------------- |\n| ๐Ÿ“ **ลฝรกdost + protokolovรกnรญ proxy** | รšplnรฉ protokolovรกnรญ poลพadavkลฏ/odpovฤ›dรญ a proxy |\n| ๐Ÿ“‹ **Sjednocenรฝ panel protokolลฏ** | Zobrazenรญ poลพadavkลฏ, proxy, auditu a konzole na jednรฉ strรกnce |\n| ๐Ÿ” **Vyลพรกdat si telemetrii** | Latence p50/p95/p99 a trasovรกnรญ poลพadavkลฏ |\n| ๐Ÿฅ **Panel zdravรญ** | Doba provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti |\n| ๐Ÿ’ฐ **Sledovรกnรญ nรกkladลฏ** | Kontrola rozpoฤtu a pล™ehled o cenรกch pro jednotlivรฉ modely |\n| ๐Ÿ“ˆ **Analytickรฉ vizualizace** | Pล™ehledy vyuลพitรญ modelลฏ/poskytovatelลฏ a zobrazenรญ trendลฏ |\n| ๐Ÿงช **Rรกmec hodnocenรญ** | Testovรกnรญ zlatรฉ sady s konfigurovatelnรฝmi strategiemi shody |\n\n### โ˜๏ธ Nasazenรญ a platforma\n\n| Funkce | Co to dฤ›lรก |\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\n| ๐ŸŒ **Nasazenรญ kdekoli** | Localhost, VPS, Docker, cloudovรก prostล™edรญ |\n| ๐Ÿ’พ **Synchronizace s cloudem** | Synchronizace konfigurace pล™es cloud worker |\n| ๐Ÿ”„ **Zรกlohovรกnรญ/Obnovenรญ** | Toky exportu/importu a obnovy po havรกrii |\n| ๐Ÿง™ **Prลฏvodce nรกstupem** | Prลฏvodce prvnรญm spuลกtฤ›nรญm |\n| ๐Ÿ”ง **Panel nรกstrojลฏ CLI** | Nastavenรญ oblรญbenรฝch kรณdovacรญch nรกstrojลฏ jednรญm kliknutรญm |\n| ๐ŸŽฎ **Modelovรฉ hล™iลกtฤ›** | Otestujte libovolnรฉho poskytovatele/model/koncovรฝ bod z ล™รญdicรญho panelu |\n| ๐Ÿ” **Pล™epรญnaฤ otiskลฏ prstลฏ v pล™รญkazovรฉm ล™รกdku** | Porovnรกvรกnรญ otiskลฏ prstลฏ podle poskytovatele v Nastavenรญ > Zabezpeฤenรญ |\n| ๐ŸŒ **i18n (30 jazykลฏ)** | Plnรก jazykovรก podpora dashboardu a dokumentace s psanรญm zprava doleva |\n| ๐Ÿ“‚ **Adresรกล™ vlastnรญch dat** | Pล™epsรกnรญ `DATA_DIR` pro umรญstฤ›nรญ รบloลพiลกtฤ› |\n\n### Hlubokรฝ pohled na funkce\n\n#### Chytrรก zรกloลพnรญ funkce s praktickou kontrolou nรกkladลฏ\n\n```txt\nCombo: \"my-coding-stack\"\n 1. cc/claude-opus-4-6\n 2. nvidia/llama-3.3-70b\n 3. glm/glm-4.7\n 4. if/kimi-k2-thinking\n```\n\nKdyลพ selลพe kvรณta, rychlost nebo stav, OmniRoute automaticky pล™ejde k dalลกรญmu kandidรกtovi bez nutnosti ruฤnรญho pล™epรญnรกnรญ.\n\n#### Sprรกva protokolลฏ, kterรก je viditelnรก a ovladatelnรก\n\n- MCP + A2A jsou viditelnรฉ v uลพivatelskรฉm rozhranรญ a dokumentaci (nejsou skrytรฉ)\n- API pro stav protokolu zpล™รญstupลˆujรญ ลพivรก provoznรญ data ( `/api/mcp/*` , `/api/a2a/*` )\n- Dashboardy zahrnujรญ akce pro operace 2. dne (pล™epรญnรกnรญ kombinacรญ, resetovรกnรญ jistiฤลฏ, zruลกenรญ รบkolลฏ)\n\n#### Pracovnรญ postup pล™ekladatele + validace\n\nOblast pล™ekladatele zahrnuje:\n\n- **Hล™iลกtฤ›** : kontroly transformace poลพadavkลฏ\n- **Tester chatu** : kompletnรญ okruลพnรญ cesta poลพadavku/odpovฤ›di\n- **Testovacรญ stolice** : vรญce pล™รญpadลฏ v jednom bฤ›hu\n- **ลฝivรฝ monitor** : zobrazenรญ provozu v reรกlnรฉm ฤase\n\nPlus validace protokolu se skuteฤnรฝmi klienty pomocรญ `npm run test:protocols:e2e` .\n\n> ๐Ÿ“– **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** โ€” Referenฤnรญ informace o nรกstrojรญch, konfigurace IDE a pล™รญklady klientลฏ\n>\n> ๐Ÿ“– **[Soubor README pro A2A Server](src/lib/a2a/README.md)** โ€” Dovednosti, metody JSON-RPC, streamovรกnรญ a ลพivotnรญ cyklus รบloh\n\n## ๐Ÿงช Hodnocenรญ (Evals)\n\nOmniRoute obsahuje vestavฤ›nรฝ hodnotรญcรญ rรกmec pro testovรกnรญ kvality odpovฤ›dรญ LLM v porovnรกnรญ se zlatou sadou. Pล™รญstup k nฤ›mu je moลพnรฝ pล™es **Analรฝzy โ†’ Hodnocenรญ** v dashboardu.\n\n### Vestavฤ›nรก zlatรก sada\n\nPล™edinstalovanรก sada โ€žOmniRoute Golden Setโ€œ obsahuje testovacรญ pล™รญpady pro:\n\n- Zdravรญm, matematika, zemฤ›pis, generovรกnรญ kรณdu\n- Shoda s formรกtem JSON, pล™eklad, generovรกnรญ markdownลฏ\n- Bezpeฤnostnรญ odmรญtnutรญ (ลกkodlivรฝ obsah), poฤรญtรกnรญ, booleovskรก logika\n\n### Strategie hodnocenรญ\n\n| Strategie | Popis | Pล™รญklad |\n| ---------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `exact` | Vรฝstup se musรญ pล™esnฤ› shodovat | `\"4\"` |\n| `contains` | Vรฝstup musรญ obsahovat podล™etฤ›zec (bez rozliลกenรญ velkรฝch a malรฝch pรญsmen) | `\"Paris\"` |\n| `regex` | Vรฝstup musรญ odpovรญdat vzoru regulรกrnรญch vรฝrazลฏ | `\"1.*2.*3\"` |\n| `custom` | Vlastnรญ JS funkce vracรญ true/false | `(output) => output.length > 10` |\n\n---\n\n## ๐Ÿ“– Prลฏvodce nastavenรญm\n\n### Nastavenรญ protokolu (MCP + A2A)\n\n
\n๐Ÿงฉ Nastavenรญ MCP (Model Context Protocol)\n
\n\nSpuลกtฤ›nรญ MCP transportu v reลพimu stdio:\n\n```bash\nomniroute --mcp\n```\n\nDoporuฤenรฝ postup ovฤ›ล™enรญ:\n\n1. Pล™ipojte svรฉho MCP klienta pล™es stdio.\n2. Spusลฅte `omniroute_get_health` .\n3. Spusลฅte `omniroute_list_combos` .\n4. Otevล™ete `/dashboard/mcp` pro ovฤ›ล™enรญ prezenฤnรญho signรกlu, aktivity a auditu.\n\nUลพiteฤnรก API pro automatizaci:\n\n- `GET /api/mcp/status`\n- `GET /api/mcp/tools`\n- `GET /api/mcp/audit`\n- `GET /api/mcp/audit/stats`\n\n
\n๐Ÿค Nastavenรญ A2A (Agent2Agent)\n
\n\nObjevte agenta:\n\n```bash\ncurl http://localhost:20128/.well-known/agent.json\n```\n\nOdeslat รบkol:\n\n```bash\ncurl -X POST http://localhost:20128/a2a \\\n -H 'content-type: application/json' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":\"setup-a2a\",\"method\":\"message/send\",\"params\":{\"skill\":\"quota-management\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize quota status.\"}]}}'\n```\n\nSprรกva ลพivotnรญho cyklu:\n\n- `GET /api/a2a/status`\n- `GET /api/a2a/tasks`\n- `GET /api/a2a/tasks/:id`\n- `POST /api/a2a/tasks/:id/cancel`\n\nProvoznรญ uลพivatelskรฉ rozhranรญ:\n\n- `/dashboard/a2a` pro pozorovatelnost รบloh/stavลฏ/streamลฏ a akce kouล™enรญ\n\n
\n๐Ÿงช Komplexnรญ validace protokolu\n
\n\nOvฤ›ล™te oba protokoly se skuteฤnรฝmi klienty:\n\n```bash\nnpm run test:protocols:e2e\n```\n\nTรญm se ovฤ›ล™uje:\n\n- Pล™ipojenรญ/seznam/volรกnรญ klienta MCP SDK\n- A2A objevovรกnรญ/odesรญlรกnรญ/streamovรกnรญ/zรญskรกvรกnรญ/zruลกenรญ\n- Kล™รญลพovรก kontrola dat v auditu MCP a API pro sprรกvu รบloh A2A\n\n
\n๐Ÿ’ณ Poskytovatelรฉ pล™edplatnรฉho\n
\n\n### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-6\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Tip pro profesionรกly:** Pro sloลพitรฉ รบkoly pouลพรญvejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvรณtu pro kaลพdรฝ model!\n\n### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Sprรกva limitลฏ รบฤtu Codex (5h + tรฝdnฤ›)\n\nKaลพdรฝ รบฤet Codex mรก nynรญ pล™epรญnaฤe zรกsad v `Dashboard -> Providers` :\n\n- `5h` (ZAP/VYP): vynutit politiku 5hodinovรฉho prahu okna.\n- `Weekly` (ZAP/VYP): vynutit zรกsadu tรฝdennรญho prahu okna.\n- Prahovรฉ chovรกnรญ: kdyลพ povolenรฉ okno dosรกhne vyuลพitรญ >=90 %, je danรฝ รบฤet pล™eskoฤen.\n- Chovรกnรญ rotace: OmniRoute automaticky pล™esmฤ›ruje na dalลกรญ zpลฏsobilรฝ รบฤet Codex.\n- Chovรกnรญ pล™i resetovรกnรญ: Po `resetAt` urฤitรฉ doby se รบฤet automaticky opฤ›t stane zpลฏsobilรฝm.\n\nScรฉnรกล™e:\n\n- `5h ON` + `Weekly ON` : รบฤet je pล™eskoฤen, kdyลพ kterรฉkoli z oken dosรกhne prahovรฉ hodnoty.\n- `5h OFF` + `Weekly ON` : รบฤet mลฏลพe bรฝt zablokovรกn pouze tรฝdennรญm pouลพรญvรกnรญm.\n- `5h ON` + `Weekly OFF` : รบฤet mลฏลพe bรฝt zablokovรกn pouze pล™i 5hodinovรฉm pouลพรญvรกnรญ.\n- `resetAt` passed: รบฤet se automaticky znovu zapne (bez ruฤnรญho opฤ›tovnรฉho povolenรญ).\n\n### Gemini CLI (ZDARMA 180 000/mฤ›sรญc!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Nejlepลกรญ hodnota:** Obrovskรก bezplatnรก รบroveลˆ! Pouลพijte ji pล™ed placenรฝmi รบrovnฤ›mi.\n\n### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3-pro\n```\n\n
\n๐Ÿ”‘ Poskytovatelรฉ klรญฤลฏ API\n
\n\n### NVIDIA NIM (BEZPLATNร pล™รญstup pro vรฝvojรกล™e โ€” vรญce neลพ 70 modelลฏ)\n\n1. Registrace: [build.nvidia.com](https://build.nvidia.com)\n2. Zรญskejte zdarma klรญฤ API (vฤetnฤ› 1000 inferenฤnรญch kreditลฏ)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ NVIDIA NIM:\n - Klรญฤ API: `nvapi-your-key`\n\n**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a vรญce neลพ 50 dalลกรญch\n\n**Tip pro profesionรกly:** API kompatibilnรญ s OpenAI โ€“ funguje bez problรฉmลฏ s pล™ekladem formรกtลฏ OmniRoute!\n\n### Hlubokรฉ vyhledรกvรกnรญ\n\n1. Registrace: [platform.deepseek.com](https://platform.deepseek.com)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ DeepSeek\n\n**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder`\n\n### Groq (k dispozici je bezplatnรก รบroveลˆ!)\n\n1. Registrace: [console.groq.com](https://console.groq.com)\n2. Zรญskejte klรญฤ API (vฤetnฤ› bezplatnรฉ รบrovnฤ›)\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ Groq\n\n**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b`\n\n**Tip pro profesionรกly:** Ultrarychlรก inference โ€“ nejlepลกรญ pro kรณdovรกnรญ v reรกlnรฉm ฤase!\n\n### OpenRouter (100+ modelลฏ)\n\n1. Registrace: [openrouter.ai](https://openrouter.ai)\n2. Zรญskat klรญฤ API\n3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ OpenRouter\n\n**Modely:** Zรญskejte pล™รญstup k vรญce neลพ 100 modelลฏm od vลกech hlavnรญch poskytovatelลฏ prostล™ednictvรญm jedinรฉho klรญฤe API.\n\n
\n๐Ÿ’ฐ Levnรญ poskytovatelรฉ (zรกloลพnรญ)\n
\n\n### GLM-4.7 (Dennรญ reset, 0,6 USD/1 milion)\n\n1. Registrace: [Zhipu AI](https://open.bigmodel.cn/)\n2. Zรญskejte klรญฤ API z kรณdovacรญho plรกnu\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API:\n - Poskytovatel: `glm`\n - Klรญฤ API: `your-key`\n\n**Pouลพitรญ:** `glm/glm-4.7`\n\n**Tip pro profesionรกly:** Programovacรญ plรกn nabรญzรญ 3ร— kvรณtu za cenu 1/7! Obnovuje se dennฤ› v 10:00.\n\n### MiniMax M2.1 (5h reset, 0,20 $/1 milion)\n\n1. Registrace: [MiniMax](https://www.minimax.io/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `minimax/MiniMax-M2.1`\n\n**Tip pro profesionรกly:** Nejlevnฤ›jลกรญ varianta pro dlouhรฝ kontext (1 milion tokenลฏ)!\n\n### Kimi K2 (pauลกรกlnรญ poplatek 9 dolarลฏ mฤ›sรญฤnฤ›)\n\n1. Odebรญrat: [Moonshot AI](https://platform.moonshot.ai/)\n2. Zรญskat klรญฤ API\n3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API\n\n**Pouลพitรญ:** `kimi/kimi-latest`\n\n**Tip pro profesionรกly:** Fixnรญch 9 $/mฤ›sรญc za 10 milionลฏ tokenลฏ = efektivnรญ nรกklady 0,90 $/1 milion!\n\n
\n๐Ÿ†“ BEZPLATNร poskytovatelรฉ (nouzovรฉ zรกlohovรกnรญ)\n
\n\n### iFlow (5 BEZPLATNรCH modelลฏ pล™es OAuth)\n\n```bash\nDashboard โ†’ Connect iFlow\nโ†’ iFlow OAuth login\nโ†’ Unlimited usage\n\nModels:\n if/kimi-k2-thinking\n if/qwen3-coder-plus\n if/glm-4.7\n if/minimax-m2\n if/deepseek-r1\n```\n\n### Qwen (4 modely ZDARMA s kรณdem zaล™รญzenรญ)\n\n```bash\nDashboard โ†’ Connect Qwen\nโ†’ Device code authorization\nโ†’ Unlimited usage\n\nModels:\n qw/qwen3-coder-plus\n qw/qwen3-coder-flash\n```\n\n### Kiro (Claude ZDARMA)\n\n```bash\nDashboard โ†’ Connect Kiro\nโ†’ AWS Builder ID or Google/GitHub\nโ†’ Unlimited usage\n\nModels:\n kr/claude-sonnet-4.5\n kr/claude-haiku-4.5\n```\n\n
\n๐ŸŽจ Vytvoล™te kombinace\n
\n\n### Pล™รญklad 1: Maximalizace pล™edplatnรฉho โ†’ Levnรฉ zรกlohovรกnรญ\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-6 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Pล™รญklad 2: Pouze zdarma (nulovรฉ nรกklady)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n
\n๐Ÿ”ง Integrace s rozhranรญm pล™รญkazovรฉho ล™รกdku\n
\n\n### IDE kurzoru\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from OmniRoute dashboard]\n Model: cc/claude-opus-4-6\n```\n\n### Claude Code\n\nPro konfiguraci jednรญm kliknutรญm pouลพijte strรกnku **Nรกstroje CLI** na ล™รญdicรญm panelu nebo ruฤnฤ› upravte soubor `~/.claude/settings.json` .\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\n\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\n**Moลพnost 1 โ€“ Dashboard (doporuฤeno):**\n\n```\nDashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply\n```\n\n**Moลพnost 2 โ€“ Manuรกlnรญ รบprava:** รšprava `~/.openclaw/openclaw.json` :\n\n```json\n{\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://127.0.0.1:20128/v1\",\n \"apiKey\": \"sk_omniroute\",\n \"api\": \"openai-completions\"\n }\n }\n }\n}\n```\n\n> **Poznรกmka:** OpenClaw funguje pouze s lokรกlnรญm OmniRoute. Mรญsto `localhost` pouลพijte `127.0.0.1` , abyste se vyhnuli problรฉmลฏm s rozliลกenรญm IPv6.\n\n### Cline / Pokraฤovat / RooCode\n\n```\nSettings โ†’ API Configuration:\n Provider: OpenAI Compatible\n Base URL: http://localhost:20128/v1\n API Key: [from OmniRoute dashboard]\n Model: if/kimi-k2-thinking\n```\n\n### OpenCode\n\n**Krok 1:** Pล™idรกnรญ OmniRoute jako vlastnรญho poskytovatele:\n\n```bash\nopencode\n/connect\n# Select \"Other\" โ†’ Enter ID: \"omniroute\" โ†’ Enter your OmniRoute API key\n```\n\n**Krok 2:** Vytvoล™te/upravte `opencode.json` v koล™enovรฉm adresรกล™i projektu:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"provider\": {\n \"omniroute\": {\n \"npm\": \"@ai-sdk/openai-compatible\",\n \"name\": \"OmniRoute\",\n \"options\": {\n \"baseURL\": \"http://localhost:20128/v1\"\n },\n \"models\": {\n \"cc/claude-sonnet-4-20250514\": { \"name\": \"Claude Sonnet 4\" },\n \"gg/gemini-2.5-pro\": { \"name\": \"Gemini 2.5 Pro\" },\n \"if/kimi-k2-thinking\": { \"name\": \"Kimi K2 (Free)\" }\n }\n }\n }\n}\n```\n\n**Krok 3:** Vyberte model v OpenCode:\n\n```bash\n/models\n# Select any OmniRoute model from the list\n```\n\n> **Tip:** Do sekce `models` pล™idejte jakรฝkoli model dostupnรฝ ve vaลกem koncovรฉm bodu OmniRoute `/v1/models` . Pouลพijte formรกt `provider/model-id` z vaลกeho dashboardu OmniRoute.\n\n---\n\n## ๐Ÿ› ล˜eลกenรญ problรฉmลฏ\n\n
\nKliknutรญm rozbalรญte prลฏvodce ล™eลกenรญm problรฉmลฏ\n
\n\n**\"Jazykovรฝ model neposkytoval zprรกvy\"**\n\n- Kvรณta poskytovatele vyฤerpรกna โ†’ Zkontrolujte sledovรกnรญ kvรณt na ล™รญdicรญm panelu\n- ล˜eลกenรญ: Pouลพijte zรกloลพnรญ kombinovanou variantu nebo pล™ejdฤ›te na levnฤ›jลกรญ รบroveลˆ\n\n**Omezenรญ rychlosti**\n\n- Kvรณta pล™edplatnรฉho vyฤerpรกna โ†’ Pล™echod na GLM/MiniMax\n- Pล™idat kombo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking`\n\n**Platnost tokenu OAuth vyprลกela**\n\n- Automaticky aktualizovรกno sluลพbou OmniRoute\n- Pokud problรฉmy pล™etrvรกvajรญ: Ovlรกdacรญ panel โ†’ Poskytovatel โ†’ Znovu pล™ipojit\n\n**Vysokรฉ nรกklady**\n\n- Zkontrolujte statistiky vyuลพitรญ v sekci Nรกstฤ›nka โ†’ Nรกklady\n- Pล™epnout primรกrnรญ model na GLM/MiniMax\n- Pro nekritickรฉ รบlohy pouลพijte bezplatnou รบroveลˆ (Gemini CLI, iFlow).\n\n**Porty ล™รญdicรญho panelu/API jsou nesprรกvnรฉ**\n\n- `PORT` je kanonickรฝ zรกkladnรญ port (a standardnฤ› port API)\n- `API_PORT` pล™episuje pouze posluchaฤ API kompatibilnรญ s OpenAI.\n- `DASHBOARD_PORT` pล™episuje pouze posluchaฤ dashboard/Next.js\n- Nastavte `NEXT_PUBLIC_BASE_URL` na vaลกi veล™ejnou URL adresu ล™รญdicรญho panelu (pro zpฤ›tnรก volรกnรญ OAuth)\n\n**Chyby synchronizace s cloudem**\n\n- Ovฤ›ล™te, zda `BASE_URL` odkazuje na vaลกi spuลกtฤ›nou instanci.\n- Ovฤ›ล™te, zda `CLOUD_URL` odkazuje na vรกลก oฤekรกvanรฝ cloudovรฝ koncovรฝ bod.\n- Udrลพujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na stranฤ› serveru.\n\n**Prvnรญ pล™ihlรกลกenรญ nefunguje**\n\n- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env`\n- Pokud nenรญ nastaveno, zรกloลพnรญ heslo je `123456`\n\n**ลฝรกdnรฉ protokoly poลพadavkลฏ**\n\n- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env`\n\n**Test pล™ipojenรญ ukazuje โ€žNeplatnรฉโ€œ pro poskytovatele kompatibilnรญ s OpenAI**\n\n- Mnoho poskytovatelลฏ nezpล™รญstupลˆuje koncovรฝ bod `/models`\n- OmniRoute v1.0.6+ zahrnuje zรกloลพnรญ ovฤ›ล™enรญ pomocรญ dokonฤenรญ chatu\n- Zajistฤ›te, aby zรกkladnรญ URL adresa obsahovala pล™รญponu `/v1`\n\n### ๐Ÿ” OAuth na vzdรกlenรฉm serveru\n\n\n\n\n> **โš ๏ธ Dลฏleลพitรฉ pro uลพivatele, kteล™รญ provozujรญ OmniRoute na VPS, Dockeru nebo jakรฉmkoli vzdรกlenรฉm serveru**\n\n#### Proฤ selhรกvรก OAuth v rozhranรญ CLI Antigravity / Gemini na vzdรกlenรฝch serverech?\n\nPoskytovatelรฉ rozhranรญ CLI **Antigravity** a **Gemini** pouลพรญvajรญ **Google OAuth 2.0** . Google vyลพaduje, aby se `redirect_uri` v toku OAuth pล™esnฤ› shodoval s jednรญm z pล™edregistrovanรฝch URI v konzoli Google Cloud Console aplikace.\n\nPล™ihlaลกovacรญ รบdaje OAuth, kterรฉ jsou souฤรกstรญ OmniRoute, jsou registrovรกny **pouze pro `localhost`** . Kdyลพ pล™istupujete k OmniRoute na vzdรกlenรฉm serveru (napล™. `https://omniroute.myserver.com` ), Google odmรญtne ovฤ›ล™enรญ pomocรญ:\n\n```\nError 400: redirect_uri_mismatch\n```\n\n#### ล˜eลกenรญ: Nakonfigurujte si vlastnรญ pล™ihlaลกovacรญ รบdaje OAuth\n\nV Google Cloud Console je potล™eba vytvoล™it **ID klienta OAuth 2.0** s URI vaลกeho serveru.\n\n#### Krok za krokem\n\n**1. Otevล™ete konzoli Google Cloud**\n\nPล™ejdฤ›te na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)\n\n**2. Vytvoล™te novรฉ ID klienta OAuth 2.0**\n\n- Kliknฤ›te na **โ€ž+ Vytvoล™it pล™ihlaลกovacรญ รบdajeโ€œ** โ†’ **โ€žID klienta OAuthโ€œ**\n- Typ aplikace: **โ€žWebovรก aplikaceโ€œ**\n- Nรกzev: cokoli chcete (napล™. `OmniRoute Remote` )\n\n**3. Pล™idejte autorizovanรฉ URI pro pล™esmฤ›rovรกnรญ**\n\nDo pole **โ€žAutorizovanรฉ identifikรกtory URI pro pล™esmฤ›rovรกnรญโ€œ** pล™idejte:\n\n```\nhttps://your-server.com/callback\n```\n\n> Nahraฤte `your-server.com` domรฉnou nebo IP adresou vaลกeho serveru (v pล™รญpadฤ› potล™eby uveฤte i port, napล™. `http://45.33.32.156:20128/callback` ).\n\n**4. Uloลพte a zkopรญrujte pล™ihlaลกovacรญ รบdaje**\n\nPo vytvoล™enรญ Google zobrazรญ **ID klienta** a **tajnรฝ kรณd klienta** .\n\n**5. Nastavenรญ promฤ›nnรฝch prostล™edรญ**\n\nVe vaลกem souboru `.env` (nebo promฤ›nnรฝch prostล™edรญ Docker):\n\n```bash\n# For Antigravity:\nANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n\n# For Gemini CLI:\nGEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\nGEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret\n```\n\n**6. Restartujte OmniRoute**\n\n```bash\n# npm:\nnpm run dev\n\n# Docker:\ndocker restart omniroute\n```\n\n**7. Zkuste se znovu pล™ipojit**\n\nล˜รญdicรญ panel โ†’ Poskytovatelรฉ โ†’ Antigravity (nebo Gemini CLI) โ†’ OAuth\n\nGoogle nynรญ bude sprรกvnฤ› pล™esmฤ›rovรกvat na `https://your-server.com/callback` .\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nPokud si teฤ nechcete nastavovat vlastnรญ pล™ihlaลกovacรญ รบdaje, mลฏลพete stรกle pouลพรญt **ruฤnรญ postup pro URL** :\n\n1. OmniRoute otevรญrรก autorizaฤnรญ URL od Googlu\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru).\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe (i kdyลพ se strรกnka nenaฤte)\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute.\n5. Kliknฤ›te na **โ€žPล™ipojitโ€œ**\n\n> To funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na to, zda se naฤetla pล™esmฤ›rovacรญ strรกnka.\n\n---\n\n#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ)\n\nChcete-li zรญskat pล™รญstup k pล™ihlaลกovacรญm รบdajลฏm bez vlastnรญ konfigurace, mลฏลพete pouลพรญt nรกsledujรญcรญ postup:\n\n1. OmniRoute otevล™e URL autorizace Google\n2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru)\n3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe\n4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute\n5. Kliknฤ›te na **โ€žPล™ipojit\"**\n\n> Toto ล™eลกenรญ funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na naฤtenรญ pล™esmฤ›rovacรญ strรกnky.\n\n---\n\n## ๐Ÿ› ๏ธ Technologickรฝ stack\n\n
\nKliknutรญm rozbalรญte podrobnosti o technologickรฉm stacku\n
\n\n- **Runtime** : Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ **nenรญ podporovรกn** โ€” nativnรญ binรกrnรญ soubory `better-sqlite3` jsou nekompatibilnรญ)\n- **Jazyk** : TypeScript 5.9 โ€” **100% TypeScript** napล™รญฤ `src/` a `open-sse/` ( `any` v zรกkladnรญch modulech od verze 2.0)\n- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4\n- **Databรกze** : LowDB (JSON) + SQLite (stav domรฉny + protokoly proxy + audit MCP + rozhodnutรญ o smฤ›rovรกnรญ)\n- **Schรฉmata** : Zod (validace I/O nรกstrojลฏ MCP, API smlouvy)\n- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)\n- **Streamovรกnรญ** : Udรกlosti odeslanรฉ serverem (SSE)\n- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klรญฤe + autorizace s rozsahem MCP\n- **Testovรกnรญ** : Node.js test runner + Vitest (900+ testลฏ vฤetnฤ› unit, integraฤnรญch, E2E)\n- **CI/CD** : Akce GitHubu (automatickรฉ publikovรกnรญ v npm + Docker Hub pล™i vydรกnรญ)\n- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online)\n- **Balรญฤek** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)\n- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)\n- **Odolnost** : Jistiฤ, exponenciรกlnรญ odstavenรญ, ochrana proti hromลฏm, faleลกnรฉ TLS, automatickรฉ kombinovanรฉ samoopravovรกnรญ\n\n---\n\n## ๐Ÿ“– Dokumentace\n\n| Dokument | Popis |\n| ------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| [Uลพivatelskรก pล™รญruฤka](docs/USER_GUIDE.md) | Poskytovatelรฉ, kombinace, integrace CLI, nasazenรญ |\n| [Referenฤnรญ informace k API](docs/API_REFERENCE.md) | Vลกechny koncovรฉ body s pล™รญklady |\n| [MCP server](open-sse/mcp-server/README.md) | 16 nรกstrojลฏ MCP, konfigurace IDE, klienti Python/TS/Go |\n| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamovรกnรญ, sprรกva รบloh |\n| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorovรฉ bodovรกnรญ, balรญฤky reลพimลฏ, samolรฉฤba |\n| [Odstraลˆovรกnรญ problรฉmลฏ](docs/TROUBLESHOOTING.md) | Bฤ›ลพnรฉ problรฉmy a jejich ล™eลกenรญ |\n| [Architektura](docs/ARCHITECTURE.md) | Architektura a internรญ prvky systรฉmu |\n| [Pล™ispรญvรกnรญ](CONTRIBUTING.md) | Nastavenรญ a pokyny pro vรฝvoj |\n| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 |\n| [Bezpeฤnostnรญ zรกsady](SECURITY.md) | Hlรกลกenรญ zranitelnostรญ a bezpeฤnostnรญ postupy |\n| [Nasazenรญ virtuรกlnรญho poฤรญtaฤe](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletnรญ prลฏvodce: Nastavenรญ virtuรกlnรญho poฤรญtaฤe + nginx + Cloudflare |\n| [Galerie funkcรญ](docs/FEATURES.md) | Vizuรกlnรญ prohlรญdka ล™รญdicรญho panelu se snรญmky obrazovky |\n| [Kontrolnรญ seznam vydรกnรญ](docs/RELEASE_CHECKLIST.md) | Kroky ovฤ›ล™enรญ pล™ed vydรกnรญm |\n\n---\n\n## ๐Ÿ—บ๏ธ Plรกn\n\nOmniRoute mรก **v plรกnu vรญce neลพ 210 funkcรญ** v nฤ›kolika fรกzรญch vรฝvoje. Zde jsou klรญฤovรฉ oblasti:\n\n| Kategorie | Plรกnovanรฉ funkce | Hlavnรญ body |\n| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| ๐Ÿง  **Smฤ›rovรกnรญ a inteligence** | 25+ | Smฤ›rovรกnรญ s nejniลพลกรญ latencรญ, smฤ›rovรกnรญ zaloลพenรฉ na tagech, kontrola kvรณt pล™ed vรฝstupem, vรฝbฤ›r รบฤtu P2C |\n| ๐Ÿ”’ **Zabezpeฤenรญ a dodrลพovรกnรญ pล™edpisลฏ** | 20+ | Zpevnฤ›nรญ SSRF, maskovรกnรญ pล™ihlaลกovacรญch รบdajลฏ, limit rychlosti pro kaลพdรฝ koncovรฝ bod, stanovenรญ rozsahu klรญฤลฏ pro sprรกvu |\n| ๐Ÿ“Š **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledovรกnรญ kvรณt v reรกlnรฉm ฤase, sledovรกnรญ nรกkladลฏ podle modelu |\n| ๐Ÿ”„ **Integrace poskytovatelลฏ** | 20+ | Dynamickรฝ registr modelลฏ, doba zchlazenรญ poskytovatelลฏ, Codex pro vรญce รบฤtลฏ, analรฝza kvรณt Copilota |\n| โšก **Vรฝkon** | 15+ | Dvojitรก vrstva mezipamฤ›ti, mezipamฤ›ลฅ vรฝzev, mezipamฤ›ลฅ odpovฤ›dรญ, udrลพovรกnรญ streamovรกnรญ, dรกvkovรฉ API |\n| ๐ŸŒ **Ekosystรฉm** | 10+ | WebSocket API, horkรฉ opฤ›tovnรฉ naฤรญtรกnรญ konfigurace, distribuovanรฉ รบloลพiลกtฤ› konfigurace, komerฤnรญ reลพim |\n\n### ๐Ÿ”œ Jiลพ brzy\n\n- ๐Ÿ”— **Integrace OpenCode** โ€” Nativnรญ podpora poskytovatelลฏ pro IDE kรณdovรกnรญ s AI v OpenCode\n- ๐Ÿ”— **Integrace TRAE** โ€” Plnรก podpora vรฝvojovรฉho rรกmce TRAE pro umฤ›lou inteligenci\n- ๐Ÿ“ฆ **Dรกvkovรฉ API** โ€” Asynchronnรญ dรกvkovรฉ zpracovรกnรญ hromadnรฝch poลพadavkลฏ\n- ๐ŸŽฏ **Smฤ›rovรกnรญ na zรกkladฤ› tagลฏ** โ€” Smฤ›rovรกnรญ poลพadavkลฏ na zรกkladฤ› vlastnรญch tagลฏ a metadat\n- ๐Ÿ’ฐ **Strategie nejniลพลกรญch nรกkladลฏ** โ€“ Automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele\n\n> ๐Ÿ“ รšplnรฉ specifikace funkcรญ jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobnรฝch specifikacรญ)\n\n---\n\n## ๐Ÿ‘ฅ Pล™ispฤ›vatelรฉ\n\n[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Pล™ispฤ›vatelรฉ](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)\n\n### Jak pล™ispฤ›t\n\n1. Vytvoล™enรญ forku repozitรกล™e\n2. Vytvoล™te si vlastnรญ vฤ›tev feature ( `git checkout -b feature/amazing-feature` )\n3. Potvrฤte zmฤ›ny ( `git commit -m 'Add amazing feature'` )\n4. Odeslat do vฤ›tve ( `git push origin feature/amazing-feature` )\n5. Otevล™รญt ลพรกdost o zmฤ›ny (pull request)\n\nPodrobnรฉ pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) .\n\n### Vydรกnรญ novรฉ verze\n\n```bash\n# Create a release โ€” npm publish happens automatically\ngh release create v2.0.0 --title \"v2.0.0\" --generate-notes\n```\n\n---\n\n## ๐Ÿ“Š Hvฤ›zdnรก historie\n\n## Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu\n\n## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)\n\n## ๐Ÿ™ Podฤ›kovรกnรญ\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** โ€“ pลฏvodnรญmu projektu, kterรฝ inspiroval tento fork. OmniRoute stavรญ na tomto neuvฤ›ล™itelnรฉm zรกkladu s dalลกรญmi funkcemi, multimodรกlnรญmi API a kompletnรญm pล™epsรกnรญm TypeScriptu.\n\nZvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€“ pลฏvodnรญ implementaci Go, kterรก inspirovala tento JavaScriptovรฝ port.\n\n---\n\n## ๐Ÿ“„ Licence\n\nLicence MIT - podrobnosti viz [LICENCE](LICENSE) .\n\n---\n\n
\n Vytvoล™eno s โค๏ธ pro vรฝvojรกล™e, kteล™รญ programujรญ 24 hodin dennฤ›, 7 dnรญ v tรฝdnu\n
\n

omniroute.online

\n
\n\n"}}, "docs/i18n/ms/docs/guides/USER_GUIDE.md": {"df4fa8e65b6d5e5876dcecd5a0eec84928b2be31": {"t": 1785746499.9295108, "n": 37587, "h": "3e844b7e135eddd1", "c": "# User Guide (Bahasa Melayu)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../../bn/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../../fa/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../../gu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../../hi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../../mr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../../sw/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../../ta/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../../te/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../../tr/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../../ur/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **๐Ÿ’ฐ CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n\n---\n\n## ๐ŸŽฏ Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## ๐Ÿ“– Provider Setup\n\n### ๐Ÿ” Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n\n\n#### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### ๐Ÿ’ฐ Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` โ€” **Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` โ€” **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest` โ€” **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### ๐Ÿ†“ FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard โ†’ Connect Qoder โ†’ OAuth login โ†’ Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard โ†’ Connect Qwen โ†’ Device code auth โ†’ Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro โ†’ AWS Builder ID or Google/GitHub โ†’ Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## ๐ŸŽจ Combos\n\nYou 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.\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## ๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools โ†’ OpenClaw โ†’ Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## Penempatan\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid 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.\n\n
\nView xbps-src template\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## ๐Ÿ“Š Available Models\n\n
\nView all available models\n\n**Claude Code (`cc/`)** โ€” Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** โ€” Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** โ€” $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** โ€” $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** โ€” FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** โ€” FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** โ€” FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n
\n\n---\n\n## ๐Ÿงฉ Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**.\n\nNotes:\n\n- 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.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific โ†’ Combo-specific โ†’ Provider-specific โ†’ Global โ†’ Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** โ€” Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** โ€” Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard โ†’ Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard โ†’ Settings โ†’ Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order โ€” primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one โ€” balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* โ†’ Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* โ†’ Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard โ†’ Settings โ†’ Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** โ€” System-level request shaping:\n - **Requests Per Minute (RPM)** โ€” Maximum requests per minute per account\n - **Min Time Between Requests** โ€” Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** โ€” Maximum simultaneous requests per account\n\n2. **Connection Cooldown** โ€” Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** โ€” Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** โ€” Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** โ€” Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** โ€” Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** โ€” Consecutive provider failures before opening the breaker\n - **Reset Timeout** โ€” Time window before the provider is tested again\n - **CLOSED** (Healthy) โ€” Requests flow normally\n - **OPEN** โ€” Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** โ€” Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard โ†’ Health** only.\n\n4. **Wait For Cooldown** โ€” If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** โ€” When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard โ†’ Settings โ†’ System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**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).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all โ†’ share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard โ†’ Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries โ€” cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**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.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard โ†’ Combos โ†’ Create/Edit โ†’ Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard โ†’ Settings โ†’ Routing โ†’ Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard โ†’ Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### Pasang\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput โ†’ `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64โ€“16384 MB) |\n\n๐Ÿ“– Full documentation: [`electron/README.md`](../electron/README.md)\n"}, "7c23dab64de929686d2326f6824527ba9c746ca9": {"t": 1785764412.907156, "n": 37587, "h": "3e844b7e135eddd1", "c": "# User Guide (Bahasa Melayu)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../../bn/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../../fa/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../../gu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../../hi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../../mr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../../sw/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../../ta/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../../te/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../../tr/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../../ur/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **๐Ÿ’ฐ CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n\n---\n\n## ๐ŸŽฏ Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## ๐Ÿ“– Provider Setup\n\n### ๐Ÿ” Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n\n\n#### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### ๐Ÿ’ฐ Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` โ€” **Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` โ€” **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest` โ€” **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### ๐Ÿ†“ FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard โ†’ Connect Qoder โ†’ OAuth login โ†’ Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard โ†’ Connect Qwen โ†’ Device code auth โ†’ Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro โ†’ AWS Builder ID or Google/GitHub โ†’ Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## ๐ŸŽจ Combos\n\nYou 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.\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## ๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools โ†’ OpenClaw โ†’ Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## Penempatan\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid 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.\n\n
\nView xbps-src template\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## ๐Ÿ“Š Available Models\n\n
\nView all available models\n\n**Claude Code (`cc/`)** โ€” Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** โ€” Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** โ€” $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** โ€” $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** โ€” FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** โ€” FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** โ€” FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n
\n\n---\n\n## ๐Ÿงฉ Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**.\n\nNotes:\n\n- 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.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific โ†’ Combo-specific โ†’ Provider-specific โ†’ Global โ†’ Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** โ€” Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** โ€” Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard โ†’ Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard โ†’ Settings โ†’ Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order โ€” primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one โ€” balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* โ†’ Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* โ†’ Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard โ†’ Settings โ†’ Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** โ€” System-level request shaping:\n - **Requests Per Minute (RPM)** โ€” Maximum requests per minute per account\n - **Min Time Between Requests** โ€” Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** โ€” Maximum simultaneous requests per account\n\n2. **Connection Cooldown** โ€” Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** โ€” Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** โ€” Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** โ€” Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** โ€” Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** โ€” Consecutive provider failures before opening the breaker\n - **Reset Timeout** โ€” Time window before the provider is tested again\n - **CLOSED** (Healthy) โ€” Requests flow normally\n - **OPEN** โ€” Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** โ€” Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard โ†’ Health** only.\n\n4. **Wait For Cooldown** โ€” If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** โ€” When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard โ†’ Settings โ†’ System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**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).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all โ†’ share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard โ†’ Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries โ€” cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**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.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard โ†’ Combos โ†’ Create/Edit โ†’ Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard โ†’ Settings โ†’ Routing โ†’ Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard โ†’ Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### Pasang\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput โ†’ `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64โ€“16384 MB) |\n\n๐Ÿ“– Full documentation: [`electron/README.md`](../electron/README.md)\n"}, "8a1d9beb55fe825bd132c8696117046258869a79": {"t": 1785764414.580887, "n": 38219, "h": "c4764e7caf2c0a15", "c": "# User Guide (Bahasa Melayu)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../../bn/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../../fa/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../../gu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../../hi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../../mr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../../sw/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../../ta/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../../te/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../../tr/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../../ur/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **๐Ÿ’ฐ CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n**๐Ÿ’ก Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!\n\n---\n\n## ๐ŸŽฏ Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash (180K free/month)\n 2. if/kimi-k2-thinking (unlimited free)\n 3. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## ๐Ÿ“– Provider Setup\n\n### ๐Ÿ” Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n#### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### ๐Ÿ’ฐ Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` โ€” **Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` โ€” **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest` โ€” **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### ๐Ÿ†“ FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard โ†’ Connect Qoder โ†’ OAuth login โ†’ Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard โ†’ Connect Qwen โ†’ Device code auth โ†’ Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro โ†’ AWS Builder ID or Google/GitHub โ†’ Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## ๐ŸŽจ Combos\n\nYou 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.\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## ๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools โ†’ OpenClaw โ†’ Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## Penempatan\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid 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.\n\n
\nView xbps-src template\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## ๐Ÿ“Š Available Models\n\n
\nView all available models\n\n**Claude Code (`cc/`)** โ€” Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** โ€” Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n**Gemini CLI (`gc/`)** โ€” FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** โ€” $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** โ€” $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** โ€” FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** โ€” FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** โ€” FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n
\n\n---\n\n## ๐Ÿงฉ Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**.\n\nNotes:\n\n- 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.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific โ†’ Combo-specific โ†’ Provider-specific โ†’ Global โ†’ Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** โ€” Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** โ€” Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard โ†’ Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard โ†’ Settings โ†’ Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order โ€” primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one โ€” balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* โ†’ Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* โ†’ Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard โ†’ Settings โ†’ Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** โ€” System-level request shaping:\n - **Requests Per Minute (RPM)** โ€” Maximum requests per minute per account\n - **Min Time Between Requests** โ€” Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** โ€” Maximum simultaneous requests per account\n\n2. **Connection Cooldown** โ€” Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** โ€” Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** โ€” Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** โ€” Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** โ€” Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** โ€” Consecutive provider failures before opening the breaker\n - **Reset Timeout** โ€” Time window before the provider is tested again\n - **CLOSED** (Healthy) โ€” Requests flow normally\n - **OPEN** โ€” Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** โ€” Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard โ†’ Health** only.\n\n4. **Wait For Cooldown** โ€” If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** โ€” When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard โ†’ Settings โ†’ System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**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).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all โ†’ share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard โ†’ Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries โ€” cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**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.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard โ†’ Combos โ†’ Create/Edit โ†’ Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard โ†’ Settings โ†’ Routing โ†’ Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard โ†’ Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### Pasang\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput โ†’ `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64โ€“16384 MB) |\n\n๐Ÿ“– Full documentation: [`electron/README.md`](../electron/README.md)\n"}}, "docs/i18n/no/docs/guides/USER_GUIDE.md": {"df4fa8e65b6d5e5876dcecd5a0eec84928b2be31": {"t": 1785746502.1201484, "n": 37581, "h": "2b2b21e44f8ea8ff", "c": "# User Guide (Norsk)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../../bn/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../../fa/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../../gu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../../hi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../../mr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../../sw/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../../ta/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../../te/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../../tr/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../../ur/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **๐Ÿ’ฐ CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n\n---\n\n## ๐ŸŽฏ Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## ๐Ÿ“– Provider Setup\n\n### ๐Ÿ” Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n\n\n#### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### ๐Ÿ’ฐ Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` โ€” **Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` โ€” **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest` โ€” **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### ๐Ÿ†“ FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard โ†’ Connect Qoder โ†’ OAuth login โ†’ Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard โ†’ Connect Qwen โ†’ Device code auth โ†’ Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro โ†’ AWS Builder ID or Google/GitHub โ†’ Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## ๐ŸŽจ Combos\n\nYou 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.\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## ๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools โ†’ OpenClaw โ†’ Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## Utrulling\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid 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.\n\n
\nView xbps-src template\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## ๐Ÿ“Š Available Models\n\n
\nView all available models\n\n**Claude Code (`cc/`)** โ€” Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** โ€” Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** โ€” $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** โ€” $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** โ€” FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** โ€” FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** โ€” FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n
\n\n---\n\n## ๐Ÿงฉ Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**.\n\nNotes:\n\n- 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.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific โ†’ Combo-specific โ†’ Provider-specific โ†’ Global โ†’ Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** โ€” Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** โ€” Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard โ†’ Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard โ†’ Settings โ†’ Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order โ€” primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one โ€” balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* โ†’ Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* โ†’ Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard โ†’ Settings โ†’ Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** โ€” System-level request shaping:\n - **Requests Per Minute (RPM)** โ€” Maximum requests per minute per account\n - **Min Time Between Requests** โ€” Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** โ€” Maximum simultaneous requests per account\n\n2. **Connection Cooldown** โ€” Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** โ€” Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** โ€” Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** โ€” Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** โ€” Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** โ€” Consecutive provider failures before opening the breaker\n - **Reset Timeout** โ€” Time window before the provider is tested again\n - **CLOSED** (Healthy) โ€” Requests flow normally\n - **OPEN** โ€” Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** โ€” Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard โ†’ Health** only.\n\n4. **Wait For Cooldown** โ€” If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** โ€” When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard โ†’ Settings โ†’ System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**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).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all โ†’ share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard โ†’ Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries โ€” cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**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.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard โ†’ Combos โ†’ Create/Edit โ†’ Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard โ†’ Settings โ†’ Routing โ†’ Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard โ†’ Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### Installer\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput โ†’ `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64โ€“16384 MB) |\n\n๐Ÿ“– Full documentation: [`electron/README.md`](../electron/README.md)\n"}, "7c23dab64de929686d2326f6824527ba9c746ca9": {"t": 1785764413.2452216, "n": 37581, "h": "2b2b21e44f8ea8ff", "c": "# User Guide (Norsk)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../../bn/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../../fa/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../../gu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../../hi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../../mr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../../sw/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../../ta/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../../te/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../../tr/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../../ur/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **๐Ÿ’ฐ CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n\n---\n\n## ๐ŸŽฏ Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## ๐Ÿ“– Provider Setup\n\n### ๐Ÿ” Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n\n\n#### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### ๐Ÿ’ฐ Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` โ€” **Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` โ€” **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest` โ€” **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### ๐Ÿ†“ FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard โ†’ Connect Qoder โ†’ OAuth login โ†’ Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard โ†’ Connect Qwen โ†’ Device code auth โ†’ Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro โ†’ AWS Builder ID or Google/GitHub โ†’ Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## ๐ŸŽจ Combos\n\nYou 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.\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## ๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools โ†’ OpenClaw โ†’ Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## Utrulling\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid 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.\n\n
\nView xbps-src template\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## ๐Ÿ“Š Available Models\n\n
\nView all available models\n\n**Claude Code (`cc/`)** โ€” Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** โ€” Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** โ€” $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** โ€” $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** โ€” FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** โ€” FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** โ€” FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n
\n\n---\n\n## ๐Ÿงฉ Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**.\n\nNotes:\n\n- 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.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific โ†’ Combo-specific โ†’ Provider-specific โ†’ Global โ†’ Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** โ€” Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** โ€” Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard โ†’ Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard โ†’ Settings โ†’ Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order โ€” primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one โ€” balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* โ†’ Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* โ†’ Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard โ†’ Settings โ†’ Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** โ€” System-level request shaping:\n - **Requests Per Minute (RPM)** โ€” Maximum requests per minute per account\n - **Min Time Between Requests** โ€” Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** โ€” Maximum simultaneous requests per account\n\n2. **Connection Cooldown** โ€” Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** โ€” Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** โ€” Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** โ€” Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** โ€” Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** โ€” Consecutive provider failures before opening the breaker\n - **Reset Timeout** โ€” Time window before the provider is tested again\n - **CLOSED** (Healthy) โ€” Requests flow normally\n - **OPEN** โ€” Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** โ€” Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard โ†’ Health** only.\n\n4. **Wait For Cooldown** โ€” If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** โ€” When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard โ†’ Settings โ†’ System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**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).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all โ†’ share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard โ†’ Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries โ€” cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**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.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard โ†’ Combos โ†’ Create/Edit โ†’ Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard โ†’ Settings โ†’ Routing โ†’ Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard โ†’ Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### Installer\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput โ†’ `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64โ€“16384 MB) |\n\n๐Ÿ“– Full documentation: [`electron/README.md`](../electron/README.md)\n"}, "8a1d9beb55fe825bd132c8696117046258869a79": {"t": 1785764414.7922587, "n": 38213, "h": "69a5b1611104b49e", "c": "# User Guide (Norsk)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../../bn/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../../fa/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../../gu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../../hi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../../mr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../../sw/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../../ta/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../../te/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../../tr/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../../ur/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **๐Ÿ’ฐ CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n**๐Ÿ’ก Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!\n\n---\n\n## ๐ŸŽฏ Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash (180K free/month)\n 2. if/kimi-k2-thinking (unlimited free)\n 3. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## ๐Ÿ“– Provider Setup\n\n### ๐Ÿ” Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n#### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### ๐Ÿ’ฐ Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` โ€” **Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` โ€” **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest` โ€” **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### ๐Ÿ†“ FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard โ†’ Connect Qoder โ†’ OAuth login โ†’ Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard โ†’ Connect Qwen โ†’ Device code auth โ†’ Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro โ†’ AWS Builder ID or Google/GitHub โ†’ Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## ๐ŸŽจ Combos\n\nYou 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.\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## ๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools โ†’ OpenClaw โ†’ Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## Utrulling\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid 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.\n\n
\nView xbps-src template\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## ๐Ÿ“Š Available Models\n\n
\nView all available models\n\n**Claude Code (`cc/`)** โ€” Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** โ€” Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n**Gemini CLI (`gc/`)** โ€” FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** โ€” $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** โ€” $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** โ€” FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** โ€” FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** โ€” FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n
\n\n---\n\n## ๐Ÿงฉ Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**.\n\nNotes:\n\n- 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.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific โ†’ Combo-specific โ†’ Provider-specific โ†’ Global โ†’ Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** โ€” Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** โ€” Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard โ†’ Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard โ†’ Settings โ†’ Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order โ€” primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one โ€” balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* โ†’ Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* โ†’ Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard โ†’ Settings โ†’ Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** โ€” System-level request shaping:\n - **Requests Per Minute (RPM)** โ€” Maximum requests per minute per account\n - **Min Time Between Requests** โ€” Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** โ€” Maximum simultaneous requests per account\n\n2. **Connection Cooldown** โ€” Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** โ€” Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** โ€” Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** โ€” Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** โ€” Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** โ€” Consecutive provider failures before opening the breaker\n - **Reset Timeout** โ€” Time window before the provider is tested again\n - **CLOSED** (Healthy) โ€” Requests flow normally\n - **OPEN** โ€” Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** โ€” Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard โ†’ Health** only.\n\n4. **Wait For Cooldown** โ€” If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** โ€” When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard โ†’ Settings โ†’ System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**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).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all โ†’ share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard โ†’ Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries โ€” cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**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.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard โ†’ Combos โ†’ Create/Edit โ†’ Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard โ†’ Settings โ†’ Routing โ†’ Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard โ†’ Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### Installer\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput โ†’ `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64โ€“16384 MB) |\n\n๐Ÿ“– Full documentation: [`electron/README.md`](../electron/README.md)\n"}}, "docs/i18n/he/docs/guides/USER_GUIDE.md": {"df4fa8e65b6d5e5876dcecd5a0eec84928b2be31": {"t": 1785746509.7690573, "n": 37573, "h": "a98fc610b5fc1ee4", "c": "# User Guide (ืขื‘ืจื™ืช)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../../bn/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../../fa/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../../gu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../../hi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../../mr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../../sw/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../../ta/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../../te/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../../tr/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../../ur/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **๐Ÿ’ฐ CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n\n---\n\n## ๐ŸŽฏ Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## ๐Ÿ“– Provider Setup\n\n### ๐Ÿ” Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n\n\n#### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### ๐Ÿ’ฐ Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` โ€” **Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` โ€” **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest` โ€” **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### ๐Ÿ†“ FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard โ†’ Connect Qoder โ†’ OAuth login โ†’ Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard โ†’ Connect Qwen โ†’ Device code auth โ†’ Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro โ†’ AWS Builder ID or Google/GitHub โ†’ Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## ๐ŸŽจ Combos\n\nYou 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.\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## ๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools โ†’ OpenClaw โ†’ Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## ืคืจื™ืกื”\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid 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.\n\n
\nView xbps-src template\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## ๐Ÿ“Š Available Models\n\n
\nView all available models\n\n**Claude Code (`cc/`)** โ€” Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** โ€” Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** โ€” $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** โ€” $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** โ€” FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** โ€” FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** โ€” FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n
\n\n---\n\n## ๐Ÿงฉ Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**.\n\nNotes:\n\n- 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.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific โ†’ Combo-specific โ†’ Provider-specific โ†’ Global โ†’ Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** โ€” Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** โ€” Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard โ†’ Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard โ†’ Settings โ†’ Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order โ€” primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one โ€” balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* โ†’ Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* โ†’ Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard โ†’ Settings โ†’ Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** โ€” System-level request shaping:\n - **Requests Per Minute (RPM)** โ€” Maximum requests per minute per account\n - **Min Time Between Requests** โ€” Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** โ€” Maximum simultaneous requests per account\n\n2. **Connection Cooldown** โ€” Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** โ€” Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** โ€” Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** โ€” Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** โ€” Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** โ€” Consecutive provider failures before opening the breaker\n - **Reset Timeout** โ€” Time window before the provider is tested again\n - **CLOSED** (Healthy) โ€” Requests flow normally\n - **OPEN** โ€” Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** โ€” Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard โ†’ Health** only.\n\n4. **Wait For Cooldown** โ€” If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** โ€” When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard โ†’ Settings โ†’ System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**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).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all โ†’ share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard โ†’ Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries โ€” cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**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.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard โ†’ Combos โ†’ Create/Edit โ†’ Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard โ†’ Settings โ†’ Routing โ†’ Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard โ†’ Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### ื”ืชืงื ื”\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput โ†’ `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64โ€“16384 MB) |\n\n๐Ÿ“– Full documentation: [`electron/README.md`](../electron/README.md)\n"}, "7c23dab64de929686d2326f6824527ba9c746ca9": {"t": 1785764410.926768, "n": 37573, "h": "a98fc610b5fc1ee4", "c": "# User Guide (ืขื‘ืจื™ืช)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../../bn/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../../fa/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../../gu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../../hi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../../mr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../../sw/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../../ta/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../../te/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../../tr/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../../ur/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **๐Ÿ’ฐ CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n\n---\n\n## ๐ŸŽฏ Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. if/kimi-k2-thinking (unlimited free)\n 2. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## ๐Ÿ“– Provider Setup\n\n### ๐Ÿ” Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n\n\n#### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### ๐Ÿ’ฐ Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` โ€” **Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` โ€” **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest` โ€” **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### ๐Ÿ†“ FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard โ†’ Connect Qoder โ†’ OAuth login โ†’ Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard โ†’ Connect Qwen โ†’ Device code auth โ†’ Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro โ†’ AWS Builder ID or Google/GitHub โ†’ Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## ๐ŸŽจ Combos\n\nYou 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.\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. if/kimi-k2-thinking (unlimited)\n 2. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## ๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools โ†’ OpenClaw โ†’ Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## ืคืจื™ืกื”\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid 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.\n\n
\nView xbps-src template\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## ๐Ÿ“Š Available Models\n\n
\nView all available models\n\n**Claude Code (`cc/`)** โ€” Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** โ€” Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** โ€” $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** โ€” $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** โ€” FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** โ€” FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** โ€” FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n
\n\n---\n\n## ๐Ÿงฉ Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**.\n\nNotes:\n\n- 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.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific โ†’ Combo-specific โ†’ Provider-specific โ†’ Global โ†’ Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** โ€” Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** โ€” Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard โ†’ Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard โ†’ Settings โ†’ Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order โ€” primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one โ€” balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* โ†’ Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* โ†’ Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard โ†’ Settings โ†’ Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** โ€” System-level request shaping:\n - **Requests Per Minute (RPM)** โ€” Maximum requests per minute per account\n - **Min Time Between Requests** โ€” Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** โ€” Maximum simultaneous requests per account\n\n2. **Connection Cooldown** โ€” Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** โ€” Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** โ€” Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** โ€” Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** โ€” Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** โ€” Consecutive provider failures before opening the breaker\n - **Reset Timeout** โ€” Time window before the provider is tested again\n - **CLOSED** (Healthy) โ€” Requests flow normally\n - **OPEN** โ€” Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** โ€” Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard โ†’ Health** only.\n\n4. **Wait For Cooldown** โ€” If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** โ€” When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard โ†’ Settings โ†’ System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**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).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all โ†’ share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard โ†’ Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries โ€” cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**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.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard โ†’ Combos โ†’ Create/Edit โ†’ Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard โ†’ Settings โ†’ Routing โ†’ Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard โ†’ Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### ื”ืชืงื ื”\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput โ†’ `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64โ€“16384 MB) |\n\n๐Ÿ“– Full documentation: [`electron/README.md`](../electron/README.md)\n"}, "8a1d9beb55fe825bd132c8696117046258869a79": {"t": 1785764413.4347286, "n": 38205, "h": "365a9a21800e3cc7", "c": "# User Guide (ืขื‘ืจื™ืช)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../../bn/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../../fa/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../../gu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../../hi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../../mr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../../sw/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../../ta/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../../te/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../../tr/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../../ur/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md)\n\n---\n\nComplete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.\n\n---\n\n## Table of Contents\n\n- [Pricing at a Glance](#-pricing-at-a-glance)\n- [Use Cases](#-use-cases)\n- [Provider Setup](#-provider-setup)\n- [CLI Integration](#-cli-integration)\n- [Deployment](#-deployment)\n- [Available Models](#-available-models)\n- [Advanced Features](#-advanced-features)\n\n---\n\n## ๐Ÿ’ฐ Pricing at a Glance\n\n| Tier | Provider | Cost | Quota Reset | Best For |\n| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |\n| **๐Ÿ’ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |\n| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |\n| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |\n| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |\n| **๐Ÿ”‘ API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |\n| | Groq | Pay per use | None | Ultra-fast inference |\n| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |\n| | Mistral | Pay per use | None | EU-hosted models |\n| | Perplexity | Pay per use | None | Search-augmented |\n| | Together AI | Pay per use | None | Open-source models |\n| | Fireworks AI | Pay per use | None | Fast FLUX images |\n| | Cerebras | Pay per use | None | Wafer-scale speed |\n| | Cohere | Pay per use | None | Command R+ RAG |\n| | NVIDIA NIM | Pay per use | None | Enterprise models |\n| **๐Ÿ’ฐ CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |\n| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |\n| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |\n| **๐Ÿ†“ FREE** | Qoder | $0 | Unlimited | 8 models free |\n| | Qwen | $0 | Unlimited | 3 models free |\n| | Kiro | $0 | Unlimited | Claude free |\n\n**๐Ÿ’ก Pro Tip:** Start with Gemini CLI (180K free/month) + Qoder (unlimited free) combo = $0 cost!\n\n---\n\n## ๐ŸŽฏ Use Cases\n\n### Case 1: \"I have Claude Pro subscription\"\n\n**Problem:** Quota expires unused, rate limits during heavy coding\n\n```\nCombo: \"maximize-claude\"\n 1. cc/claude-opus-4-7 (use subscription fully)\n 2. glm/glm-4.7 (cheap backup when quota out)\n 3. if/kimi-k2-thinking (free emergency fallback)\n\nMonthly cost: $20 (subscription) + ~$5 (backup) = $25 total\nvs. $20 + hitting limits = frustration\n```\n\n### Case 2: \"I want zero cost\"\n\n**Problem:** Can't afford subscriptions, need reliable AI coding\n\n```\nCombo: \"free-forever\"\n 1. gc/gemini-3-flash (180K free/month)\n 2. if/kimi-k2-thinking (unlimited free)\n 3. qw/qwen3-coder-plus (unlimited free)\n\nMonthly cost: $0\nQuality: Production-ready models\n```\n\n### Case 3: \"I need 24/7 coding, no interruptions\"\n\n**Problem:** Deadlines, can't afford downtime\n\n```\nCombo: \"always-on\"\n 1. cc/claude-opus-4-7 (best quality)\n 2. cx/gpt-5.2-codex (second subscription)\n 3. glm/glm-4.7 (cheap, resets daily)\n 4. minimax/MiniMax-M2.1 (cheapest, 5h reset)\n 5. if/kimi-k2-thinking (free unlimited)\n\nResult: 5 layers of fallback = zero downtime\nMonthly cost: $20-200 (subscriptions) + $10-20 (backup)\n```\n\n### Case 4: \"I want FREE AI in OpenClaw\"\n\n**Problem:** Need AI assistant in messaging apps, completely free\n\n```\nCombo: \"openclaw-free\"\n 1. if/glm-4.7 (unlimited free)\n 2. if/minimax-m2.1 (unlimited free)\n 3. if/kimi-k2-thinking (unlimited free)\n\nMonthly cost: $0\nAccess via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...\n```\n\n---\n\n## ๐Ÿ“– Provider Setup\n\n### ๐Ÿ” Subscription Providers\n\n#### Claude Code (Pro/Max)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Claude Code\nโ†’ OAuth login โ†’ Auto token refresh\nโ†’ 5-hour + weekly quota tracking\n\nModels:\n cc/claude-opus-4-7\n cc/claude-sonnet-4-5-20250929\n cc/claude-haiku-4-5-20251001\n```\n\n**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!\n\n#### OpenAI Codex (Plus/Pro)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Codex\nโ†’ OAuth login (port 1455)\nโ†’ 5-hour + weekly reset\n\nModels:\n cx/gpt-5.2-codex\n cx/gpt-5.1-codex-max\n```\n\n#### Gemini CLI (FREE 180K/month!)\n\n```bash\nDashboard โ†’ Providers โ†’ Connect Gemini CLI\nโ†’ Google OAuth\nโ†’ 180K completions/month + 1K/day\n\nModels:\n gc/gemini-3-flash-preview\n gc/gemini-2.5-pro\n```\n\n**Best Value:** Huge free tier! Use this before paid tiers.\n\n#### GitHub Copilot\n\n```bash\nDashboard โ†’ Providers โ†’ Connect GitHub\nโ†’ OAuth via GitHub\nโ†’ Monthly reset (1st of month)\n\nModels:\n gh/gpt-5\n gh/claude-4.5-sonnet\n gh/gemini-3.1-pro-preview\n```\n\n### ๐Ÿ’ฐ Cheap Providers\n\n#### GLM-4.7 (Daily reset, $0.6/1M)\n\n1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)\n2. Get API key from Coding Plan\n3. Dashboard โ†’ Add API Key: Provider: `glm`, API Key: `your-key`\n\n**Use:** `glm/glm-4.7` โ€” **Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM.\n\n#### MiniMax M2.1 (5h reset, $0.20/1M)\n\n1. Sign up: [MiniMax](https://www.minimax.io/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `minimax/MiniMax-M2.1` โ€” **Pro Tip:** Cheapest option for long context (1M tokens)!\n\n#### Kimi K2 ($9/month flat)\n\n1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)\n2. Get API key โ†’ Dashboard โ†’ Add API Key\n\n**Use:** `kimi/kimi-latest` โ€” **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!\n\n### ๐Ÿ†“ FREE Providers\n\n#### Qoder (8 FREE models)\n\n```bash\nDashboard โ†’ Connect Qoder โ†’ OAuth login โ†’ Unlimited usage\n\nModels: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1\n```\n\n#### Qwen (3 FREE models)\n\n```bash\nDashboard โ†’ Connect Qwen โ†’ Device code auth โ†’ Unlimited usage\n\nModels: qw/qwen3-coder-plus, qw/qwen3-coder-flash\n```\n\n#### Kiro (Claude FREE)\n\n```bash\nDashboard โ†’ Connect Kiro โ†’ AWS Builder ID or Google/GitHub โ†’ Unlimited\n\nModels: kr/claude-sonnet-4.5, kr/claude-haiku-4.5\n```\n\n---\n\n## ๐ŸŽจ Combos\n\nYou 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.\n\n### Example 1: Maximize Subscription โ†’ Cheap Backup\n\n```\nDashboard โ†’ Combos โ†’ Create New\n\nName: premium-coding\nModels:\n 1. cc/claude-opus-4-7 (Subscription primary)\n 2. glm/glm-4.7 (Cheap backup, $0.6/1M)\n 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)\n\nUse in CLI: premium-coding\n```\n\n### Example 2: Free-Only (Zero Cost)\n\n```\nName: free-combo\nModels:\n 1. gc/gemini-3-flash-preview (180K free/month)\n 2. if/kimi-k2-thinking (unlimited)\n 3. qw/qwen3-coder-plus (unlimited)\n\nCost: $0 forever!\n```\n\n---\n\n## ๐Ÿ”ง CLI Integration\n\n### Cursor IDE\n\n```\nSettings โ†’ Models โ†’ Advanced:\n OpenAI API Base URL: http://localhost:20128/v1\n OpenAI API Key: [from omniroute dashboard]\n Model: cc/claude-opus-4-7\n```\n\n### Claude Code\n\nEdit `~/.claude/config.json`:\n\n```json\n{\n \"anthropic_api_base\": \"http://localhost:20128/v1\",\n \"anthropic_api_key\": \"your-omniroute-api-key\"\n}\n```\n\n### Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=\"http://localhost:20128\"\nexport OPENAI_API_KEY=\"your-omniroute-api-key\"\ncodex \"your prompt\"\n```\n\n### OpenClaw\n\nEdit `~/.openclaw/openclaw.json`:\n\n```json\n{\n \"agents\": {\n \"defaults\": {\n \"model\": { \"primary\": \"omniroute/if/glm-4.7\" }\n }\n },\n \"models\": {\n \"providers\": {\n \"omniroute\": {\n \"baseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"your-omniroute-api-key\",\n \"api\": \"openai-completions\",\n \"models\": [{ \"id\": \"if/glm-4.7\", \"name\": \"glm-4.7\" }]\n }\n }\n }\n}\n```\n\n**Or use Dashboard:** CLI Tools โ†’ OpenClaw โ†’ Auto-config\n\n### Cline / Continue / RooCode\n\n```\nProvider: OpenAI Compatible\nBase URL: http://localhost:20128/v1\nAPI Key: [from dashboard]\nModel: cc/claude-opus-4-7\n```\n\n---\n\n## ืคืจื™ืกื”\n\n### Global npm install (Recommended)\n\n```bash\nnpm install -g omniroute\n\n# Create config directory\nmkdir -p ~/.omniroute\n\n# Create .env file (see .env.example)\ncp .env.example ~/.omniroute/.env\n\n# Start server\nomniroute\n# Or with custom port:\nomniroute --port 3000\n```\n\nThe CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`.\n\n### Uninstalling\n\nWhen you no longer need OmniRoute, we provide two quick scripts for a clean removal:\n\n| Command | Action |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. |\n| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. |\n\n> 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`.\n\n### VPS Deployment\n\n```bash\ngit clone https://github.com/diegosouzapw/OmniRoute.git\ncd OmniRoute && npm install && npm run build\n\nexport JWT_SECRET=\"your-secure-secret-change-this\"\nexport INITIAL_PASSWORD=\"your-password\"\nexport DATA_DIR=\"/var/lib/omniroute\"\nexport PORT=\"20128\"\nexport HOSTNAME=\"0.0.0.0\"\nexport NODE_ENV=\"production\"\nexport NEXT_PUBLIC_BASE_URL=\"http://localhost:20128\"\nexport API_KEY_SECRET=\"endpoint-proxy-api-key-secret\"\n\nnpm run start\n# Or: pm2 start npm --name omniroute -- start\n```\n\n### PM2 Deployment (Low Memory)\n\nFor servers with limited RAM, use the memory limit option:\n\n```bash\n# With 512MB limit (default)\npm2 start npm --name omniroute -- start\n\n# Or with custom memory limit\nOMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start\n\n# Or using ecosystem.config.js\npm2 start ecosystem.config.js\n```\n\nCreate `ecosystem.config.js`:\n\n```javascript\nmodule.exports = {\n apps: [\n {\n name: \"omniroute\",\n script: \"npm\",\n args: \"start\",\n env: {\n NODE_ENV: \"production\",\n OMNIROUTE_MEMORY_MB: \"512\",\n JWT_SECRET: \"your-secret\",\n INITIAL_PASSWORD: \"your-password\",\n },\n node_args: \"--max-old-space-size=512\",\n max_memory_restart: \"300M\",\n },\n ],\n};\n```\n\n### Docker\n\n```bash\n# Build image (default = runner-cli with codex/claude/droid preinstalled)\ndocker build -t omniroute:cli .\n\n# Portable mode (recommended)\ndocker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli\n```\n\nFor host-integrated mode with CLI binaries, see the Docker section in the main docs.\n\n### Void Linux (xbps-src)\n\nVoid 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.\n\n
\nView xbps-src template\n\n```bash\n# Template file for 'omniroute'\npkgname=omniroute\nversion=3.2.4\nrevision=1\nhostmakedepends=\"nodejs python3 make\"\ndepends=\"openssl\"\nshort_desc=\"Universal AI gateway with smart routing for multiple LLM providers\"\nmaintainer=\"zenobit \"\nlicense=\"MIT\"\nhomepage=\"https://github.com/diegosouzapw/OmniRoute\"\ndistfiles=\"https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz\"\nchecksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b\nsystem_accounts=\"_omniroute\"\nomniroute_homedir=\"/var/lib/omniroute\"\nexport NODE_ENV=production\nexport npm_config_engine_strict=false\nexport npm_config_loglevel=error\nexport npm_config_fund=false\nexport npm_config_audit=false\n\ndo_build() {\n\t# Determine target CPU arch for node-gyp\n\tlocal _gyp_arch\n\tcase \"$XBPS_TARGET_MACHINE\" in\n\t\taarch64*) _gyp_arch=arm64 ;;\n\t\tarmv7*|armv6*) _gyp_arch=arm ;;\n\t\ti686*) _gyp_arch=ia32 ;;\n\t\t*) _gyp_arch=x64 ;;\n\tesac\n\n\t# 1) Install all deps โ€“ skip scripts\n\tNODE_ENV=development npm ci --ignore-scripts\n\n\t# 2) Build the Next.js standalone bundle\n\tnpm run build\n\n\t# 3) Copy static assets into standalone\n\tcp -r .next/static .next/standalone/.next/static\n\t[ -d public ] && cp -r public .next/standalone/public || true\n\n\t# 4) Compile better-sqlite3 native binding\n\tlocal _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\n\t(cd node_modules/better-sqlite3 && node \"$_node_gyp\" rebuild --arch=\"$_gyp_arch\")\n\n\t# 5) Place the compiled binding into the standalone bundle\n\tlocal _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release\n\tmkdir -p \"$_bs3_release\"\n\tcp node_modules/better-sqlite3/build/Release/better_sqlite3.node \"$_bs3_release/\"\n\n\t# 6) Remove arch-specific sharp bundles\n\trm -rf .next/standalone/node_modules/@img\n\n\t# 7) Copy pino runtime deps omitted by Next.js static analysis:\n\tfor _mod in pino-abstract-transport split2 process-warning; do\n\t\tcp -r \"node_modules/$_mod\" .next/standalone/node_modules/\n\tdone\n}\n\ndo_check() {\n\tnpm run test:unit\n}\n\ndo_install() {\n\tvmkdir usr/lib/omniroute/.next\n\tvcopy .next/standalone/. usr/lib/omniroute/.next/standalone\n\n\t# Prevent removal of empty Next.js app router dirs by the post-install hook\n\tfor _d in \\\n\t\t.next/standalone/.next/server/app/dashboard \\\n\t\t.next/standalone/.next/server/app/dashboard/settings \\\n\t\t.next/standalone/.next/server/app/dashboard/providers; do\n\t\ttouch \"${DESTDIR}/usr/lib/omniroute/${_d}/.keep\"\n\tdone\n\n\tcat > \"${WRKDIR}/omniroute\" <<'EOF'\n#!/bin/sh\nexport PORT=\"${PORT:-20128}\"\nexport DATA_DIR=\"${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}\"\nexport APP_LOG_TO_FILE=\"${APP_LOG_TO_FILE:-false}\"\nmkdir -p \"${DATA_DIR}\"\nexec node /usr/lib/omniroute/.next/standalone/server.js \"$@\"\nEOF\n\tvbin \"${WRKDIR}/omniroute\"\n}\n\npost_install() {\n\tvlicense LICENSE\n}\n```\n\n
\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |\n| `INITIAL_PASSWORD` | `123456` | First login password |\n| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |\n| `PORT` | framework default | Service port (`20128` in examples) |\n| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |\n| `NODE_ENV` | runtime default | Set `production` for deploy |\n| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |\n| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |\n| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |\n| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |\n| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand |\n| `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Server-side refresh cadence for cached Provider Limits data; UI refresh buttons still trigger manual sync |\n| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work |\n| `APP_LOG_TO_FILE` | `true` | Enables application and audit log output to disk |\n| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |\n| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download |\n| `CLOUDFLARED_PROTOCOL` | `http2` | Transport for managed Quick Tunnels (`http2`, `quic`, or `auto`) |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB |\n| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries |\n| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries |\n\nFor the full environment variable reference, see the [README](../README.md).\n\n---\n\n## ๐Ÿ“Š Available Models\n\n
\nView all available models\n\n**Claude Code (`cc/`)** โ€” Pro/Max: `cc/claude-opus-4-7`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`\n\n**Codex (`cx/`)** โ€” Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`\n\n**Gemini CLI (`gc/`)** โ€” FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`\n\n**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`\n\n**GLM (`glm/`)** โ€” $0.6/1M: `glm/glm-4.7`\n\n**MiniMax (`minimax/`)** โ€” $0.2/1M: `minimax/MiniMax-M2.1`\n\n**Qoder (`if/`)** โ€” FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`\n\n**Qwen (`qw/`)** โ€” FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`\n\n**Kiro (`kr/`)** โ€” FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`\n\n**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`\n\n**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`\n\n**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`\n\n**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`\n\n**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`\n\n**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`\n\n**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`\n\n**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`\n\n**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`\n\n**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`\n\n
\n\n---\n\n## ๐Ÿงฉ Advanced Features\n\n### Custom Models\n\nAdd any model ID to any provider without waiting for an app update:\n\n```bash\n# Via API\ncurl -X POST http://localhost:20128/api/provider-models \\\n -H \"Content-Type: application/json\" \\\n -d '{\"provider\": \"openai\", \"modelId\": \"gpt-4.5-preview\", \"modelName\": \"GPT-4.5 Preview\"}'\n\n# List: curl http://localhost:20128/api/provider-models?provider=openai\n# Remove: curl -X DELETE \"http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview\"\n```\n\nOr use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**.\n\nNotes:\n\n- 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.\n- The **Custom Models** section is intended for providers that do not expose managed available-model imports.\n\n### Dedicated Provider Routes\n\nRoute requests directly to a specific provider with model validation:\n\n```bash\nPOST http://localhost:20128/v1/providers/openai/chat/completions\nPOST http://localhost:20128/v1/providers/openai/embeddings\nPOST http://localhost:20128/v1/providers/fireworks/images/generations\n```\n\nThe provider prefix is auto-added if missing. Mismatched models return `400`.\n\n### Network Proxy Configuration\n\n```bash\n# Set global proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"global\": {\"type\":\"http\",\"host\":\"proxy.example.com\",\"port\":\"8080\"}}'\n\n# Per-provider proxy\ncurl -X PUT http://localhost:20128/api/settings/proxy \\\n -d '{\"providers\": {\"openai\": {\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}}'\n\n# Test proxy\ncurl -X POST http://localhost:20128/api/settings/proxy/test \\\n -d '{\"proxy\":{\"type\":\"socks5\",\"host\":\"proxy.example.com\",\"port\":\"1080\"}}'\n```\n\n**Precedence:** Key-specific โ†’ Combo-specific โ†’ Provider-specific โ†’ Global โ†’ Environment.\n\n### Model Catalog API\n\n```bash\ncurl http://localhost:20128/api/models/catalog\n```\n\nReturns models grouped by provider with types (`chat`, `embedding`, `image`).\n\n### Cloud Sync\n\n- Sync providers, combos, and settings across devices\n- Automatic background sync with timeout + fail-fast\n- Prefer server-side `BASE_URL`/`CLOUD_URL` in production\n\n### Cloudflare Quick Tunnel\n\n- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments\n- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint\n- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary\n- Quick Tunnels are not auto-restored after an OmniRoute or container restart; re-enable them from the dashboard when needed\n- Tunnel URLs are ephemeral and change every time you stop/start the tunnel\n- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained containers\n- Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want to override the managed transport choice\n- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download\n\n### LLM Gateway Intelligence (Phase 9)\n\n- **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)\n- **Request Idempotency** โ€” Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header\n- **Progress Tracking** โ€” Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header\n\n---\n\n### Translator Playground\n\nAccess via **Dashboard โ†’ Translator**. Debug and visualize how OmniRoute translates API requests between providers.\n\n| Mode | Purpose |\n| ---------------- | -------------------------------------------------------------------------------------- |\n| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |\n| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |\n| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |\n| **Live Monitor** | Watch real-time translations as requests flow through the proxy |\n\n**Use cases:**\n\n- Debug why a specific client/provider combination fails\n- Verify that thinking tags, tool calls, and system prompts translate correctly\n- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats\n\n---\n\n### Routing Strategies\n\nConfigure via **Dashboard โ†’ Settings โ†’ Routing**.\n\n| Strategy | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------ |\n| **Fill First** | Uses accounts in priority order โ€” primary account handles all requests until unavailable |\n| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |\n| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one โ€” balances load with awareness of health |\n| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |\n| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |\n| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |\n\n#### External Sticky Session Header\n\nFor external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send:\n\n```http\nX-Session-Id: your-session-key\n```\n\nOmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`.\n\nIf you use Nginx and send underscore-form headers, enable:\n\n```nginx\nunderscores_in_headers on;\n```\n\n#### Wildcard Model Aliases\n\nCreate wildcard patterns to remap model names:\n\n```\nPattern: claude-sonnet-* โ†’ Target: cc/claude-sonnet-4-5-20250929\nPattern: gpt-* โ†’ Target: gh/gpt-5.1-codex\n```\n\nWildcards support `*` (any characters) and `?` (single character).\n\n#### Fallback Chains\n\nDefine global fallback chains that apply across all requests:\n\n```\nChain: production-fallback\n 1. cc/claude-opus-4-7\n 2. gh/gpt-5.1-codex\n 3. glm/glm-4.7\n```\n\n---\n\n### Resilience & Circuit Breakers\n\nConfigure via **Dashboard โ†’ Settings โ†’ Resilience**.\n\nOmniRoute implements provider-level resilience with five components:\n\n1. **Request Queue & Pacing** โ€” System-level request shaping:\n - **Requests Per Minute (RPM)** โ€” Maximum requests per minute per account\n - **Min Time Between Requests** โ€” Minimum gap in milliseconds between requests\n - **Max Concurrent Requests** โ€” Maximum simultaneous requests per account\n\n2. **Connection Cooldown** โ€” Per-auth-type configuration for a single connection after retryable failures:\n - **Base Cooldown** โ€” Default cooldown window for retryable upstream failures\n - **Use Upstream Retry Hints** โ€” Honors authoritative `Retry-After` or reset hints when provided\n - **Max Backoff Steps** โ€” Maximum exponential backoff level for repeated failures\n\n3. **Provider Circuit Breaker** โ€” Tracks end-to-end provider failures and automatically opens the breaker when the configured threshold is reached:\n - **Failure Threshold** โ€” Consecutive provider failures before opening the breaker\n - **Reset Timeout** โ€” Time window before the provider is tested again\n - **CLOSED** (Healthy) โ€” Requests flow normally\n - **OPEN** โ€” Provider is temporarily blocked after repeated failures\n - **HALF_OPEN** โ€” Testing if provider has recovered\n\n Connection-scoped `429` rate limits stay in **Connection Cooldown** and do not count toward the provider breaker.\n\n The provider breaker runtime state is shown on **Dashboard โ†’ Health** only.\n\n4. **Wait For Cooldown** โ€” If every candidate connection is already cooling down, OmniRoute can wait for the earliest cooldown and retry the same client request automatically.\n\n5. **Rate Limit Auto-Detection** โ€” When upstream providers return explicit wait windows, those hints override the local connection cooldown when the setting is enabled.\n\n**Pro Tip:** Use the **Health** page to inspect and reset live provider breakers after an outage. The Resilience page only changes configuration.\n\n---\n\n### Database Export / Import\n\nManage database backups in **Dashboard โ†’ Settings โ†’ System & Storage**.\n\n| Action | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |\n| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |\n| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created unless `DISABLE_SQLITE_AUTO_BACKUP=true` |\n\n```bash\n# API: Export database\ncurl -o backup.sqlite http://localhost:20128/api/db-backups/export\n\n# API: Export all (full archive)\ncurl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll\n\n# API: Import database\ncurl -X POST http://localhost:20128/api/db-backups/import \\\n -F \"file=@backup.sqlite\"\n```\n\n**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).\n\n**Use Cases:**\n\n- Migrate OmniRoute between machines\n- Create external backups for disaster recovery\n- Share configurations between team members (export all โ†’ share archive)\n\n---\n\n### Settings Dashboard\n\nThe settings page is organized into 6 tabs for easy navigation:\n\n| Tab | Contents |\n| -------------- | -------------------------------------------------------------------------------------------- |\n| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility |\n| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking |\n| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |\n| **Resilience** | Request queue, connection cooldown, provider breaker config, and wait-for-cooldown behavior |\n| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |\n| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |\n\n---\n\n### Costs & Budget Management\n\nAccess via **Dashboard โ†’ Costs**.\n\n| Tab | Purpose |\n| ----------- | ---------------------------------------------------------------------------------------- |\n| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |\n| **Pricing** | View and edit model pricing entries โ€” cost per 1K input/output tokens per provider |\n\n```bash\n# API: Set a budget\ncurl -X POST http://localhost:20128/api/usage/budget \\\n -H \"Content-Type: application/json\" \\\n -d '{\"keyId\": \"key-123\", \"limit\": 50.00, \"period\": \"monthly\"}'\n\n# API: Get current budget status\ncurl http://localhost:20128/api/usage/budget\n```\n\n**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.\n\n---\n\n### Audio Transcription\n\nOmniRoute supports audio transcription via the OpenAI-compatible endpoint:\n\n```bash\nPOST /v1/audio/transcriptions\nAuthorization: Bearer your-api-key\nContent-Type: multipart/form-data\n\n# Example with curl\ncurl -X POST http://localhost:20128/v1/audio/transcriptions \\\n -H \"Authorization: Bearer your-api-key\" \\\n -F \"file=@audio.mp3\" \\\n -F \"model=deepgram/nova-3\"\n```\n\nAvailable providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).\n\nSupported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.\n\n---\n\n### Combo Balancing Strategies\n\nConfigure per-combo balancing in **Dashboard โ†’ Combos โ†’ Create/Edit โ†’ Strategy**.\n\n| Strategy | Description |\n| ------------------ | ------------------------------------------------------------------------ |\n| **Round-Robin** | Rotates through models sequentially |\n| **Priority** | Always tries the first model; falls back only on error |\n| **Random** | Picks a random model from the combo for each request |\n| **Weighted** | Routes proportionally based on assigned weights per model |\n| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |\n| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |\n\nGlobal combo defaults can be set in **Dashboard โ†’ Settings โ†’ Routing โ†’ Combo Defaults**.\n\n---\n\n### Health Dashboard\n\nAccess via **Dashboard โ†’ Health**. Real-time system health overview with 6 cards:\n\n| Card | What It Shows |\n| --------------------- | ----------------------------------------------------------- |\n| **System Status** | Uptime, version, memory usage, data directory |\n| **Provider Health** | Global provider circuit breaker runtime state |\n| **Rate Limits** | Active connection cooldowns per account with remaining time |\n| **Active Lockouts** | Active model-scoped lockouts and temporary exclusions |\n| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |\n| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |\n\n**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.\n\n---\n\n## ๐Ÿ–ฅ๏ธ Desktop Application (Electron)\n\nOmniRoute is available as a native desktop application for Windows, macOS, and Linux.\n\n### ื”ืชืงื ื”\n\n```bash\n# From the electron directory:\ncd electron\nnpm install\n\n# Development mode (connect to running Next.js dev server):\nnpm run dev\n\n# Production mode (uses standalone build):\nnpm start\n```\n\n### Building Installers\n\n```bash\ncd electron\nnpm run build # Current platform\nnpm run build:win # Windows (.exe NSIS)\nnpm run build:mac # macOS (.dmg universal)\nnpm run build:linux # Linux (.AppImage)\n```\n\nOutput โ†’ `electron/dist-electron/`\n\n### Key Features\n\n| Feature | Description |\n| --------------------------- | ---------------------------------------------------- |\n| **Server Readiness** | Polls server before showing window (no blank screen) |\n| **System Tray** | Minimize to tray, change port, quit from tray menu |\n| **Port Management** | Change server port from tray (auto-restarts server) |\n| **Content Security Policy** | Restrictive CSP via session headers |\n| **Single Instance** | Only one app instance can run at a time |\n| **Offline Mode** | Bundled Next.js server works without internet |\n\n### Environment Variables\n\n| Variable | Default | Description |\n| --------------------- | ------- | -------------------------------- |\n| `OMNIROUTE_PORT` | `20128` | Server port |\n| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64โ€“16384 MB) |\n\n๐Ÿ“– Full documentation: [`electron/README.md`](../electron/README.md)\n"}}, "docs/i18n/no/docs/reference/CLI-TOOLS.md": {"df4fa8e65b6d5e5876dcecd5a0eec84928b2be31": {"t": 1785747209.9274452, "n": 13216, "h": "2c6b46e0ca45ef6d", "c": "# CLI Tools Setup Guide โ€” OmniRoute (Norsk)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../../bn/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../../fa/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../../gu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../../hi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../../mr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../../sw/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../../ta/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../../te/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../../tr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../../ur/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md)\n\n---\n\nThis guide explains how to install and configure all supported AI coding CLI tools\nto use **OmniRoute** as the unified backend, giving you centralized key management,\ncost tracking, model switching, and request logging across every tool.\n\n---\n\n## How It Works\n\n```\nClaude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot\n โ”‚\n โ–ผ (all point to OmniRoute)\n http://YOUR_SERVER:20128/v1\n โ”‚\n โ–ผ (OmniRoute routes to the right provider)\n Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ...\n```\n\n**Benefits:**\n\n- One API key to manage all tools\n- Cost tracking across all CLIs in the dashboard\n- Model switching without reconfiguring every tool\n- Works locally and on remote servers (VPS)\n\n---\n\n## Supported Tools (Dashboard Source of Truth)\n\nThe dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`.\nCurrent list (v3.0.0-rc.16):\n\n| Tool | ID | Command | Setup Mode | Install Method |\n| ------------------ | ------------- | ---------- | ---------- | -------------- |\n| **Claude Code** | `claude` | `claude` | env | npm |\n| **OpenAI Codex** | `codex` | `codex` | custom | npm |\n| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI |\n| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI |\n| **Cursor** | `cursor` | app | guide | desktop app |\n| **Cline** | `cline` | `cline` | custom | npm |\n| **Kilo Code** | `kilo` | `kilocode` | custom | npm |\n| **Continue** | `continue` | extension | guide | VS Code |\n| **Antigravity** | `antigravity` | internal | mitm | OmniRoute |\n| **GitHub Copilot** | `copilot` | extension | custom | VS Code |\n| **OpenCode** | `opencode` | `opencode` | guide | npm |\n| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI |\n| **Qwen Code** | `qwen` | `qwen` | custom | npm |\n\n### CLI fingerprint sync (Agents + Settings)\n\n`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`.\nThis keeps provider IDs aligned with CLI cards and legacy IDs.\n\n| CLI ID | Fingerprint Provider ID |\n| ---------------------------------------------------------------------------------------------------- | ----------------------- |\n| `kilo` | `kilocode` |\n| `copilot` | `github` |\n| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID |\n\nLegacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`.\n\n---\n\n## Step 1 โ€” Get an OmniRoute API Key\n\n1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`)\n2. Click **Create API Key**\n3. Give it a name (e.g. `cli-tools`) and select all permissions\n4. Copy the key โ€” you'll need it for every CLI below\n\n> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx`\n\n---\n\n## Step 2 โ€” Install CLI Tools\n\nAll npm-based tools require Node.js 18+:\n\n```bash\n# Claude Code (Anthropic)\nnpm install -g @anthropic-ai/claude-code\n\n# OpenAI Codex\nnpm install -g @openai/codex\n\n# OpenCode\nnpm install -g opencode-ai\n\n# Cline\nnpm install -g cline\n\n# KiloCode\nnpm install -g kilocode\n\n# Kiro CLI (Amazon โ€” requires curl + unzip)\napt-get install -y unzip # on Debian/Ubuntu\ncurl -fsSL https://cli.kiro.dev/install | bash\nexport PATH=\"$HOME/.local/bin:$PATH\" # add to ~/.bashrc\n```\n\n**Verify:**\n\n```bash\nclaude --version # 2.x.x\ncodex --version # 0.x.x\nopencode --version # x.x.x\ncline --version # 2.x.x\nkilocode --version # x.x.x (or: kilo --version)\nkiro-cli --version # 1.x.x\n```\n\n---\n\n## Step 3 โ€” Set Global Environment Variables\n\nAdd to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`:\n\n```bash\n# OmniRoute Universal Endpoint\nexport OPENAI_BASE_URL=\"http://localhost:20128/v1\"\nexport OPENAI_API_KEY=\"sk-your-omniroute-key\"\nexport ANTHROPIC_BASE_URL=\"http://localhost:20128/v1\"\nexport ANTHROPIC_API_KEY=\"sk-your-omniroute-key\"\nexport GEMINI_BASE_URL=\"http://localhost:20128/v1\"\nexport GEMINI_API_KEY=\"sk-your-omniroute-key\"\n```\n\n> For a **remote server** replace `localhost:20128` with the server IP or domain,\n> e.g. `http://192.168.0.15:20128`.\n\n---\n\n## Step 4 โ€” Configure Each Tool\n\n### Claude Code\n\n```bash\n# Via CLI:\nclaude config set --global api-base-url http://localhost:20128/v1\n\n# Or create ~/.claude/settings.json:\nmkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF\n{\n \"apiBaseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"sk-your-omniroute-key\"\n}\nEOF\n```\n\n**Test:** `claude \"say hello\"`\n\n---\n\n### OpenAI Codex\n\n```bash\nmkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF\nmodel: auto\napiKey: sk-your-omniroute-key\napiBaseUrl: http://localhost:20128/v1\nEOF\n```\n\n**Test:** `codex \"what is 2+2?\"`\n\n---\n\n### OpenCode\n\n```bash\nmkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF\n[provider.openai]\nbase_url = \"http://localhost:20128/v1\"\napi_key = \"sk-your-omniroute-key\"\nEOF\n```\n\n**Test:** `opencode`\n\n---\n\n### Cline (CLI or VS Code)\n\n**CLI mode:**\n\n```bash\nmkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF\n{\n \"apiProvider\": \"openai\",\n \"openAiBaseUrl\": \"http://localhost:20128/v1\",\n \"openAiApiKey\": \"sk-your-omniroute-key\"\n}\nEOF\n```\n\n**VS Code mode:**\nCline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1`\n\nOr use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**.\n\n---\n\n### KiloCode (CLI or VS Code)\n\n**CLI mode:**\n\n```bash\nkilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key\n```\n\n**VS Code settings:**\n\n```json\n{\n \"kilo-code.openAiBaseUrl\": \"http://localhost:20128/v1\",\n \"kilo-code.apiKey\": \"sk-your-omniroute-key\"\n}\n```\n\nOr use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**.\n\n---\n\n### Continue (VS Code Extension)\n\nEdit `~/.continue/config.yaml`:\n\n```yaml\nmodels:\n - name: OmniRoute\n provider: openai\n model: auto\n apiBase: http://localhost:20128/v1\n apiKey: sk-your-omniroute-key\n default: true\n```\n\nRestart VS Code after editing.\n\n---\n\n### Kiro CLI (Amazon)\n\n```bash\n# Login to your AWS/Kiro account:\nkiro-cli login\n\n# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself.\n# Use kiro-cli alongside OmniRoute for other tools.\nkiro-cli status\n```\n\n---\n\n### Qwen Code (Alibaba)\n\nQwen Code supports OpenAI-compatible API endpoints via environment variables or `settings.json`.\n\n**Option 1: Environment variables (`~/.qwen/.env`)**\n\n```bash\nmkdir -p ~/.qwen && cat > ~/.qwen/.env << EOF\nOPENAI_API_KEY=\"sk-your-omniroute-key\"\nOPENAI_BASE_URL=\"http://localhost:20128/v1\"\nOPENAI_MODEL=\"auto\"\nEOF\n```\n\n**Option 2: `settings.json` with model providers**\n\n```json\n// ~/.qwen/settings.json\n{\n \"env\": {\n \"OPENAI_API_KEY\": \"sk-your-omniroute-key\",\n \"OPENAI_BASE_URL\": \"http://localhost:20128/v1\"\n },\n \"modelProviders\": {\n \"openai\": [\n {\n \"id\": \"omniroute-default\",\n \"name\": \"OmniRoute (Auto)\",\n \"envKey\": \"OPENAI_API_KEY\",\n \"baseUrl\": \"http://localhost:20128/v1\"\n }\n ]\n }\n}\n```\n\n**Option 3: Inline CLI flags**\n\n```bash\nOPENAI_BASE_URL=\"http://localhost:20128/v1\" \\\nOPENAI_API_KEY=\"sk-your-omniroute-key\" \\\nOPENAI_MODEL=\"auto\" \\\nqwen\n```\n\n> For a **remote server** replace `localhost:20128` with the server IP or domain.\n\n**Test:** `qwen \"say hello\"`\n\n### Cursor (Desktop App)\n\n> **Note:** Cursor routes requests through its cloud. For OmniRoute integration,\n> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL.\n\nVia GUI: **Settings โ†’ Models โ†’ OpenAI API Key**\n\n- Base URL: `https://your-domain.com/v1`\n- API Key: your OmniRoute key\n\n---\n\n## Dashboard Auto-Configuration\n\nThe OmniRoute dashboard automates configuration for most tools:\n\n1. Go to `http://localhost:20128/dashboard/cli-tools`\n2. Expand any tool card\n3. Select your API key from the dropdown\n4. Click **Apply Config** (if tool is detected as installed)\n5. Or copy the generated config snippet manually\n\n---\n\n## Built-in Agents: Droid & OpenClaw\n\n**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed.\nThey run as internal routes and use OmniRoute's model routing automatically.\n\n- Access: `http://localhost:20128/dashboard/agents`\n- Configure: same combos and providers as all other tools\n- No API key or CLI install required\n\n---\n\n## Available API Endpoints\n\n| Endpoint | Description | Use For |\n| -------------------------- | ----------------------------- | --------------------------- |\n| `/v1/chat/completions` | Standard chat (all providers) | All modern tools |\n| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows |\n| `/v1/completions` | Legacy text completions | Older tools using `prompt:` |\n| `/v1/embeddings` | Text embeddings | RAG, search |\n| `/v1/images/generations` | Image generation | GPT-Image, Flux, etc. |\n| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS |\n| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI |\n\n---\n\n## Feilsรธking\n\n| Error | Cause | Fix |\n| ------------------------- | ----------------------- | ------------------------------------------ |\n| `Connection refused` | OmniRoute not running | `pm2 start omniroute` |\n| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` |\n| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` |\n| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` |\n| CLI shows \"not installed\" | Binary not in PATH | Check `which ` |\n| `kiro-cli: not found` | Not in PATH | `export PATH=\"$HOME/.local/bin:$PATH\"` |\n\n---\n\n## Quick Setup Script (One Command)\n\n```bash\n# Install all CLIs and configure for OmniRoute (replace with your key and server URL)\nOMNIROUTE_URL=\"http://localhost:20128/v1\"\nOMNIROUTE_KEY=\"sk-your-omniroute-key\"\n\nnpm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode @qwen-code/qwen-code\n\n# Kiro CLI\napt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash\n\n# Write configs\nmkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue\n\ncat > ~/.claude/settings.json <<< \"{\\\"apiBaseUrl\\\":\\\"$OMNIROUTE_URL\\\",\\\"apiKey\\\":\\\"$OMNIROUTE_KEY\\\"}\"\ncat > ~/.codex/config.yaml <<< \"model: auto\\napiKey: $OMNIROUTE_KEY\\napiBaseUrl: $OMNIROUTE_URL\"\ncat >> ~/.bashrc << EOF\nexport OPENAI_BASE_URL=\"$OMNIROUTE_URL\"\nexport OPENAI_API_KEY=\"$OMNIROUTE_KEY\"\nexport ANTHROPIC_BASE_URL=\"$OMNIROUTE_URL\"\nexport ANTHROPIC_API_KEY=\"$OMNIROUTE_KEY\"\nEOF\n\nsource ~/.bashrc\necho \"โœ… All CLIs installed and configured for OmniRoute\"\n```\n"}, "8a1d9beb55fe825bd132c8696117046258869a79": {"t": 1785764410.947035, "n": 13216, "h": "2c6b46e0ca45ef6d", "c": "# CLI Tools Setup Guide โ€” OmniRoute (Norsk)\n\n๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฉ [bn](../../bn/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ท [fa](../../fa/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [gu](../../gu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [hi](../../hi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [mr](../../mr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ช [sw](../../sw/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [ta](../../ta/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [te](../../te/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ท [tr](../../tr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฐ [ur](../../ur/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md)\n\n---\n\nThis guide explains how to install and configure all supported AI coding CLI tools\nto use **OmniRoute** as the unified backend, giving you centralized key management,\ncost tracking, model switching, and request logging across every tool.\n\n---\n\n## How It Works\n\n```\nClaude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot\n โ”‚\n โ–ผ (all point to OmniRoute)\n http://YOUR_SERVER:20128/v1\n โ”‚\n โ–ผ (OmniRoute routes to the right provider)\n Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ...\n```\n\n**Benefits:**\n\n- One API key to manage all tools\n- Cost tracking across all CLIs in the dashboard\n- Model switching without reconfiguring every tool\n- Works locally and on remote servers (VPS)\n\n---\n\n## Supported Tools (Dashboard Source of Truth)\n\nThe dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`.\nCurrent list (v3.0.0-rc.16):\n\n| Tool | ID | Command | Setup Mode | Install Method |\n| ------------------ | ------------- | ---------- | ---------- | -------------- |\n| **Claude Code** | `claude` | `claude` | env | npm |\n| **OpenAI Codex** | `codex` | `codex` | custom | npm |\n| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI |\n| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI |\n| **Cursor** | `cursor` | app | guide | desktop app |\n| **Cline** | `cline` | `cline` | custom | npm |\n| **Kilo Code** | `kilo` | `kilocode` | custom | npm |\n| **Continue** | `continue` | extension | guide | VS Code |\n| **Antigravity** | `antigravity` | internal | mitm | OmniRoute |\n| **GitHub Copilot** | `copilot` | extension | custom | VS Code |\n| **OpenCode** | `opencode` | `opencode` | guide | npm |\n| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI |\n| **Qwen Code** | `qwen` | `qwen` | custom | npm |\n\n### CLI fingerprint sync (Agents + Settings)\n\n`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`.\nThis keeps provider IDs aligned with CLI cards and legacy IDs.\n\n| CLI ID | Fingerprint Provider ID |\n| ---------------------------------------------------------------------------------------------------- | ----------------------- |\n| `kilo` | `kilocode` |\n| `copilot` | `github` |\n| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID |\n\nLegacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`.\n\n---\n\n## Step 1 โ€” Get an OmniRoute API Key\n\n1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`)\n2. Click **Create API Key**\n3. Give it a name (e.g. `cli-tools`) and select all permissions\n4. Copy the key โ€” you'll need it for every CLI below\n\n> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx`\n\n---\n\n## Step 2 โ€” Install CLI Tools\n\nAll npm-based tools require Node.js 18+:\n\n```bash\n# Claude Code (Anthropic)\nnpm install -g @anthropic-ai/claude-code\n\n# OpenAI Codex\nnpm install -g @openai/codex\n\n# OpenCode\nnpm install -g opencode-ai\n\n# Cline\nnpm install -g cline\n\n# KiloCode\nnpm install -g kilocode\n\n# Kiro CLI (Amazon โ€” requires curl + unzip)\napt-get install -y unzip # on Debian/Ubuntu\ncurl -fsSL https://cli.kiro.dev/install | bash\nexport PATH=\"$HOME/.local/bin:$PATH\" # add to ~/.bashrc\n```\n\n**Verify:**\n\n```bash\nclaude --version # 2.x.x\ncodex --version # 0.x.x\nopencode --version # x.x.x\ncline --version # 2.x.x\nkilocode --version # x.x.x (or: kilo --version)\nkiro-cli --version # 1.x.x\n```\n\n---\n\n## Step 3 โ€” Set Global Environment Variables\n\nAdd to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`:\n\n```bash\n# OmniRoute Universal Endpoint\nexport OPENAI_BASE_URL=\"http://localhost:20128/v1\"\nexport OPENAI_API_KEY=\"sk-your-omniroute-key\"\nexport ANTHROPIC_BASE_URL=\"http://localhost:20128/v1\"\nexport ANTHROPIC_API_KEY=\"sk-your-omniroute-key\"\nexport GEMINI_BASE_URL=\"http://localhost:20128/v1\"\nexport GEMINI_API_KEY=\"sk-your-omniroute-key\"\n```\n\n> For a **remote server** replace `localhost:20128` with the server IP or domain,\n> e.g. `http://192.168.0.15:20128`.\n\n---\n\n## Step 4 โ€” Configure Each Tool\n\n### Claude Code\n\n```bash\n# Via CLI:\nclaude config set --global api-base-url http://localhost:20128/v1\n\n# Or create ~/.claude/settings.json:\nmkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF\n{\n \"apiBaseUrl\": \"http://localhost:20128/v1\",\n \"apiKey\": \"sk-your-omniroute-key\"\n}\nEOF\n```\n\n**Test:** `claude \"say hello\"`\n\n---\n\n### OpenAI Codex\n\n```bash\nmkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF\nmodel: auto\napiKey: sk-your-omniroute-key\napiBaseUrl: http://localhost:20128/v1\nEOF\n```\n\n**Test:** `codex \"what is 2+2?\"`\n\n---\n\n### OpenCode\n\n```bash\nmkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF\n[provider.openai]\nbase_url = \"http://localhost:20128/v1\"\napi_key = \"sk-your-omniroute-key\"\nEOF\n```\n\n**Test:** `opencode`\n\n---\n\n### Cline (CLI or VS Code)\n\n**CLI mode:**\n\n```bash\nmkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF\n{\n \"apiProvider\": \"openai\",\n \"openAiBaseUrl\": \"http://localhost:20128/v1\",\n \"openAiApiKey\": \"sk-your-omniroute-key\"\n}\nEOF\n```\n\n**VS Code mode:**\nCline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1`\n\nOr use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**.\n\n---\n\n### KiloCode (CLI or VS Code)\n\n**CLI mode:**\n\n```bash\nkilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key\n```\n\n**VS Code settings:**\n\n```json\n{\n \"kilo-code.openAiBaseUrl\": \"http://localhost:20128/v1\",\n \"kilo-code.apiKey\": \"sk-your-omniroute-key\"\n}\n```\n\nOr use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**.\n\n---\n\n### Continue (VS Code Extension)\n\nEdit `~/.continue/config.yaml`:\n\n```yaml\nmodels:\n - name: OmniRoute\n provider: openai\n model: auto\n apiBase: http://localhost:20128/v1\n apiKey: sk-your-omniroute-key\n default: true\n```\n\nRestart VS Code after editing.\n\n---\n\n### Kiro CLI (Amazon)\n\n```bash\n# Login to your AWS/Kiro account:\nkiro-cli login\n\n# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself.\n# Use kiro-cli alongside OmniRoute for other tools.\nkiro-cli status\n```\n\n---\n\n### Qwen Code (Alibaba)\n\nQwen Code supports OpenAI-compatible API endpoints via environment variables or `settings.json`.\n\n**Option 1: Environment variables (`~/.qwen/.env`)**\n\n```bash\nmkdir -p ~/.qwen && cat > ~/.qwen/.env << EOF\nOPENAI_API_KEY=\"sk-your-omniroute-key\"\nOPENAI_BASE_URL=\"http://localhost:20128/v1\"\nOPENAI_MODEL=\"auto\"\nEOF\n```\n\n**Option 2: `settings.json` with model providers**\n\n```json\n// ~/.qwen/settings.json\n{\n \"env\": {\n \"OPENAI_API_KEY\": \"sk-your-omniroute-key\",\n \"OPENAI_BASE_URL\": \"http://localhost:20128/v1\"\n },\n \"modelProviders\": {\n \"openai\": [\n {\n \"id\": \"omniroute-default\",\n \"name\": \"OmniRoute (Auto)\",\n \"envKey\": \"OPENAI_API_KEY\",\n \"baseUrl\": \"http://localhost:20128/v1\"\n }\n ]\n }\n}\n```\n\n**Option 3: Inline CLI flags**\n\n```bash\nOPENAI_BASE_URL=\"http://localhost:20128/v1\" \\\nOPENAI_API_KEY=\"sk-your-omniroute-key\" \\\nOPENAI_MODEL=\"auto\" \\\nqwen\n```\n\n> For a **remote server** replace `localhost:20128` with the server IP or domain.\n\n**Test:** `qwen \"say hello\"`\n\n### Cursor (Desktop App)\n\n> **Note:** Cursor routes requests through its cloud. For OmniRoute integration,\n> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL.\n\nVia GUI: **Settings โ†’ Models โ†’ OpenAI API Key**\n\n- Base URL: `https://your-domain.com/v1`\n- API Key: your OmniRoute key\n\n---\n\n## Dashboard Auto-Configuration\n\nThe OmniRoute dashboard automates configuration for most tools:\n\n1. Go to `http://localhost:20128/dashboard/cli-tools`\n2. Expand any tool card\n3. Select your API key from the dropdown\n4. Click **Apply Config** (if tool is detected as installed)\n5. Or copy the generated config snippet manually\n\n---\n\n## Built-in Agents: Droid & OpenClaw\n\n**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed.\nThey run as internal routes and use OmniRoute's model routing automatically.\n\n- Access: `http://localhost:20128/dashboard/agents`\n- Configure: same combos and providers as all other tools\n- No API key or CLI install required\n\n---\n\n## Available API Endpoints\n\n| Endpoint | Description | Use For |\n| -------------------------- | ----------------------------- | --------------------------- |\n| `/v1/chat/completions` | Standard chat (all providers) | All modern tools |\n| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows |\n| `/v1/completions` | Legacy text completions | Older tools using `prompt:` |\n| `/v1/embeddings` | Text embeddings | RAG, search |\n| `/v1/images/generations` | Image generation | GPT-Image, Flux, etc. |\n| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS |\n| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI |\n\n---\n\n## Feilsรธking\n\n| Error | Cause | Fix |\n| ------------------------- | ----------------------- | ------------------------------------------ |\n| `Connection refused` | OmniRoute not running | `pm2 start omniroute` |\n| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` |\n| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` |\n| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` |\n| CLI shows \"not installed\" | Binary not in PATH | Check `which ` |\n| `kiro-cli: not found` | Not in PATH | `export PATH=\"$HOME/.local/bin:$PATH\"` |\n\n---\n\n## Quick Setup Script (One Command)\n\n```bash\n# Install all CLIs and configure for OmniRoute (replace with your key and server URL)\nOMNIROUTE_URL=\"http://localhost:20128/v1\"\nOMNIROUTE_KEY=\"sk-your-omniroute-key\"\n\nnpm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode @qwen-code/qwen-code\n\n# Kiro CLI\napt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash\n\n# Write configs\nmkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue\n\ncat > ~/.claude/settings.json <<< \"{\\\"apiBaseUrl\\\":\\\"$OMNIROUTE_URL\\\",\\\"apiKey\\\":\\\"$OMNIROUTE_KEY\\\"}\"\ncat > ~/.codex/config.yaml <<< \"model: auto\\napiKey: $OMNIROUTE_KEY\\napiBaseUrl: $OMNIROUTE_URL\"\ncat >> ~/.bashrc << EOF\nexport OPENAI_BASE_URL=\"$OMNIROUTE_URL\"\nexport OPENAI_API_KEY=\"$OMNIROUTE_KEY\"\nexport ANTHROPIC_BASE_URL=\"$OMNIROUTE_URL\"\nexport ANTHROPIC_API_KEY=\"$OMNIROUTE_KEY\"\nEOF\n\nsource ~/.bashrc\necho \"โœ… All CLIs installed and configured for OmniRoute\"\n```\n"}}}}