| --- |
| title: 9router (custom fork) |
| emoji: 🏃 |
| colorFrom: gray |
| colorTo: blue |
| sdk: docker |
| app_port: 7860 |
| pinned: false |
| --- |
| |
| > **🍴 Custom fork by clowntreffen** — based on [decolua/9router](https://github.com/decolua/9router) (MIT). |
| > Added: configurable stream stall timeout (per-provider + global), persistent data on HF bucket, port 7860 for HF Spaces. |
|
|
| ## 🚀 Deploy on Hugging Face Spaces |
|
|
| One-click deploy your own instance: |
|
|
| 1. **Fork this repo** → `https://huggingface.co/new-space` → SDK: **Docker** → connect your fork |
| 2. **Or push directly:** |
| ```bash |
| git clone https://github.com/clowntreffen/9router.git |
| cd 9router |
| git checkout feat/configurable-stall-timeout |
| |
| # Create space on HF, then: |
| git remote add hf hf-2api:spaces/YOUR_USER/SPACE_NAME.git |
| git push hf main |
| ``` |
|
|
| 3. **After deploy:** Open your Space → Dashboard → add providers + API keys |
| 4. **All data persists** on the HF Storage Bucket (`/data`) across rebuilds |
|
|
| > **⚠️ HF Space specifics:** |
| > - App runs on **port 7860** (HF mandatory, auto-configured) |
| > - Data stored at `/data/v2` on the HF Bucket — survives restarts |
| > - Container runs as **root** (no `su-exec`) — otherwise `SQLITE_READONLY` on the bucket |
| > - Set `STREAM_STALL_TIMEOUT_MS` env var or use Dashboard → Profile → Timeouts UI |
| > - Every provider has a per-provider **Stream Stall Timeout** override in its detail page |
|
|
| **Live demo:** [`https://2api-9router.hf.space`](https://2api-9router.hf.space) |
|
|
| --- |
|
|
| <div align="center"> |
| |
| # 9Router - FREE AI Router & Token Saver |
| |
| **Never stop coding. Save 20-40% tokens with RTK + auto-fallback to FREE & cheap AI models.** |
| |
| **Connect All AI Code Tools (Claude Code, Cursor, Antigravity, Copilot, Codex, Gemini, OpenCode, Cline, OpenClaw...) to 40+ AI Providers & 100+ Models.** |
| |
| [](https://www.npmjs.com/package/9router) |
| [](https://www.npmjs.com/package/9router) |
| [](https://hub.docker.com/r/decolua/9router) |
| [](https://github.com/decolua/9router/pkgs/container/9router) |
| [](https://github.com/decolua/9router/blob/main/LICENSE) |
|
|
| <a href="https://trendshift.io/repositories/22628" target="_blank"><img src="https://trendshift.io/api/badge/repositories/22628" alt="decolua%2F9router | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a> |
| |
| [🚀 Quick Start](#-quick-start) • [💡 Features](#-key-features) • [📖 Setup](#-setup-guide) • [🌐 Website](https://9router.com) |
|
|
| [🇻🇳 Tiếng Việt](./i18n/README.vi.md) • [🇨🇳 中文](./i18n/README.zh-CN.md) • [🇯🇵 日本語](./i18n/README.ja-JP.md) • [🇷🇺 Русский](./i18n/README.ru.md) |
| </div> |
|
|
| --- |
|
|
| ## 🤔 Why 9Router? |
|
|
| **Stop wasting money, tokens and hitting limits:** |
|
|
| - ❌ Subscription quota expires unused every month |
| - ❌ Rate limits stop you mid-coding |
| - ❌ Tool outputs (git diff, grep, ls...) burn tokens fast |
| - ❌ Expensive APIs ($20-50/month per provider) |
| - ❌ Manual switching between providers |
|
|
| **9Router solves this:** |
|
|
| - ✅ **RTK Token Saver** - Auto-compress tool_result content, save 20-40% tokens per request |
| - ✅ **Maximize subscriptions** - Track quota, use every bit before reset |
| - ✅ **Auto fallback** - Subscription → Cheap → Free, zero downtime |
| - ✅ **Multi-account** - Round-robin between accounts per provider |
| - ✅ **Universal** - Works with Claude Code, Codex, Cursor, Cline, any CLI tool |
| |
| --- |
| |
| ## 🔄 How It Works |
| |
| ``` |
| ┌─────────────┐ |
| │ Your CLI │ (Claude Code, Codex, OpenClaw, Cursor, Cline...) |
| │ Tool │ |
| └──────┬──────┘ |
| │ http://localhost:20128/v1 |
| ↓ |
| ┌─────────────────────────────────────────────┐ |
| │ 9Router (Smart Router) │ |
| │ • RTK Token Saver (cut tool_result tokens) │ |
| │ • Format translation (OpenAI ↔ Claude) │ |
| │ • Quota tracking │ |
| │ • Auto token refresh │ |
| └──────┬──────────────────────────────────────┘ |
| │ |
| ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, GitHub Copilot |
| │ ↓ quota exhausted |
| ├─→ [Tier 2: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M) |
| │ ↓ budget limit |
| └─→ [Tier 3: FREE] Kiro, OpenCode Free, Vertex ($300 credits) |
| |
| Result: Never stop coding, minimal cost + 20-40% token savings via RTK |
| ``` |
| |
| --- |
| |
| ## ⚡ Quick Start |
| |
| **1. Install globally:** |
| |
| ```bash |
| npm install -g 9router |
| 9router |
| ``` |
| |
| 🎉 Dashboard opens at `http://localhost:20128` |
| |
| **2. Connect a FREE provider (no signup needed):** |
| |
| Dashboard → Providers → Connect **Kiro AI** (free Claude unlimited) or **OpenCode Free** (no auth) → Done! |
| |
| **3. Use in your CLI tool:** |
| |
| ``` |
| Claude Code/Codex/OpenClaw/Cursor/Cline Settings: |
| Endpoint: http://localhost:20128/v1 |
| API Key: [copy from dashboard] |
| Model: kr/claude-sonnet-4.5 |
| ``` |
| |
| **That's it!** Start coding with FREE AI models. |
| |
| **Alternative: run from source (this repository):** |
| |
| This repository package is private (`9router-app`), so source/Docker execution is the expected local development path. |
| |
| ```bash |
| cp .env.example .env |
| npm install |
| PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev |
| ``` |
| |
| Production mode: |
| |
| ```bash |
| npm run build |
| PORT=20128 HOSTNAME=0.0.0.0 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run start |
| ``` |
| |
| Default URLs: |
| - Dashboard: `http://localhost:20128/dashboard` |
| - OpenAI-compatible API: `http://localhost:20128/v1` |
| |
| --- |
| |
| ## Video Guides |
| |
| <div align="center"> |
| |
| <table> |
| <tr> |
| <td align="center" width="320"> |
| <a href="https://www.youtube.com/watch?v=raEyZPg5xE0"> |
| <img src="https://img.youtube.com/vi/raEyZPg5xE0/maxresdefault.jpg" alt="9Router Setup Tutorial" width="300"/> |
| </a><br/> |
| <b>🇺🇸 English</b><br/> |
| <sub>9Router + Claude Code FREE Setup<br/>by <a href="https://www.youtube.com/@BuildAIWithHamid">Build AI With Hamid</a></sub> |
| </td> |
| <td align="center" width="320"> |
| <a href="https://www.youtube.com/watch?v=X69n5Lm06Yw"> |
| <img src="https://img.youtube.com/vi/X69n5Lm06Yw/maxresdefault.jpg" alt="Tiết kiệm chi phí LLM với 9Router" width="300"/> |
| </a><br/> |
| <b>🇻🇳 Tiếng Việt</b><br/> |
| <sub>Tiết kiệm chi phí LLM cho OpenClaw với 9Router<br/>by <a href="https://www.youtube.com/c/M%C3%ACAIblog">Mì AI</a></sub> |
| </td> |
| <td align="center" width="320"> |
| <a href="https://www.youtube.com/watch?v=o3qYCyjrFYg"> |
| <img src="https://img.youtube.com/vi/o3qYCyjrFYg/maxresdefault.jpg" alt="Claude Code FREE Forever" width="300"/> |
| </a><br/> |
| <b>🇺🇸 English</b><br/> |
| <sub>Claude Code FREE Forever — Unlimited Models<br/>by <a href="https://www.youtube.com/@BuildAIWithHamid">Build AI With Hamid</a></sub> |
| </td> |
| </tr> |
| <tr> |
| <td align="center" width="320"> |
| <a href="https://www.youtube.com/watch?v=Ttpc26m39Dw"> |
| <img src="https://img.youtube.com/vi/Ttpc26m39Dw/maxresdefault.jpg" alt="Claude CLI Free Setup" width="300"/> |
| </a><br/> |
| <b>🇺🇸 English</b><br/> |
| <sub>Claude CLI Free Setup with 9Router 🚀<br/>by <a href="https://www.youtube.com/@CodeVerseSoban">CodeVerse Soban</a></sub> |
| </td> |
| <td align="center" width="320"> |
| <a href="https://www.youtube.com/watch?v=G-5A_D5Pm6Y"> |
| <img src="https://img.youtube.com/vi/G-5A_D5Pm6Y/maxresdefault.jpg" alt="Cài đặt OpenClaw Free A-Z" width="300"/> |
| </a><br/> |
| <b>🇻🇳 Tiếng Việt</b><br/> |
| <sub>Cài Đặt OpenClaw Free Từ A-Z + 9Router<br/>by <a href="https://www.youtube.com/@maigia">Mai Gia</a></sub> |
| </td> |
| <td align="center" width="320"> |
| <a href="https://www.youtube.com/watch?v=JXmg8_gccgE"> |
| <img src="https://img.youtube.com/vi/JXmg8_gccgE/maxresdefault.jpg" alt="FREE OpenClaw with Claude Opus" width="300"/> |
| </a><br/> |
| <b>🇺🇸 English</b><br/> |
| <sub>FREE OpenClaw + Claude Opus 4.6<br/>by <a href="https://www.youtube.com/@BuildAIWithHamid">Build AI With Hamid</a></sub> |
| </td> |
| </tr> |
| <tr> |
| <td align="center" width="320"> |
| <a href="https://www.youtube.com/watch?v=CkVZZUSTXAI"> |
| <img src="https://img.youtube.com/vi/CkVZZUSTXAI/mqdefault.jpg" alt="Claude CLI Free Setup" width="300"/> |
| </a><br/> |
| <b>🇮🇩 Indonesia</b><br/> |
| <sub>Koding 24 Jam Anti Rate Limit! Hemat Token AI 65% | Tutorial Quick Setup 9Router 🚀<br/>by <a href="https://www.youtube.com/@krisswuh">Krisswuh</a></sub> |
| </td> |
| </tr> |
| </table> |
| |
| </div> |
| |
| > 🎬 **Made a video about 9Router?** Submit a [Pull Request](https://github.com/decolua/9router/pulls) adding your video to this section — we'll merge it! |
| |
| --- |
| |
| ## 🛠️ Supported CLI Tools |
| |
| 9Router works seamlessly with all major AI coding tools: |
| |
| <div align="center"> |
| <table> |
| <tr> |
| <td align="center" width="120"> |
| <img src="./public/providers/claude.png" width="60" alt="Claude Code"/><br/> |
| <b>Claude-Code</b> |
| </td> |
| <td align="center" width="120"> |
| <img src="./public/providers/openclaw.png" width="60" alt="OpenClaw"/><br/> |
| <b>OpenClaw</b> |
| </td> |
| <td align="center" width="120"> |
| <img src="./public/providers/codex.png" width="60" alt="Codex"/><br/> |
| <b>Codex</b> |
| </td> |
| <td align="center" width="120"> |
| <img src="./public/providers/opencode.png" width="60" alt="OpenCode"/><br/> |
| <b>OpenCode</b> |
| </td> |
| <td align="center" width="120"> |
| <img src="./public/providers/cursor.png" width="60" alt="Cursor"/><br/> |
| <b>Cursor</b> |
| </td> |
| <td align="center" width="120"> |
| <img src="./public/providers/antigravity.png" width="60" alt="Antigravity"/><br/> |
| <b>Antigravity</b> |
| </td> |
| </tr> |
| <tr> |
| <td align="center" width="120"> |
| <img src="./public/providers/cline.png" width="60" alt="Cline"/><br/> |
| <b>Cline</b> |
| </td> |
| <td align="center" width="120"> |
| <img src="./public/providers/continue.png" width="60" alt="Continue"/><br/> |
| <b>Continue</b> |
| </td> |
| <td align="center" width="120"> |
| <img src="./public/providers/droid.png" width="60" alt="Droid"/><br/> |
| <b>Droid</b> |
| </td> |
| <td align="center" width="120"> |
| <img src="./public/providers/roo.png" width="60" alt="Roo"/><br/> |
| <b>Roo</b> |
| </td> |
| <td align="center" width="120"> |
| <img src="./public/providers/copilot.png" width="60" alt="Copilot"/><br/> |
| <b>Copilot</b> |
| </td> |
| <td align="center" width="120"> |
| <img src="./public/providers/kilocode.png" width="60" alt="Kilo Code"/><br/> |
| <b>Kilo Code</b> |
| </td> |
| </tr> |
| </table> |
| </div> |
| |
| --- |
| |
| ## 🌐 Supported Providers |
| |
| ### 🔐 OAuth Providers |
| |
| <div align="center"> |
| <table> |
| <tr> |
| <td align="center" width="120"> |
| <img src="./public/providers/claude.png" width="60" alt="Claude Code"/><br/> |
| <b>Claude-Code</b> |
| </td> |
| <td align="center" width="120"> |
| <img src="./public/providers/antigravity.png" width="60" alt="Antigravity"/><br/> |
| <b>Antigravity</b> |
| </td> |
| <td align="center" width="120"> |
| <img src="./public/providers/codex.png" width="60" alt="Codex"/><br/> |
| <b>Codex</b> |
| </td> |
| <td align="center" width="120"> |
| <img src="./public/providers/github.png" width="60" alt="GitHub"/><br/> |
| <b>GitHub</b> |
| </td> |
| <td align="center" width="120"> |
| <img src="./public/providers/cursor.png" width="60" alt="Cursor"/><br/> |
| <b>Cursor</b> |
| </td> |
| </tr> |
| </table> |
| </div> |
| |
| ### 🆓 Free Providers |
| |
| <div align="center"> |
| <table> |
| <tr> |
| <td align="center" width="150"> |
| <img src="./public/providers/kiro.png" width="70" alt="Kiro"/><br/> |
| <b>Kiro AI</b><br/> |
| <sub>Claude 4.5 + GLM-5 + MiniMax<br/>Unlimited FREE</sub> |
| </td> |
| <td align="center" width="150"> |
| <img src="./public/providers/opencode.png" width="70" alt="OpenCode Free"/><br/> |
| <b>OpenCode Free</b><br/> |
| <sub>No auth • Auto-fetch models<br/>Unlimited FREE</sub> |
| </td> |
| <td align="center" width="150"> |
| <img src="./public/providers/gemini.png" width="70" alt="Vertex AI"/><br/> |
| <b>Vertex AI</b><br/> |
| <sub>Gemini 3 Pro + GLM-5 + DeepSeek<br/>$300 credits free</sub> |
| </td> |
| </tr> |
| </table> |
| </div> |
| |
| > **Note:** iFlow, Qwen and Gemini CLI free tiers were discontinued in 2026. Use Kiro / OpenCode Free / Vertex instead. |
| |
| ### 🔑 API Key Providers (40+) |
| |
| <div align="center"> |
| <table> |
| <tr> |
| <td align="center" width="100"> |
| <img src="./public/providers/openrouter.png" width="50" alt="OpenRouter"/><br/> |
| <sub>OpenRouter</sub> |
| </td> |
| <td align="center" width="100"> |
| <img src="./public/providers/glm.png" width="50" alt="GLM"/><br/> |
| <sub>GLM</sub> |
| </td> |
| <td align="center" width="100"> |
| <img src="./public/providers/kimi.png" width="50" alt="Kimi"/><br/> |
| <sub>Kimi</sub> |
| </td> |
| <td align="center" width="100"> |
| <img src="./public/providers/minimax.png" width="50" alt="MiniMax"/><br/> |
| <sub>MiniMax</sub> |
| </td> |
| <td align="center" width="100"> |
| <img src="./public/providers/openai.png" width="50" alt="OpenAI"/><br/> |
| <sub>OpenAI</sub> |
| </td> |
| <td align="center" width="100"> |
| <img src="./public/providers/anthropic.png" width="50" alt="Anthropic"/><br/> |
| <sub>Anthropic</sub> |
| </td> |
| </tr> |
| <tr> |
| <td align="center" width="100"> |
| <img src="./public/providers/gemini.png" width="50" alt="Gemini"/><br/> |
| <sub>Gemini</sub> |
| </td> |
| <td align="center" width="100"> |
| <img src="./public/providers/deepseek.png" width="50" alt="DeepSeek"/><br/> |
| <sub>DeepSeek</sub> |
| </td> |
| <td align="center" width="100"> |
| <img src="./public/providers/groq.png" width="50" alt="Groq"/><br/> |
| <sub>Groq</sub> |
| </td> |
| <td align="center" width="100"> |
| <img src="./public/providers/xai.png" width="50" alt="xAI"/><br/> |
| <sub>xAI</sub> |
| </td> |
| <td align="center" width="100"> |
| <img src="./public/providers/mistral.png" width="50" alt="Mistral"/><br/> |
| <sub>Mistral</sub> |
| </td> |
| <td align="center" width="100"> |
| <img src="./public/providers/perplexity.png" width="50" alt="Perplexity"/><br/> |
| <sub>Perplexity</sub> |
| </td> |
| </tr> |
| <tr> |
| <td align="center" width="100"> |
| <img src="./public/providers/together.png" width="50" alt="Together"/><br/> |
| <sub>Together AI</sub> |
| </td> |
| <td align="center" width="100"> |
| <img src="./public/providers/fireworks.png" width="50" alt="Fireworks"/><br/> |
| <sub>Fireworks</sub> |
| </td> |
| <td align="center" width="100"> |
| <img src="./public/providers/cerebras.png" width="50" alt="Cerebras"/><br/> |
| <sub>Cerebras</sub> |
| </td> |
| <td align="center" width="100"> |
| <img src="./public/providers/cohere.png" width="50" alt="Cohere"/><br/> |
| <sub>Cohere</sub> |
| </td> |
| <td align="center" width="100"> |
| <img src="./public/providers/nvidia.png" width="50" alt="NVIDIA"/><br/> |
| <sub>NVIDIA</sub> |
| </td> |
| <td align="center" width="100"> |
| <img src="./public/providers/siliconflow.png" width="50" alt="SiliconFlow"/><br/> |
| <sub>SiliconFlow</sub> |
| </td> |
| </tr> |
| </table> |
| <p><i>...and 20+ more providers including Nebius, Chutes, Hyperbolic, and custom OpenAI/Anthropic compatible endpoints</i></p> |
| </div> |
| |
| --- |
| |
| ## 💡 Key Features |
| |
| | Feature | What It Does | Why It Matters | |
| |---------|--------------|----------------| |
| | 🚀 **RTK Token Saver** ([RTK](https://github.com/rtk-ai/rtk) ⭐40K) | Compress tool outputs (`git diff`, `grep`, `ls`, `tree`...) before sending to LLM | Save **20-40% input tokens** per request | |
| | 🪨 **Caveman Mode** ([Caveman](https://github.com/JuliusBrussee/caveman) ⭐52K) | Inject caveman-speak prompt → LLM replies terse, technical substance preserved | Save **up to 65% output tokens** | |
| | 🎯 **Smart 3-Tier Fallback** | Auto-route: Subscription → Cheap → Free | Never stop coding, zero downtime | |
| | 📊 **Real-Time Quota Tracking** | Live token count + reset countdown | Maximize subscription value | |
| | 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro ↔ Vertex | Works with any CLI tool | |
| | 👥 **Multi-Account Support** | Multiple accounts per provider | Load balancing + redundancy | |
| | 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically | No manual re-login needed | |
| | 🎨 **Custom Combos** | Create unlimited model combinations | Tailor fallback to your needs | |
| | 📝 **Request Logging** | Debug mode with full request/response logs | Troubleshoot issues easily | |
| | 💾 **Cloud Sync** | Sync config across devices | Same setup everywhere | |
| | 📊 **Usage Analytics** | Track tokens, cost, trends over time | Optimize spending | |
| | 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloudflare Workers | Flexible deployment options | |
| |
| <details> |
| <summary><b>📖 Feature Details</b></summary> |
| |
| ### 🚀 RTK Token Saver |
| |
| Tool outputs (`git diff`, `grep`, `find`, `ls`, `tree`, log dumps...) often eat 30-50% of your prompt budget. RTK detects them and applies smart, lossless compression **before** the request hits the LLM: |
| |
| - **Filters:** `git-diff`, `git-status`, `grep`, `find`, `ls`, `tree`, `dedup-log`, `smart-truncate`, `read-numbered`, `search-list` |
| - **Auto-detect:** No config needed — RTK peeks the first 1KB of each `tool_result` and picks the right filter. |
| - **Safe by design:** If a filter fails, throws, or makes output bigger, RTK silently keeps the original text. Errors never break your request. |
| - **Universal:** Works across all formats (OpenAI, Claude, Gemini, Cursor, Kiro, OpenAI Responses) because it runs **before** any format translation. |
| - **Default ON:** Toggle anytime in Dashboard → Endpoint settings. |
| |
| ``` |
| Without RTK: 47K tokens sent to LLM |
| With RTK: 28K tokens sent to LLM (40% saved · same context · same answer) |
| ``` |
| |
| ### 🎯 Smart 3-Tier Fallback |
| |
| Create combos with automatic fallback: |
| |
| ``` |
| Combo: "my-coding-stack" |
| 1. cc/claude-opus-4-6 (your subscription) |
| 2. glm/glm-4.7 (cheap backup, $0.6/1M) |
| 3. if/kimi-k2-thinking (free fallback) |
|
|
| → Auto switches when quota runs out or errors occur |
| ``` |
| |
| ### 📊 Real-Time Quota Tracking |
| |
| - Token consumption per provider |
| - Reset countdown (5-hour, daily, weekly) |
| - Cost estimation for paid tiers |
| - Monthly spending reports |
| |
| ### 🔄 Format Translation |
| |
| Seamless translation between formats: |
| - **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **Cursor** ↔ **Kiro** ↔ **Vertex** ↔ **Antigravity** ↔ **Ollama** ↔ **OpenAI Responses** |
| - Your CLI tool sends OpenAI format → 9Router translates → Provider receives native format |
| - Works with any tool that supports custom OpenAI endpoints |
| |
| ### 👥 Multi-Account Support |
| |
| - Add multiple accounts per provider |
| - Auto round-robin or priority-based routing |
| - Fallback to next account when one hits quota |
| |
| ### 🔄 Auto Token Refresh |
| |
| - OAuth tokens automatically refresh before expiration |
| - No manual re-authentication needed |
| - Seamless experience across all providers |
| |
| ### 🎨 Custom Combos |
| |
| - Create unlimited model combinations |
| - Mix subscription, cheap, and free tiers |
| - Name your combos for easy access |
| - Share combos across devices with Cloud Sync |
| |
| ### 📝 Request Logging |
| |
| - Enable debug mode for full request/response logs |
| - Track API calls, headers, and payloads |
| - Troubleshoot integration issues |
| - Export logs for analysis |
| |
| ### 💾 Cloud Sync |
| |
| - Sync providers, combos, and settings across devices |
| - Automatic background sync |
| - Secure encrypted storage |
| - Access your setup from anywhere |
| |
| #### Cloud Runtime Notes |
| |
| - Prefer server-side cloud variables in production: |
| - `BASE_URL` (internal callback URL used by sync scheduler) |
| - `CLOUD_URL` (cloud sync endpoint base) |
| - `NEXT_PUBLIC_BASE_URL` and `NEXT_PUBLIC_CLOUD_URL` are still supported for compatibility/UI, but server runtime now prioritizes `BASE_URL`/`CLOUD_URL`. |
| - Cloud sync requests now use timeout + fail-fast behavior to avoid UI hanging when cloud DNS/network is unavailable. |
| |
| ### 📊 Usage Analytics |
| |
| - Track token usage per provider and model |
| - Cost estimation and spending trends |
| - Monthly reports and insights |
| - Optimize your AI spending |
| |
| > **💡 IMPORTANT - Understanding Dashboard Costs:** |
| > |
| > The "cost" displayed in Usage Analytics is **for tracking and comparison purposes only**. |
| > 9Router itself **never charges** you anything. You only pay providers directly (if using paid services). |
| > |
| > **Example:** If your dashboard shows "$290 total cost" while using iFlow models, this represents |
| > what you would have paid using paid APIs directly. Your actual cost = **$0** (iFlow is free unlimited). |
| > |
| > Think of it as a "savings tracker" showing how much you're saving by using free models or |
| > routing through 9Router! |
| |
| ### 🌐 Deploy Anywhere |
| |
| - 💻 **Localhost** - Default, works offline |
| - ☁️ **VPS/Cloud** - Share across devices |
| - 🐳 **Docker** - One-command deployment |
| - 🚀 **Cloudflare Workers** - Global edge network |
| |
| </details> |
| |
| --- |
| |
| ## 💰 Pricing at a Glance |
| |
| | Tier | Provider | Cost | Quota Reset | Best For | |
| |------|----------|------|-------------|----------| |
| | **🚀 TOKEN SAVER** | **RTK (built-in)** | **FREE** | Always on | **Save 20-40% tokens on EVERY request** | |
| | **💳 SUBSCRIPTION** | Claude Code (Pro/Max) | $20-200/mo | 5h + weekly | Already subscribed | |
| | | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | |
| | | GitHub Copilot | $10-19/mo | Monthly | GitHub users | |
| | | Cursor IDE | $20/mo | Monthly | Cursor users | |
| | **💰 CHEAP** | GLM-5.1 / GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | |
| | | MiniMax M2.7 | $0.2/1M | 5-hour rolling | Cheapest option | |
| | | Kimi K2.5 | $9/mo flat | 10M tokens/mo | Predictable cost | |
| | **🆓 FREE** | Kiro AI | $0 | Unlimited | Claude 4.5 + GLM-5 + MiniMax free | |
| | | OpenCode Free | $0 | Unlimited | No auth, auto-fetch models | |
| | | Vertex AI | $300 credits | New GCP accounts | Gemini 3 Pro + DeepSeek + GLM-5 | |
| |
| **💡 Pro Tip:** RTK + Kiro AI + OpenCode Free combo = **$0 cost + 20-40% token savings**! |
| |
| --- |
| |
| ### 📊 Understanding 9Router Costs & Billing |
| |
| **9Router Billing Reality:** |
| |
| ✅ **9Router software = FREE forever** (open source, never charges) |
| ✅ **Dashboard "costs" = Display/tracking only** (not actual bills) |
| ✅ **You pay providers directly** (subscriptions or API fees) |
| ✅ **FREE providers stay FREE** (iFlow, Kiro, Qwen = $0 unlimited) |
| ❌ **9Router never sends invoices** or charges your card |
| |
| **How Cost Display Works:** |
| |
| The dashboard shows **estimated costs** as if you were using paid APIs directly. This is **not billing** - it's a comparison tool to show your savings. |
| |
| **Example Scenario:** |
| ``` |
| Dashboard Display: |
| • Total Requests: 1,662 |
| • Total Tokens: 47M |
| • Display Cost: $290 |
|
|
| Reality Check: |
| • Provider: iFlow (FREE unlimited) |
| • Actual Payment: $0.00 |
| • What $290 Means: Amount you SAVED by using free models! |
| ``` |
| |
| **Payment Rules:** |
| - **Subscription providers** (Claude Code, Codex): Pay them directly via their websites |
| - **Cheap providers** (GLM, MiniMax): Pay them directly, 9Router just routes |
| - **FREE providers** (iFlow, Kiro, Qwen): Genuinely free forever, no hidden charges |
| - **9Router**: Never charges anything, ever |
| |
| --- |
| |
| ## 🎯 Use Cases |
| |
| ### Case 1: "I have Claude Pro subscription" |
| |
| **Problem:** Quota expires unused, rate limits during heavy coding |
| |
| **Solution:** |
| ``` |
| Combo: "maximize-claude" |
| 1. cc/claude-opus-4-7 (use subscription fully) |
| 2. glm/glm-5.1 (cheap backup when quota out) |
| 3. kr/claude-sonnet-4.5 (free emergency fallback) |
|
|
| Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total |
| vs. $20 + hitting limits = frustration |
| ``` |
| |
| ### Case 2: "I want zero cost" |
| |
| **Problem:** Can't afford subscriptions, need reliable AI coding |
| |
| **Solution:** |
| ``` |
| Combo: "free-forever" |
| 1. kr/claude-sonnet-4.5 (Claude 4.5 free unlimited) |
| 2. kr/glm-5 (GLM-5 free via Kiro) |
| 3. oc/<auto> (OpenCode Free, no auth) |
|
|
| Monthly cost: $0 |
| Quality: Production-ready models + RTK saves 20-40% tokens |
| ``` |
| |
| ### Case 3: "I need 24/7 coding, no interruptions" |
| |
| **Problem:** Deadlines, can't afford downtime |
| |
| **Solution:** |
| ``` |
| Combo: "always-on" |
| 1. cc/claude-opus-4-7 (best quality) |
| 2. cx/gpt-5.5 (second subscription) |
| 3. glm/glm-5.1 (cheap, resets daily) |
| 4. minimax/MiniMax-M2.7 (cheapest, 5h reset) |
| 5. kr/claude-sonnet-4.5 (free unlimited) |
|
|
| Result: 5 layers of fallback = zero downtime |
| Monthly cost: $20-200 (subscriptions) + $10-20 (backup) |
| ``` |
| |
| ### Case 4: "I want FREE AI in OpenClaw" |
| |
| **Problem:** Need AI assistant in messaging apps (WhatsApp, Telegram, Slack...), completely free |
| |
| **Solution:** |
| ``` |
| Combo: "openclaw-free" |
| 1. kr/claude-sonnet-4.5 (Claude 4.5 free) |
| 2. kr/glm-5 (GLM-5 free) |
| 3. kr/MiniMax-M2.5 (MiniMax free) |
|
|
| Monthly cost: $0 |
| Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... |
| ``` |
| |
| --- |
| |
| ## ❓ Frequently Asked Questions |
| |
| <details> |
| <summary><b>📊 Why does my dashboard show high costs?</b></summary> |
| |
| The dashboard tracks your token usage and displays **estimated costs** as if you were using paid APIs directly. This is **not actual billing** - it's a reference to show how much you're saving by using free models or existing subscriptions through 9Router. |
| |
| **Example:** |
| - **Dashboard shows:** "$290 total cost" |
| - **Reality:** You're using iFlow (FREE unlimited) |
| - **Your actual cost:** **$0.00** |
| - **What $290 means:** Amount you **saved** by using free models instead of paid APIs! |
| |
| The cost display is a "savings tracker" to help you understand your usage patterns and optimization opportunities. |
| |
| </details> |
| |
| <details> |
| <summary><b>💳 Will I be charged by 9Router?</b></summary> |
| |
| **No.** 9Router is free, open-source software that runs on your own computer. It never charges you anything. |
| |
| **You only pay:** |
| - ✅ **Subscription providers** (Claude Code $20/mo, Codex $20-200/mo) → Pay them directly on their websites |
| - ✅ **Cheap providers** (GLM, MiniMax) → Pay them directly, 9Router just routes your requests |
| - ❌ **9Router itself** → **Never charges anything, ever** |
| |
| 9Router is a local proxy/router. It doesn't have your credit card, can't send invoices, and has no billing system. It's completely free software. |
| |
| </details> |
| |
| <details> |
| <summary><b>🆓 Are FREE providers really unlimited?</b></summary> |
| |
| **Yes!** The current FREE providers (Kiro, OpenCode Free, Vertex) are genuinely free with **no hidden charges**. |
| |
| These are free services offered by those respective companies: |
| - **Kiro AI**: Free unlimited Claude 4.5 + GLM-5 + MiniMax via AWS Builder ID / Google / GitHub OAuth |
| - **OpenCode Free**: No-auth passthrough proxy, models auto-fetched from `opencode.ai/zen/v1/models` |
| - **Vertex AI**: $300 free credits for new Google Cloud accounts (90 days) |
| |
| 9Router just routes your requests to them - there's no "catch" or future billing. They're truly free services, and 9Router makes them easy to use with fallback support. |
| |
| **Discontinued free tiers (no longer recommended):** |
| - ❌ **iFlow**: Was free unlimited, now changed to paid (2026) |
| - ❌ **Qwen Code**: Free OAuth tier discontinued by Alibaba on 2026-04-15 |
| - ❌ **Gemini CLI**: Still works, but using it with non-CLI tools (Claude, Codex, Cursor...) may result in account bans — only use if you stick to Gemini CLI itself |
| |
| </details> |
| |
| <details> |
| <summary><b>💰 How do I minimize my actual AI costs?</b></summary> |
| |
| **Free-First Strategy:** |
| |
| 1. **Start with 100% free combo:** |
| ``` |
| 1. gc/gemini-3-flash (180K/month free from Google) |
| 2. if/kimi-k2-thinking (unlimited free from iFlow) |
| 3. qw/qwen3-coder-plus (unlimited free from Qwen) |
| ``` |
| **Cost: $0/month** |
| |
| 2. **Add cheap backup** only if you need it: |
| ``` |
| 4. glm/glm-4.7 ($0.6/1M tokens) |
| ``` |
| **Additional cost: Only pay for what you actually use** |
| |
| 3. **Use subscription providers last:** |
| - Only if you already have them |
| - 9Router helps maximize their value through quota tracking |
| |
| **Result:** Most users can operate at $0/month using only free tiers! |
| |
| </details> |
| |
| <details> |
| <summary><b>📈 What if my usage suddenly spikes?</b></summary> |
| |
| 9Router's smart fallback prevents surprise charges: |
| |
| **Scenario:** You're on a coding sprint and blow through your quotas |
| |
| **Without 9Router:** |
| - ❌ Hit rate limit → Work stops → Frustration |
| - ❌ Or: Accidentally rack up huge API bills |
| |
| **With 9Router:** |
| - ✅ Subscription hits limit → Auto-fallback to cheap tier |
| - ✅ Cheap tier gets expensive → Auto-fallback to free tier |
| - ✅ Never stop coding → Predictable costs |
| |
| **You're in control:** Set spending limits per provider in dashboard, and 9Router respects them. |
| |
| </details> |
| |
| --- |
| |
| ## 📖 Setup Guide |
| |
| <details> |
| <summary><b>🔐 Subscription Providers (Maximize Value)</b></summary> |
| |
| ### Claude Code (Pro/Max) |
| |
| ```bash |
| Dashboard → Providers → Connect Claude Code |
| → OAuth login → Auto token refresh |
| → 5-hour + weekly quota tracking |
|
|
| Models: |
| cc/claude-opus-4-7 |
| cc/claude-opus-4-6 |
| cc/claude-sonnet-4-6 |
| cc/claude-haiku-4-5-20251001 |
| ``` |
| |
| **Pro Tip:** Use Opus for complex tasks, Sonnet for speed. 9Router tracks quota per model! |
| |
| ### OpenAI Codex (Plus/Pro) |
| |
| ```bash |
| Dashboard → Providers → Connect Codex |
| → OAuth login (port 1455) |
| → 5-hour + weekly reset |
|
|
| Models: |
| cx/gpt-5.5 |
| cx/gpt-5.4 |
| cx/gpt-5.3-codex |
| cx/gpt-5.2-codex |
| ``` |
| |
| ### GitHub Copilot |
| |
| ```bash |
| Dashboard → Providers → Connect GitHub |
| → OAuth via GitHub |
| → Monthly reset (1st of month) |
|
|
| Models: |
| gh/gpt-5.4 |
| gh/claude-opus-4.7 |
| gh/claude-sonnet-4.6 |
| gh/gemini-3.1-pro-preview |
| gh/grok-code-fast-1 |
| ``` |
| |
| ### Cursor IDE |
| |
| ```bash |
| Dashboard → Providers → Connect Cursor |
| → OAuth login |
| → Monthly subscription |
|
|
| Models: |
| cu/claude-4.6-opus-max |
| cu/claude-4.5-sonnet-thinking |
| cu/gpt-5.3-codex |
| ``` |
| |
| </details> |
| |
| <details> |
| <summary><b>💰 Cheap Providers (Backup)</b></summary> |
| |
| ### GLM-5.1 / GLM-4.7 (Daily reset, $0.6/1M) |
| |
| 1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) |
| 2. Get API key from Coding Plan |
| 3. Dashboard → Add API Key: |
| - Provider: `glm` |
| - API Key: `your-key` |
| |
| **Use:** `glm/glm-5.1`, `glm/glm-5`, `glm/glm-4.7` |
| |
| **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. |
| |
| ### MiniMax M2.7 (5h reset, $0.20/1M) |
| |
| 1. Sign up: [MiniMax](https://www.minimax.io/) |
| 2. Get API key |
| 3. Dashboard → Add API Key |
| |
| **Use:** `minimax/MiniMax-M2.7`, `minimax/MiniMax-M2.5` |
| |
| **Pro Tip:** Cheapest option for long context (1M tokens)! |
| |
| ### Kimi K2.5 ($9/month flat) |
| |
| 1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) |
| 2. Get API key |
| 3. Dashboard → Add API Key |
| |
| **Use:** `kimi/kimi-k2.5`, `kimi/kimi-k2.5-thinking` |
| |
| **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! |
| |
| </details> |
| |
| <details> |
| <summary><b>🆓 FREE Providers (Recommended)</b></summary> |
| |
| ### Kiro AI (Claude 4.5 + GLM-5 + MiniMax FREE) |
| |
| ```bash |
| Dashboard → Connect Kiro |
| → AWS Builder ID, AWS IAM Identity Center, Google, or GitHub |
| → Unlimited usage |
|
|
| Models: |
| kr/claude-sonnet-4.5 |
| kr/claude-haiku-4.5 |
| kr/glm-5 |
| kr/MiniMax-M2.5 |
| kr/qwen3-coder-next |
| kr/deepseek-3.2 |
| ``` |
| |
| **Pro Tip:** Best free option for Claude. No API key, no payment, fully unlimited. |
| |
| ### OpenCode Free (No auth, auto-fetch models) |
| |
| ```bash |
| Dashboard → Connect OpenCode Free |
| → No login required (passthrough proxy) |
| → Models auto-fetched from opencode.ai/zen/v1/models |
| ``` |
| |
| **Pro Tip:** Fastest setup. Just connect and start coding. |
| |
| ### Vertex AI ($300 free credits for new GCP accounts) |
| |
| ```bash |
| Dashboard → Connect Vertex AI |
| → Upload Google Cloud Service Account JSON |
| → Enable Vertex AI API in your GCP project |
|
|
| Models: |
| vertex/gemini-3.1-pro-preview |
| vertex/gemini-3-flash-preview |
| vertex/gemini-2.5-flash |
|
|
| Vertex Partner (Anthropic / DeepSeek / GLM / Qwen via Vertex): |
| vertex-partner/glm-5-maas |
| vertex-partner/deepseek-v3.2-maas |
| vertex-partner/qwen3-next-80b-a3b-thinking-maas |
| ``` |
| |
| **Pro Tip:** New Google Cloud accounts get $300 credits free for 90 days. Plenty for daily coding. |
| |
| </details> |
| |
| <details> |
| <summary><b>🎨 Create Combos</b></summary> |
| |
| ### Example 1: Maximize Subscription → Cheap Backup |
| |
| ``` |
| Dashboard → Combos → Create New |
|
|
| Name: premium-coding |
| Models: |
| 1. cc/claude-opus-4-7 (Subscription primary) |
| 2. glm/glm-5.1 (Cheap backup, $0.6/1M) |
| 3. minimax/MiniMax-M2.7 (Cheapest fallback, $0.20/1M) |
|
|
| Use in CLI: premium-coding |
|
|
| Monthly cost example (100M tokens): |
| 80M via Claude (subscription): $0 extra |
| 15M via GLM: $9 |
| 5M via MiniMax: $1 |
| Total: $10 + your subscription |
| ``` |
| |
| ### Example 2: Free-Only (Zero Cost) |
| |
| ``` |
| Name: free-combo |
| Models: |
| 1. kr/claude-sonnet-4.5 (Claude 4.5 free unlimited) |
| 2. kr/glm-5 (GLM-5 free via Kiro) |
| 3. vertex/gemini-3.1-pro-preview ($300 free credits) |
|
|
| Cost: $0 forever (+ 20-40% token savings via RTK)! |
| ``` |
| |
| </details> |
| |
| <details> |
| <summary><b>🔧 CLI Integration</b></summary> |
| |
| ### Cursor IDE |
| |
| ``` |
| Settings → Models → Advanced: |
| OpenAI API Base URL: http://localhost:20128/v1 |
| OpenAI API Key: [from 9router dashboard] |
| Model: cc/claude-opus-4-7 |
| ``` |
| |
| Or use combo: `premium-coding` |
| |
| ### Claude Code |
| |
| Edit `~/.claude/config.json`: |
| |
| ```json |
| { |
| "anthropic_api_base": "http://localhost:20128/v1", |
| "anthropic_api_key": "your-9router-api-key" |
| } |
| ``` |
| |
| ### Codex CLI |
| |
| ```bash |
| export OPENAI_BASE_URL="http://localhost:20128" |
| export OPENAI_API_KEY="your-9router-api-key" |
|
|
| codex "your prompt" |
| ``` |
| |
| ### OpenClaw |
| |
| **Option 1 — Dashboard (recommended):** |
| |
| ``` |
| Dashboard → CLI Tools → OpenClaw → Select Model → Apply |
| ``` |
| |
| **Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: |
| |
| ```json |
| { |
| "agents": { |
| "defaults": { |
| "model": { |
| "primary": "9router/kr/claude-sonnet-4.5" |
| } |
| } |
| }, |
| "models": { |
| "providers": { |
| "9router": { |
| "baseUrl": "http://127.0.0.1:20128/v1", |
| "apiKey": "sk_9router", |
| "api": "openai-completions", |
| "models": [ |
| { |
| "id": "kr/claude-sonnet-4.5", |
| "name": "Claude Sonnet 4.5 (Kiro Free)" |
| } |
| ] |
| } |
| } |
| } |
| } |
| ``` |
| |
| > **Note:** OpenClaw only works with local 9Router. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. |
|
|
| ### Cline / Continue / RooCode |
|
|
| ``` |
| Provider: OpenAI Compatible |
| Base URL: http://localhost:20128/v1 |
| API Key: [from dashboard] |
| Model: cc/claude-opus-4-7 |
| ``` |
|
|
| </details> |
|
|
| <details> |
| <summary><b>🚀 Deployment</b></summary> |
|
|
| ### VPS Deployment |
|
|
| ```bash |
| # Clone and install |
| git clone https://github.com/decolua/9router.git |
| cd 9router |
| npm install |
| npm run build |
| |
| # Configure |
| export JWT_SECRET="your-secure-secret-change-this" |
| export INITIAL_PASSWORD="your-password" |
| export DATA_DIR="/var/lib/9router" |
| export PORT="20128" |
| export HOSTNAME="0.0.0.0" |
| export NODE_ENV="production" |
| export NEXT_PUBLIC_BASE_URL="http://localhost:20128" |
| export NEXT_PUBLIC_CLOUD_URL="https://9router.com" |
| export API_KEY_SECRET="endpoint-proxy-api-key-secret" |
| export MACHINE_ID_SALT="endpoint-proxy-salt" |
| |
| # Start |
| npm run start |
| |
| # Or use PM2 |
| npm install -g pm2 |
| pm2 start npm --name 9router -- start |
| pm2 save |
| pm2 startup |
| ``` |
|
|
| ### Docker |
|
|
| Published images (multi-platform `linux/amd64` + `linux/arm64`): |
| - Docker Hub: [`decolua/9router`](https://hub.docker.com/r/decolua/9router) |
| - GHCR: [`ghcr.io/decolua/9router`](https://github.com/decolua/9router/pkgs/container/9router) |
|
|
| **Quick start (use published image):** |
|
|
| ```bash |
| docker run -d \ |
| --name 9router \ |
| -p 20128:20128 \ |
| -v "$HOME/.9router:/app/data" \ |
| -e DATA_DIR=/app/data \ |
| decolua/9router:latest |
| ``` |
|
|
| → Open http://localhost:20128 |
|
|
| **Build from source (dev):** |
|
|
| ```bash |
| git clone https://github.com/decolua/9router.git |
| cd 9router/app |
| docker build -t 9router . |
| docker run -d --name 9router -p 20128:20128 \ |
| -v "$HOME/.9router:/app/data" -e DATA_DIR=/app/data 9router |
| ``` |
|
|
| **Container defaults:** |
| - `PORT=20128` |
| - `HOSTNAME=0.0.0.0` |
|
|
| **Useful commands:** |
|
|
| ```bash |
| docker logs -f 9router |
| docker restart 9router |
| docker stop 9router && docker rm 9router |
| docker pull decolua/9router:latest # update to latest |
| ``` |
|
|
| **Data persistence:** `$HOME/.9router/db/data.sqlite` on host ↔ `/app/data/db/data.sqlite` in container. |
|
|
| ### Environment Variables |
|
|
| | Variable | Default | Description | |
| |----------|---------|-------------| |
| | `JWT_SECRET` | Auto-generated (`~/.9router/jwt-secret`) | JWT signing secret for dashboard auth cookie (override to share across instances) | |
| | `INITIAL_PASSWORD` | `123456` | First login password when no saved hash exists | |
| | `DATA_DIR` | `~/.9router` | Main app data location (SQLite at `$DATA_DIR/db/data.sqlite`) | |
| | `PORT` | framework default | Service port (`20128` in examples) | |
| | `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | |
| | `NODE_ENV` | runtime default | Set `production` for deploy | |
| | `BASE_URL` | `http://localhost:20128` | Server-side internal base URL used by cloud sync jobs | |
| | `CLOUD_URL` | `https://9router.com` | Server-side cloud sync endpoint base URL | |
| | `NEXT_PUBLIC_BASE_URL` | `http://localhost:3000` | Backward-compatible/public base URL (prefer `BASE_URL` for server runtime) | |
| | `NEXT_PUBLIC_CLOUD_URL` | `https://9router.com` | Backward-compatible/public cloud URL (prefer `CLOUD_URL` for server runtime) | |
| | `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | |
| | `MACHINE_ID_SALT` | `endpoint-proxy-salt` | Salt for stable machine ID hashing | |
| | `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs under `logs/` | |
| | `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (set `true` behind HTTPS reverse proxy) | |
| | `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` routes (recommended for internet-exposed deploys) | |
| | `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` | empty | Optional outbound proxy for upstream provider calls | |
|
|
| Notes: |
| - Lowercase proxy variables are also supported: `http_proxy`, `https_proxy`, `all_proxy`, `no_proxy`. |
| - `.env` is not baked into Docker image (`.dockerignore`); inject runtime config with `--env-file` or `-e`. |
| - On Windows, `APPDATA` can be used for local storage path resolution. |
| - `INSTANCE_NAME` appears in older docs/env templates, but is currently not used at runtime. |
|
|
| ### Runtime Files and Storage |
|
|
| - Main app state: `${DATA_DIR}/db/data.sqlite` (SQLite — providers, combos, aliases, keys, settings, usage history) |
| - Auto backups: `${DATA_DIR}/db/backups/` |
| - Optional request/translator logs: `<repo>/logs/...` when `ENABLE_REQUEST_LOGS=true` |
| - Both `${DATA_DIR}` and `~/.9router` resolve to the same location in a Docker container — the symlink `/root/.9router -> /app/data` is created at build time. |
|
|
| </details> |
|
|
| --- |
|
|
| ## 📊 Available Models |
|
|
| <details> |
| <summary><b>View all available models</b></summary> |
|
|
| **Claude Code (`cc/`)** - Pro/Max: |
| - `cc/claude-opus-4-7` |
| - `cc/claude-opus-4-6` |
| - `cc/claude-sonnet-4-6` |
| - `cc/claude-sonnet-4-5-20250929` |
| - `cc/claude-haiku-4-5-20251001` |
|
|
| **Codex (`cx/`)** - Plus/Pro: |
| - `cx/gpt-5.5` |
| - `cx/gpt-5.4` |
| - `cx/gpt-5.3-codex` |
| - `cx/gpt-5.2-codex` |
| - `cx/gpt-5.1-codex-max` |
|
|
| **GitHub Copilot (`gh/`)**: |
| - `gh/gpt-5.4` |
| - `gh/claude-opus-4.7` |
| - `gh/claude-sonnet-4.6` |
| - `gh/gemini-3.1-pro-preview` |
| - `gh/grok-code-fast-1` |
|
|
| **Cursor (`cu/`)** - Subscription: |
| - `cu/claude-4.6-opus-max` |
| - `cu/claude-4.5-sonnet-thinking` |
| - `cu/gpt-5.3-codex` |
| - `cu/kimi-k2.5` |
|
|
| **GLM (`glm/`)** - $0.6/1M: |
| - `glm/glm-5.1` |
| - `glm/glm-5` |
| - `glm/glm-4.7` |
|
|
| **MiniMax (`minimax/`)** - $0.2/1M: |
| - `minimax/MiniMax-M2.7` |
| - `minimax/MiniMax-M2.5` |
|
|
| **Kimi (`kimi/`)** - $9/mo flat: |
| - `kimi/kimi-k2.5` |
| - `kimi/kimi-k2.5-thinking` |
|
|
| **Kiro (`kr/`)** - FREE unlimited: |
| - `kr/claude-sonnet-4.5` |
| - `kr/claude-haiku-4.5` |
| - `kr/glm-5` |
| - `kr/MiniMax-M2.5` |
| - `kr/qwen3-coder-next` |
| - `kr/deepseek-3.2` |
|
|
| **OpenCode Free (`oc/`)** - FREE no-auth: |
| - Auto-fetched from `opencode.ai/zen/v1/models` |
|
|
| **Vertex AI (`vertex/`)** - $300 free credits: |
| - `vertex/gemini-3.1-pro-preview` |
| - `vertex/gemini-3-flash-preview` |
| - `vertex/gemini-2.5-flash` |
| - `vertex-partner/glm-5-maas` |
| - `vertex-partner/deepseek-v3.2-maas` |
|
|
| </details> |
|
|
| --- |
|
|
| ## 🐛 Troubleshooting |
|
|
| **"Language model did not provide messages"** |
| - Provider quota exhausted → Check dashboard quota tracker |
| - Solution: Use combo fallback or switch to cheaper tier |
|
|
| **Rate limiting** |
| - Subscription quota out → Fallback to GLM/MiniMax |
| - Add combo: `cc/claude-opus-4-7 → glm/glm-5.1 → kr/claude-sonnet-4.5` |
|
|
| **OAuth token expired** |
| - Auto-refreshed by 9Router |
| - If issues persist: Dashboard → Provider → Reconnect |
|
|
| **High costs** |
| - Enable RTK in Dashboard → Endpoint settings (default ON, saves 20-40% tokens) |
| - Check usage stats in Dashboard |
| - Switch primary model to GLM/MiniMax |
| - Use free tier (Kiro, OpenCode Free, Vertex) for non-critical tasks |
|
|
| **Dashboard opens on wrong port** |
| - Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` |
|
|
| **First login not working** |
| - Check `INITIAL_PASSWORD` in `.env` |
| - If unset, fallback password is `123456` |
|
|
| **No request logs under `logs/`** |
| - Set `ENABLE_REQUEST_LOGS=true` |
|
|
| --- |
|
|
| ## 🛠️ Tech Stack |
|
|
| - **Runtime**: Node.js 20+ |
| - **Framework**: Next.js 16 |
| - **UI**: React 19 + Tailwind CSS 4 |
| - **Database**: SQLite (better-sqlite3 / node:sqlite / sql.js fallback) |
| - **Streaming**: Server-Sent Events (SSE) |
| - **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys |
|
|
| --- |
|
|
| ## 📝 API Reference |
|
|
| ### Chat Completions |
|
|
| ```bash |
| POST http://localhost:20128/v1/chat/completions |
| Authorization: Bearer your-api-key |
| Content-Type: application/json |
| |
| { |
| "model": "cc/claude-opus-4-6", |
| "messages": [ |
| {"role": "user", "content": "Write a function to..."} |
| ], |
| "stream": true |
| } |
| ``` |
|
|
| ### List Models |
|
|
| ```bash |
| GET http://localhost:20128/v1/models |
| Authorization: Bearer your-api-key |
| |
| → Returns all models + combos in OpenAI format |
| ``` |
|
|
| ## 📧 Support |
|
|
| - **Website**: [9router.com](https://9router.com) |
| - **GitHub**: [github.com/decolua/9router](https://github.com/decolua/9router) |
| - **Issues**: [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues) |
|
|
| --- |
|
|
| ## 👥 Contributors |
|
|
| Thanks to all contributors who helped make 9Router better! |
|
|
| [](https://github.com/decolua/9router/graphs/contributors) |
|
|
| --- |
|
|
| ## 📊 Star Chart |
|
|
| [](https://starchart.cc/decolua/9router) |
|
|
|
|
|
|
| ## 🔀 Forks |
|
|
| **[OmniRoute](https://github.com/diegosouzapw/OmniRoute)** — A full-featured TypeScript fork of 9Router. Adds 36+ providers, 4-tier auto-fallback, multi-modal APIs (images, embeddings, audio, TTS), circuit breaker, semantic cache, LLM evaluations, and a polished dashboard. 368+ unit tests. Available via npm and Docker. |
|
|
| --- |
|
|
| ## 🙏 Acknowledgments |
|
|
| Built on the shoulders of giants: |
|
|
| - **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — original Go implementation that inspired this JavaScript port. |
| - **[RTK](https://github.com/rtk-ai/rtk)**  — Rust token-saver. 9Router ports its compression pipeline to JS → **−20-40% input tokens** on every request. |
| - **[Caveman](https://github.com/JuliusBrussee/caveman)**  by **[@JuliusBrussee](https://github.com/JuliusBrussee)** — viral *"why use many token when few token do trick"*. 9Router adapts its prompt → **−65% output tokens**. |
|
|
| Huge thanks to these authors — without their work, 9Router's token-saving features wouldn't exist. ⭐ them on GitHub! |
|
|
| --- |
|
|
| ## 📄 License |
|
|
| MIT License - see [LICENSE](LICENSE) for details. |
|
|
| --- |
|
|
| <div align="center"> |
| <sub>Built with ❤️ for developers who code 24/7</sub> |
| </div> |
|
|