Update Readme
This commit is contained in:
decolua
874
README.md
874
README.md
@@ -1,179 +1,400 @@
|
|||||||
# 9ROUTER - AI Proxy
|
<div align="center">
|
||||||
|
<img src="./images/9router.png" alt="9Router Dashboard" width="800"/>
|
||||||
|
|
||||||
|
# 9Router - FREE AI Coding + Cheap Backups
|
||||||
|
|
||||||
|
**Use Claude, Codex, Gemini for FREE • Ultra-cheap alternatives from $0.20/1M tokens**
|
||||||
|
|
||||||
|
[](https://www.npmjs.com/package/9router)
|
||||||
|
[](https://www.npmjs.com/package/9router)
|
||||||
|
[](https://github.com/decolua/9router/blob/main/LICENSE)
|
||||||
|
|
||||||
|
[🚀 Quick Start](#-quick-start) • [💰 Pricing](#-pricing-strategy) • [📖 Setup](#-setup-guide) • [🌐 Website](https://9router.com)
|
||||||
|
</div>
|
||||||
|
|
||||||
> Universal AI Proxy for Claude Code, Codex, Cursor | OpenAI, Claude, Gemini, Copilot
|
---
|
||||||
|
|
||||||
**Website: [9router.com](https://9router.com)**
|
## Why 9Router?
|
||||||
|
|
||||||
[](https://www.npmjs.com/package/9router)
|
Stop wasting your AI subscriptions and paying full price:
|
||||||
[](https://www.npmjs.com/package/9router)
|
|
||||||
[](https://github.com/yourusername/9router/blob/main/LICENSE)
|
|
||||||
|
|
||||||
A JavaScript port of CLIProxyAPI with web dashboard.
|
- ❌ **Subscription quota expires** unused every month
|
||||||
|
- ❌ **Rate limits** stop you mid-coding
|
||||||
|
- ❌ **Expensive APIs** ($20-50/month per provider)
|
||||||
|
- ❌ **Manual switching** between providers
|
||||||
|
|
||||||
|
**9Router maximizes value:**
|
||||||
|
|
||||||
## Introduction
|
- ✅ **Maximize Subscriptions** - Claude Code, Codex, Gemini, Copilot quota tracking
|
||||||
|
- ✅ **FREE Available** - iFlow, Qwen, Kiro when needed, via CLI
|
||||||
|
- ✅ **Ultra-Cheap Backup** - GLM ($0.6/1M), MiniMax M2.1 ($0.20/1M)
|
||||||
|
- ✅ **Smart Fallback** - Subscription → Cheap → Free, automatic switching
|
||||||
|
|
||||||
**9Router** is a powerful AI API proxy server that provides unified access to multiple AI providers through a single endpoint. It features automatic format translation, intelligent fallback routing, OAuth authentication, and a modern web dashboard for easy management.
|
---
|
||||||
|
|
||||||
**Key Highlights:**
|
## ⚡ Quick Start
|
||||||
- **JavaScript Port**: Converted from CLIProxyAPI (Go) to JavaScript/Node.js.
|
|
||||||
- **Universal CLI Support**: Works seamlessly with Claude Code, OpenAI Codex, Cline, RooCode, AmpCode, Kilo, and other CLI tools
|
|
||||||
- **Cross-Platform**: Runs on Windows, Linux, and macOS
|
|
||||||
- **Easy Deployment**: Simple installation via npx, or deploy to VPS/Dokploy
|
|
||||||
|
|
||||||
## Recent Updates
|
**Install globally:**
|
||||||
|
|
||||||
### v0.2.27
|
|
||||||
- **OpenAI Responses API Support**: Full support for Codex CLI streaming via the Responses API format
|
|
||||||
- **`/v1/models` Endpoint**: OpenAI-compatible models endpoint for client discovery
|
|
||||||
- **Combo Support in Models**: Model combos now appear in the `/v1/models` endpoint
|
|
||||||
- **Improved Usage Tracking**: Better handling of request status for streaming responses
|
|
||||||
- **Kiro (AWS CodeWhisperer) Support**: New provider integration
|
|
||||||
|
|
||||||
### Provider Support
|
|
||||||
| Provider | Alias | Auth Type | Format |
|
|
||||||
|----------|-------|-----------|--------|
|
|
||||||
| Claude (Anthropic) | `cc` | OAuth | Claude |
|
|
||||||
| Codex (OpenAI) | `cx` | OAuth | Responses API |
|
|
||||||
| Gemini CLI | `gc` | OAuth | Gemini CLI |
|
|
||||||
| Antigravity (Google) | `ag` | OAuth | Antigravity |
|
|
||||||
| GitHub Copilot | `gh` | OAuth | OpenAI |
|
|
||||||
| Qwen | `qw` | OAuth | OpenAI |
|
|
||||||
| iFlow | `if` | OAuth | OpenAI |
|
|
||||||
| Kiro (AWS) | `kr` | OAuth | Kiro |
|
|
||||||
| OpenAI | `openai` | API Key | OpenAI |
|
|
||||||
| Anthropic | `anthropic` | API Key | Claude |
|
|
||||||
| Gemini | `gemini` | API Key | Gemini |
|
|
||||||
| OpenRouter | `openrouter` | API Key | OpenAI |
|
|
||||||
|
|
||||||
## Features
|
|
||||||
|
|
||||||
### Core Features
|
|
||||||
- **Multi-Provider Support**: Unified endpoint for 15+ AI providers
|
|
||||||
- **OAuth & API Key Authentication**: Supports both OAuth2 flow and API key authentication
|
|
||||||
- **Format Translation**: Automatic request/response translation between OpenAI, Claude, Gemini, Codex, and Kiro formats
|
|
||||||
- **Web Dashboard**: React-based dashboard for managing providers, combos, API keys, and settings
|
|
||||||
- **Usage Tracking**: Real-time monitoring and analytics for all API requests
|
|
||||||
|
|
||||||
### Advanced Features
|
|
||||||
- **Combo System**: Create model combos with automatic fallback support
|
|
||||||
- **Intelligent Fallback**: Automatic account rotation when rate limits or errors occur
|
|
||||||
- **Response Caching**: Optimized caching for Claude Code
|
|
||||||
- **Model Aliases**: Create custom model aliases for easier management
|
|
||||||
|
|
||||||
### Format Support
|
|
||||||
- **OpenAI Format**: Standard OpenAI Chat Completions API
|
|
||||||
- **OpenAI Responses API**: Codex CLI format with streaming
|
|
||||||
- **Claude Format**: Anthropic Messages API
|
|
||||||
- **Gemini Format**: Google Generative AI API
|
|
||||||
- **Kiro Format**: AWS CodeWhisperer format
|
|
||||||
|
|
||||||
## Install
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Install globally
|
|
||||||
npm install -g 9router
|
npm install -g 9router
|
||||||
9router
|
9router
|
||||||
|
|
||||||
# Run directly with npx
|
|
||||||
npx 9router
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Quick Start
|
🎉 Dashboard opens → Connect Claude Code → Start coding!
|
||||||
|
|
||||||
|
**Use in Cursor/Cline:**
|
||||||
|
|
||||||
|
```
|
||||||
|
Endpoint: http://localhost:20128/v1
|
||||||
|
API Key: [from dashboard]
|
||||||
|
Model: cc/claude-opus-4-5-20251101
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 💰 Pricing Strategy
|
||||||
|
|
||||||
|
### 📅 MAXIMIZE SUBSCRIPTIONS (Primary)
|
||||||
|
|
||||||
|
Already paying? Get full value with quota tracking:
|
||||||
|
|
||||||
|
| Provider | What You Get | Quota Reset | Monthly Cost |
|
||||||
|
|----------|--------------|-------------|--------------|
|
||||||
|
| **Claude Code** (Pro/Max) | Claude 4.5 Opus/Sonnet/Haiku | 5-hour + Weekly | $20-100 |
|
||||||
|
| **OpenAI Codex** (Plus/Pro) | GPT 5.2 Codex, GPT 5.1 Codex Max | 5-hour + Weekly | $20-200 |
|
||||||
|
| **Gemini CLI** (FREE tier!) | 180K completions/month, 1K/day | Daily/Monthly | **$0** |
|
||||||
|
| **GitHub Copilot** | GPT-5, Claude 4.5, Gemini 3 | Monthly (1st) | $10-19 |
|
||||||
|
| **Antigravity** (Google) | Gemini 3 Pro, Claude Sonnet 4.5 | Similar to Gemini | **$0** |
|
||||||
|
|
||||||
|
**Value:** Use every bit of your subscription quota before it resets!
|
||||||
|
|
||||||
|
### 💰 ULTRA CHEAP (Backup)
|
||||||
|
|
||||||
|
When subscription quota runs out, pay pennies:
|
||||||
|
|
||||||
|
| Provider | Pricing (per 1M tokens) | Quota Reset | Cost for 10M |
|
||||||
|
|----------|------------------------|-------------|--------------|
|
||||||
|
| **GLM-4.7** | $0.60 input / $2.20 output | Daily 10:00 AM | ~$6-22 |
|
||||||
|
| **MiniMax M2.1** | $0.20 input / $1.00 output | 5-hour rolling | ~$2-10 |
|
||||||
|
| **Kimi K2** | $9/month (10M tokens) | Monthly | **$9 flat** |
|
||||||
|
|
||||||
|
**Value:** ~90% cheaper than ChatGPT API ($20/1M)!
|
||||||
|
|
||||||
|
### 🆓 FREE FOREVER (Fallback)
|
||||||
|
|
||||||
|
No API key needed, unlimited:
|
||||||
|
|
||||||
|
| Provider | Top Models | Notes |
|
||||||
|
|----------|-----------|-------|
|
||||||
|
| **iFlow** | Kimi K2, Qwen3 Coder Plus, GLM 4.7, MiniMax M2 | 8 models via OAuth |
|
||||||
|
| **Qwen** | Qwen3 Coder Plus/Flash, Vision | 3 models via OAuth |
|
||||||
|
| **Kiro** | Claude Sonnet 4.5, Haiku 4.5 | AWS Builder ID |
|
||||||
|
|
||||||
|
**Value:** Emergency backup when everything else is quota-limited!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✨ Key Features
|
||||||
|
|
||||||
|
### 🔄 Smart 3-Tier Fallback
|
||||||
|
|
||||||
|
```
|
||||||
|
Setup once, never stop coding:
|
||||||
|
|
||||||
|
Tier 1 (SUBSCRIPTION): Claude Code → Codex → Gemini
|
||||||
|
↓ quota exhausted
|
||||||
|
Tier 2 (CHEAP): GLM-4.7 → MiniMax M2.1 → Kimi
|
||||||
|
↓ budget limit
|
||||||
|
Tier 3 (FREE): iFlow → Qwen → Kiro
|
||||||
|
|
||||||
|
→ Automatic switching, zero downtime!
|
||||||
|
```
|
||||||
|
|
||||||
|
### 📊 Quota Tracking
|
||||||
|
|
||||||
|
- Real-time token consumption
|
||||||
|
- Reset countdown per provider
|
||||||
|
- Cost estimation (paid tiers)
|
||||||
|
- Monthly spending reports
|
||||||
|
|
||||||
|
### 🎯 Universal CLI Support
|
||||||
|
|
||||||
|
✅ **Cursor** • **Cline** • **Claude Desktop** • **Codex** • **RooCode** • **Continue** • **Any tool with custom OpenAI endpoint**
|
||||||
|
|
||||||
|
### 🌐 Deploy Options
|
||||||
|
|
||||||
|
💻 **Localhost** • ☁️ **VPS/Cloud** • 🐳 **Docker** • 🚀 **Cloudflare Workers**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📖 Setup Guide
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><b>Subscription Providers (Maximize Value)</b></summary>
|
||||||
|
|
||||||
|
### Claude Code (Pro/Max)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
9router # Start server with default settings
|
Dashboard → Providers → Connect Claude Code
|
||||||
9router --port 8080 # Custom port
|
→ OAuth login → Auto token refresh
|
||||||
9router --no-browser # Don't open browser
|
→ 5-hour + weekly quota tracking
|
||||||
9router --skip-update # Skip auto-update check
|
|
||||||
9router --help # Show help
|
Use: cc/claude-opus-4-5-20251101
|
||||||
|
cc/claude-sonnet-4-5-20250929
|
||||||
```
|
```
|
||||||
|
|
||||||
**Dashboard**: `http://localhost:20128/dashboard`
|
**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. 9Router tracks quota per model!
|
||||||
|
|
||||||
## Remote Deployment
|
### OpenAI Codex (Plus/Pro)
|
||||||
|
|
||||||
### Environment Variables
|
|
||||||
|
|
||||||
Configure these environment variables for remote deployment:
|
|
||||||
|
|
||||||
| Variable | Required | Default | Description |
|
|
||||||
|----------|----------|---------|-------------|
|
|
||||||
| `DATA_DIR` | No | `~/.9router` | Custom data directory path for database storage |
|
|
||||||
| `JWT_SECRET` | **Yes** | `9router-default-secret-change-me` | Secret key for JWT authentication. **Change this in production!** |
|
|
||||||
| `INITIAL_PASSWORD` | No | `123456` | Initial dashboard login password |
|
|
||||||
| `API_KEY_SECRET` | No | Auto-generated | Secret for API key generation/validation |
|
|
||||||
| `MACHINE_ID_SALT` | No | Auto-generated | Salt for machine ID hashing |
|
|
||||||
| `NEXT_PUBLIC_BASE_URL` | No | `http://localhost:3000` | Public base URL of your deployment |
|
|
||||||
| `NEXT_PUBLIC_CLOUD_URL` | No | `https://9router.com` | Cloud sync URL (for cloud features) |
|
|
||||||
| `ENABLE_REQUEST_LOGS` | No | `false` | Enable detailed request/response logging to files |
|
|
||||||
| `NODE_ENV` | No | `development` | Set to `production` for production deployments |
|
|
||||||
|
|
||||||
### Deploying to Dokploy
|
|
||||||
|
|
||||||
1. **Create a new application** in Dokploy
|
|
||||||
2. **Connect your Git repository** or use Docker
|
|
||||||
3. **Set environment variables** in Dokploy's settings:
|
|
||||||
|
|
||||||
```env
|
|
||||||
JWT_SECRET=your-secure-random-secret-here
|
|
||||||
INITIAL_PASSWORD=your-secure-password
|
|
||||||
DATA_DIR=/app/data
|
|
||||||
NODE_ENV=production
|
|
||||||
```
|
|
||||||
|
|
||||||
4. **Build command**: `npm run build`
|
|
||||||
5. **Start command**: `npm run start`
|
|
||||||
6. **Port**: `3000` (or configure via `PORT` env var)
|
|
||||||
|
|
||||||
### Deploying to VPS (Manual)
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Clone the repository
|
Dashboard → Providers → Connect Codex
|
||||||
git clone https://github.com/yourusername/9router.git
|
→ OAuth login (port 1455)
|
||||||
cd 9router
|
→ 5-hour + weekly reset
|
||||||
|
|
||||||
# Install dependencies
|
Use: cx/gpt-5.2-codex
|
||||||
|
cx/gpt-5.1-codex-max
|
||||||
|
```
|
||||||
|
|
||||||
|
### Gemini CLI (FREE 180K/month!)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
Dashboard → Providers → Connect Gemini CLI
|
||||||
|
→ Google OAuth
|
||||||
|
→ 180K completions/month + 1K/day
|
||||||
|
|
||||||
|
Use: gc/gemini-3-flash-preview
|
||||||
|
gc/gemini-2.5-pro
|
||||||
|
```
|
||||||
|
|
||||||
|
**Best Value:** Huge free tier! Use this before paid tiers.
|
||||||
|
|
||||||
|
### GitHub Copilot
|
||||||
|
|
||||||
|
```bash
|
||||||
|
Dashboard → Providers → Connect GitHub
|
||||||
|
→ OAuth via GitHub
|
||||||
|
→ Monthly reset (1st of month)
|
||||||
|
|
||||||
|
Use: gh/gpt-5
|
||||||
|
gh/claude-4.5-sonnet
|
||||||
|
```
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><b>Cheap Providers (Backup)</b></summary>
|
||||||
|
|
||||||
|
### GLM-4.7 (Daily reset, $0.6/1M)
|
||||||
|
|
||||||
|
1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)
|
||||||
|
2. Get API key from Coding Plan
|
||||||
|
3. Dashboard → Add API Key:
|
||||||
|
- Provider: `glm`
|
||||||
|
- API Key: `your-key`
|
||||||
|
|
||||||
|
**Use:** `glm/glm-4.7`
|
||||||
|
|
||||||
|
**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
|
||||||
|
|
||||||
|
### MiniMax M2.1 (5h reset, $0.20/1M)
|
||||||
|
|
||||||
|
1. Sign up: [MiniMax](https://www.minimax.io/)
|
||||||
|
2. Get API key
|
||||||
|
3. Dashboard → Add API Key:
|
||||||
|
- Provider: `minimax`
|
||||||
|
- API Key: `your-key`
|
||||||
|
|
||||||
|
**Use:** `minimax/MiniMax-M2.1`
|
||||||
|
|
||||||
|
**Pro Tip:** 5-hour rolling window. Cheapest option for long context (1M tokens)!
|
||||||
|
|
||||||
|
### Kimi K2 ($9/month flat)
|
||||||
|
|
||||||
|
1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
|
||||||
|
2. Get API key
|
||||||
|
3. Dashboard → Add API Key:
|
||||||
|
- Provider: `kimi`
|
||||||
|
- API Key: `your-key`
|
||||||
|
|
||||||
|
**Use:** `kimi/kimi-latest`
|
||||||
|
|
||||||
|
**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><b>FREE Providers (Emergency Backup)</b></summary>
|
||||||
|
|
||||||
|
### iFlow (8 FREE models)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
Dashboard → Connect iFlow
|
||||||
|
→ iFlow OAuth login
|
||||||
|
→ Unlimited usage
|
||||||
|
|
||||||
|
Use: if/kimi-k2-thinking
|
||||||
|
if/qwen3-coder-plus
|
||||||
|
if/glm-4.7
|
||||||
|
if/minimax-m2
|
||||||
|
```
|
||||||
|
|
||||||
|
### Qwen (3 FREE models)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
Dashboard → Connect Qwen
|
||||||
|
→ Device code authorization
|
||||||
|
→ Unlimited usage
|
||||||
|
|
||||||
|
Use: qw/qwen3-coder-plus
|
||||||
|
qw/qwen3-coder-flash
|
||||||
|
```
|
||||||
|
|
||||||
|
### Kiro (Claude FREE)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
Dashboard → Connect Kiro
|
||||||
|
→ AWS Builder ID or Google/GitHub
|
||||||
|
→ Unlimited usage
|
||||||
|
|
||||||
|
Use: kr/claude-sonnet-4.5
|
||||||
|
kr/claude-haiku-4.5
|
||||||
|
```
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><b>Combo Examples</b></summary>
|
||||||
|
|
||||||
|
### Example 1: Maximize Subscription → Cheap Backup
|
||||||
|
|
||||||
|
```
|
||||||
|
Dashboard → Combos → Create New
|
||||||
|
|
||||||
|
Name: premium-coding
|
||||||
|
Models:
|
||||||
|
1. cc/claude-opus-4-5-20251101 (Subscription primary)
|
||||||
|
2. glm/glm-4.7 (Cheap backup, $0.6/1M)
|
||||||
|
3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)
|
||||||
|
|
||||||
|
Use in CLI: premium-coding
|
||||||
|
|
||||||
|
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: Budget-First with Free Fallback
|
||||||
|
|
||||||
|
```
|
||||||
|
Name: budget-combo
|
||||||
|
Models:
|
||||||
|
1. glm/glm-4.7 (Daily quota, cheap)
|
||||||
|
2. minimax/MiniMax-M2.1 (5h quota, cheapest)
|
||||||
|
3. if/kimi-k2-thinking (FREE unlimited)
|
||||||
|
|
||||||
|
Monthly cost (100M tokens):
|
||||||
|
70M via GLM: $42
|
||||||
|
20M via MiniMax: $4
|
||||||
|
10M via iFlow: $0
|
||||||
|
Total: ~$46 vs $2000 on ChatGPT API!
|
||||||
|
```
|
||||||
|
|
||||||
|
### Example 3: Free-Only (Zero Cost)
|
||||||
|
|
||||||
|
```
|
||||||
|
Name: free-combo
|
||||||
|
Models:
|
||||||
|
1. if/kimi-k2-thinking
|
||||||
|
2. qw/qwen3-coder-plus
|
||||||
|
3. kr/claude-sonnet-4.5
|
||||||
|
|
||||||
|
Cost: $0 forever!
|
||||||
|
```
|
||||||
|
|
||||||
|
</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-5-20251101
|
||||||
|
```
|
||||||
|
|
||||||
|
Or use combo: `premium-coding`
|
||||||
|
|
||||||
|
### Claude Desktop (Claude Code)
|
||||||
|
|
||||||
|
Edit `~/.claude/config.json`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"anthropic_api_base": "http://localhost:20128/v1",
|
||||||
|
"anthropic_api_key": "your-9router-api-key"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Models:** `cc/claude-opus-4-5`, `glm/glm-4.7`, or combo name
|
||||||
|
|
||||||
|
### Codex CLI
|
||||||
|
|
||||||
|
```bash
|
||||||
|
export OPENAI_BASE_URL="http://localhost:20128"
|
||||||
|
export OPENAI_API_KEY="your-9router-api-key"
|
||||||
|
|
||||||
|
codex "your prompt"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Models:** `cx/gpt-5.2-codex`, `glm/glm-4.7`, or combo
|
||||||
|
|
||||||
|
### Cline / Continue / RooCode
|
||||||
|
|
||||||
|
```
|
||||||
|
Provider: OpenAI Compatible
|
||||||
|
Base URL: http://localhost:20128/v1
|
||||||
|
API Key: [from dashboard]
|
||||||
|
Model: cc/claude-opus-4-5-20251101
|
||||||
|
```
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><b>Deployment</b></summary>
|
||||||
|
|
||||||
|
### VPS Deployment
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Clone and install
|
||||||
|
git clone https://github.com/decolua/9router.git
|
||||||
|
cd 9router/app
|
||||||
npm install
|
npm install
|
||||||
|
npm run build
|
||||||
|
|
||||||
# Set environment variables
|
# Configure
|
||||||
export JWT_SECRET="your-secure-random-secret"
|
export JWT_SECRET="your-secure-secret-change-this"
|
||||||
export INITIAL_PASSWORD="your-secure-password"
|
export INITIAL_PASSWORD="your-password"
|
||||||
export DATA_DIR="/var/lib/9router"
|
export DATA_DIR="/var/lib/9router"
|
||||||
export NODE_ENV="production"
|
export NODE_ENV="production"
|
||||||
|
|
||||||
# Build the application
|
# Start
|
||||||
npm run build
|
|
||||||
|
|
||||||
# Start the server
|
|
||||||
npm run start
|
npm run start
|
||||||
|
|
||||||
|
# Or use PM2
|
||||||
|
npm install -g pm2
|
||||||
|
pm2 start npm --name 9router -- start
|
||||||
|
pm2 save
|
||||||
|
pm2 startup
|
||||||
```
|
```
|
||||||
|
|
||||||
### Using Docker
|
### Docker
|
||||||
|
|
||||||
Create a `Dockerfile`:
|
|
||||||
|
|
||||||
```dockerfile
|
|
||||||
FROM node:20-alpine
|
|
||||||
|
|
||||||
WORKDIR /app
|
|
||||||
|
|
||||||
COPY package*.json ./
|
|
||||||
RUN npm ci --only=production
|
|
||||||
|
|
||||||
COPY . .
|
|
||||||
RUN npm run build
|
|
||||||
|
|
||||||
ENV NODE_ENV=production
|
|
||||||
ENV DATA_DIR=/app/data
|
|
||||||
|
|
||||||
EXPOSE 3000
|
|
||||||
|
|
||||||
CMD ["npm", "run", "start"]
|
|
||||||
```
|
|
||||||
|
|
||||||
Build and run:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
docker build -t 9router .
|
docker build -t 9router .
|
||||||
@@ -185,7 +406,17 @@ docker run -d \
|
|||||||
9router
|
9router
|
||||||
```
|
```
|
||||||
|
|
||||||
### Using with Reverse Proxy (Nginx)
|
### Environment Variables
|
||||||
|
|
||||||
|
| Variable | Default | Description |
|
||||||
|
|----------|---------|-------------|
|
||||||
|
| `JWT_SECRET` | Auto-generated | **MUST change in production!** |
|
||||||
|
| `DATA_DIR` | `~/.9router` | Database storage path |
|
||||||
|
| `INITIAL_PASSWORD` | `123456` | Dashboard login password |
|
||||||
|
| `NODE_ENV` | `development` | Set to `production` for deploy |
|
||||||
|
| `ENABLE_REQUEST_LOGS` | `false` | Debug request/response logs |
|
||||||
|
|
||||||
|
### Reverse Proxy (Nginx)
|
||||||
|
|
||||||
```nginx
|
```nginx
|
||||||
server {
|
server {
|
||||||
@@ -198,11 +429,7 @@ server {
|
|||||||
proxy_set_header Upgrade $http_upgrade;
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
proxy_set_header Connection 'upgrade';
|
proxy_set_header Connection 'upgrade';
|
||||||
proxy_set_header Host $host;
|
proxy_set_header Host $host;
|
||||||
proxy_set_header X-Real-IP $remote_addr;
|
|
||||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
||||||
proxy_set_header X-Forwarded-Proto $scheme;
|
|
||||||
proxy_cache_bypass $http_upgrade;
|
|
||||||
|
|
||||||
# SSE support
|
# SSE support
|
||||||
proxy_buffering off;
|
proxy_buffering off;
|
||||||
proxy_read_timeout 86400;
|
proxy_read_timeout 86400;
|
||||||
@@ -210,169 +437,228 @@ server {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## API Endpoints
|
</details>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 💡 Cost Optimization Tips
|
||||||
|
|
||||||
|
### Monthly Budget: $10-20/month
|
||||||
|
|
||||||
|
```
|
||||||
|
Strategy:
|
||||||
|
1. Use Gemini CLI free tier (180K/month) for quick tasks
|
||||||
|
2. Use Claude Code subscription quota fully (you already pay)
|
||||||
|
3. Fallback to GLM ($0.6/1M) when quota out
|
||||||
|
4. Emergency: MiniMax M2.1 ($0.20/1M) or iFlow (free)
|
||||||
|
|
||||||
|
Real example (100M tokens/month):
|
||||||
|
60M via Gemini CLI: $0 (free tier)
|
||||||
|
30M via Claude Code: $0 (subscription you already have)
|
||||||
|
8M via GLM: $4.80
|
||||||
|
2M via MiniMax: $0.40
|
||||||
|
Total: $5.20/month + existing subscriptions
|
||||||
|
```
|
||||||
|
|
||||||
|
### Quota Reset Strategy
|
||||||
|
|
||||||
|
```
|
||||||
|
Daily routine:
|
||||||
|
1. Morning: Fresh Claude Code quota (5h reset)
|
||||||
|
2. Afternoon: Switch to Gemini CLI (1K/day)
|
||||||
|
3. Evening: GLM daily quota (reset 10AM next day)
|
||||||
|
4. Late night: MiniMax (5h rolling) or iFlow (free)
|
||||||
|
|
||||||
|
→ Code 24/7 with minimal extra cost!
|
||||||
|
```
|
||||||
|
|
||||||
|
### Model Selection Guide
|
||||||
|
|
||||||
|
| Task | Best Model | Cost | Why |
|
||||||
|
|------|-----------|------|-----|
|
||||||
|
| Complex reasoning | `cc/claude-opus-4-5` | Subscription | Best quality |
|
||||||
|
| Fast coding | `cx/gpt-5.2-codex` | Subscription | Fastest Codex |
|
||||||
|
| Budget coding | `glm/glm-4.7` | $0.6/1M | Daily quota |
|
||||||
|
| Long context | `minimax/MiniMax-M2.1` | $0.20/1M | 1M context cheap |
|
||||||
|
| Emergency backup | `if/kimi-k2-thinking` | FREE | Unlimited |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Available Models
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><b>Subscription Models (Maximize First)</b></summary>
|
||||||
|
|
||||||
|
**Claude Code (`cc/`)** - Pro/Max:
|
||||||
|
- `cc/claude-opus-4-5-20251101` - Claude 4.5 Opus
|
||||||
|
- `cc/claude-sonnet-4-5-20250929` - Claude 4.5 Sonnet
|
||||||
|
- `cc/claude-haiku-4-5-20251001` - Claude 4.5 Haiku
|
||||||
|
|
||||||
|
**Codex (`cx/`)** - Plus/Pro:
|
||||||
|
- `cx/gpt-5.2-codex` - GPT 5.2 Codex
|
||||||
|
- `cx/gpt-5.2` - GPT 5.2
|
||||||
|
- `cx/gpt-5.1-codex-max` - GPT 5.1 Codex Max
|
||||||
|
- `cx/gpt-5.1-codex` - GPT 5.1 Codex
|
||||||
|
|
||||||
|
**Gemini CLI (`gc/`)** - FREE 180K/month:
|
||||||
|
- `gc/gemini-3-flash-preview` - Gemini 3 Flash Preview
|
||||||
|
- `gc/gemini-3-pro-preview` - Gemini 3 Pro Preview
|
||||||
|
- `gc/gemini-2.5-pro` - Gemini 2.5 Pro
|
||||||
|
- `gc/gemini-2.5-flash` - Gemini 2.5 Flash
|
||||||
|
|
||||||
|
**GitHub Copilot (`gh/`)** - Subscription:
|
||||||
|
- `gh/gpt-5` - GPT-5
|
||||||
|
- `gh/gpt-5.1-codex-max` - GPT-5.1 Codex Max
|
||||||
|
- `gh/claude-4.5-sonnet` - Claude 4.5 Sonnet
|
||||||
|
- `gh/gemini-3-pro` - Gemini 3 Pro
|
||||||
|
|
||||||
|
**Antigravity (`ag/`)** - Google account:
|
||||||
|
- `ag/gemini-3-pro-high` - Gemini 3 Pro High
|
||||||
|
- `ag/claude-sonnet-4-5` - Claude Sonnet 4.5
|
||||||
|
- `ag/claude-opus-4-5-thinking` - Claude Opus 4.5
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><b>Cheap Models (Backup)</b></summary>
|
||||||
|
|
||||||
|
**GLM (`glm/`)** - $0.6/$2.2 per 1M:
|
||||||
|
- `glm/glm-4.7` - GLM 4.7 (daily reset 10AM)
|
||||||
|
- `glm/glm-4.6v` - GLM 4.6V Vision
|
||||||
|
|
||||||
|
**MiniMax (`minimax/`)** - $0.20/$1.00 per 1M:
|
||||||
|
- `minimax/MiniMax-M2.1` - MiniMax M2.1 (5h reset)
|
||||||
|
|
||||||
|
**Kimi (`kimi/`)** - $9/month (10M tokens):
|
||||||
|
- `kimi/kimi-latest` - Kimi Latest
|
||||||
|
|
||||||
|
**OpenRouter (`openrouter/`)** - Passthrough pricing:
|
||||||
|
- `openrouter/auto` - Auto (Best Available)
|
||||||
|
- Any OpenRouter model ID supported
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><b>FREE Models (Emergency)</b></summary>
|
||||||
|
|
||||||
|
**iFlow (`if/`)** - 8 models FREE:
|
||||||
|
- `if/kimi-k2-thinking` - Kimi K2 Thinking
|
||||||
|
- `if/kimi-k2` - Kimi K2
|
||||||
|
- `if/qwen3-coder-plus` - Qwen3 Coder Plus
|
||||||
|
- `if/glm-4.7` - GLM 4.7
|
||||||
|
- `if/minimax-m2` - MiniMax M2
|
||||||
|
- `if/deepseek-r1` - DeepSeek R1
|
||||||
|
- `if/deepseek-v3.2-chat` - DeepSeek V3.2 Chat
|
||||||
|
- `if/deepseek-v3.2-reasoner` - DeepSeek V3.2 Reasoner
|
||||||
|
|
||||||
|
**Qwen (`qw/`)** - 3 models FREE:
|
||||||
|
- `qw/qwen3-coder-plus` - Qwen3 Coder Plus
|
||||||
|
- `qw/qwen3-coder-flash` - Qwen3 Coder Flash
|
||||||
|
- `qw/vision-model` - Qwen3 Vision
|
||||||
|
|
||||||
|
**Kiro (`kr/`)** - 2 models FREE:
|
||||||
|
- `kr/claude-sonnet-4.5` - Claude Sonnet 4.5
|
||||||
|
- `kr/claude-haiku-4.5` - Claude Haiku 4.5
|
||||||
|
|
||||||
|
</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 → glm/glm-4.7 → minimax/MiniMax-M2.1`
|
||||||
|
|
||||||
|
**OAuth token expired**
|
||||||
|
- Auto-refreshed by 9Router
|
||||||
|
- If issues persist: Dashboard → Provider → Reconnect
|
||||||
|
|
||||||
|
**High costs**
|
||||||
|
- Check usage stats in Dashboard
|
||||||
|
- Switch primary model to GLM/MiniMax
|
||||||
|
- Use free tier (Gemini CLI, iFlow) for non-critical tasks
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🛠️ Tech Stack
|
||||||
|
|
||||||
|
- **Runtime**: Node.js 20+
|
||||||
|
- **Framework**: Next.js 15
|
||||||
|
- **UI**: React 19 + Tailwind CSS 4
|
||||||
|
- **Database**: LowDB (JSON file-based)
|
||||||
|
- **Streaming**: Server-Sent Events (SSE)
|
||||||
|
- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 API Reference
|
||||||
|
|
||||||
### Chat Completions
|
### Chat Completions
|
||||||
```
|
|
||||||
POST /v1/chat/completions
|
|
||||||
```
|
|
||||||
OpenAI-compatible chat completions endpoint. Supports all providers with automatic format translation.
|
|
||||||
|
|
||||||
### Models List
|
```bash
|
||||||
|
POST http://localhost:20128/v1/chat/completions
|
||||||
|
Authorization: Bearer your-api-key
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"model": "cc/claude-opus-4-5-20251101",
|
||||||
|
"messages": [
|
||||||
|
{"role": "user", "content": "Write a function to..."}
|
||||||
|
],
|
||||||
|
"stream": true
|
||||||
|
}
|
||||||
```
|
```
|
||||||
GET /v1/models
|
|
||||||
|
### List Models
|
||||||
|
|
||||||
|
```bash
|
||||||
|
GET http://localhost:20128/v1/models
|
||||||
|
Authorization: Bearer your-api-key
|
||||||
|
|
||||||
|
→ Returns all models + combos in OpenAI format
|
||||||
```
|
```
|
||||||
Returns available models in OpenAI-compatible format, including combos.
|
|
||||||
|
|
||||||
### Responses API (Codex)
|
### Responses API (Codex)
|
||||||
```
|
|
||||||
POST /v1/responses
|
|
||||||
POST /codex/responses
|
|
||||||
```
|
|
||||||
OpenAI Responses API endpoint for Codex CLI compatibility.
|
|
||||||
|
|
||||||
## CLI Integration Examples
|
|
||||||
|
|
||||||
### Claude Code
|
|
||||||
```bash
|
|
||||||
# Set your 9router endpoint
|
|
||||||
export ANTHROPIC_BASE_URL="http://your-server:3000/v1"
|
|
||||||
|
|
||||||
# Use with Claude Code
|
|
||||||
claude
|
|
||||||
```
|
|
||||||
|
|
||||||
### Codex CLI
|
|
||||||
```bash
|
|
||||||
# Configure Codex to use 9router
|
|
||||||
export OPENAI_BASE_URL="http://your-server:3000"
|
|
||||||
|
|
||||||
# Use Codex
|
|
||||||
codex
|
|
||||||
```
|
|
||||||
|
|
||||||
### Cursor IDE
|
|
||||||
Configure in Cursor settings:
|
|
||||||
- API Base URL: `http://your-server:3000/v1`
|
|
||||||
- Use your generated API key from the dashboard
|
|
||||||
|
|
||||||
## Debugging
|
|
||||||
|
|
||||||
### Enable Request Logging
|
|
||||||
|
|
||||||
Set the environment variable to capture full request/response data:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
ENABLE_REQUEST_LOGS=true npm run start
|
POST http://localhost:20128/v1/responses
|
||||||
|
POST http://localhost:20128/codex/responses
|
||||||
```
|
```
|
||||||
|
|
||||||
Logs are saved to the `logs/` directory with the format:
|
---
|
||||||
```
|
|
||||||
logs/
|
|
||||||
└── {sourceFormat}_{targetFormat}_{model}_{timestamp}/
|
|
||||||
├── 1_client_raw_request.json
|
|
||||||
├── 2_raw_request.json
|
|
||||||
├── 3_converted_request.json
|
|
||||||
├── 4_provider_response.txt
|
|
||||||
├── 5_converted_response.txt
|
|
||||||
└── 6_error.json (if error occurred)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Console Debug Logging
|
## 🤝 Contributing
|
||||||
|
|
||||||
The application includes debug logging for troubleshooting provider issues. Check your container/server logs for `[DEBUG]` prefixed messages.
|
1. Fork → Branch → Commit → Push → PR
|
||||||
|
2. See [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||||
|
|
||||||
## Data Location
|
---
|
||||||
|
|
||||||
User data stored at:
|
## 📧 Support
|
||||||
- **macOS/Linux**: `~/.9router/db.json`
|
|
||||||
- **Windows**: `%APPDATA%/9router/db.json`
|
|
||||||
- **Custom**: Set `DATA_DIR` environment variable
|
|
||||||
|
|
||||||
## Development
|
- **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)
|
||||||
|
|
||||||
### Setup
|
---
|
||||||
```bash
|
|
||||||
# Clone repository
|
|
||||||
git clone https://github.com/yourusername/9router.git
|
|
||||||
cd 9router
|
|
||||||
|
|
||||||
# Install dependencies
|
## 🙏 Acknowledgments
|
||||||
npm install
|
|
||||||
|
|
||||||
# Start development server
|
Special thanks to **CLIProxyAPI** - the original Go implementation that inspired this JavaScript port.
|
||||||
npm run dev
|
|
||||||
```
|
|
||||||
|
|
||||||
### Project Structure
|
---
|
||||||
```
|
|
||||||
9router/
|
|
||||||
├── src/
|
|
||||||
│ ├── app/ # Next.js app (dashboard & API routes)
|
|
||||||
│ ├── lib/ # Core libraries (DB, OAuth, etc.)
|
|
||||||
│ ├── shared/ # Shared components & utilities
|
|
||||||
│ └── sse/ # SSE streaming handlers
|
|
||||||
├── open-sse/ # Core proxy engine (translator, handlers)
|
|
||||||
│ ├── translator/ # Format translators (request/response)
|
|
||||||
│ │ ├── request/ # Request translators
|
|
||||||
│ │ └── response/ # Response translators
|
|
||||||
│ ├── handlers/ # Request handlers
|
|
||||||
│ ├── executors/ # Provider-specific executors
|
|
||||||
│ ├── services/ # Core services (fallback, token refresh)
|
|
||||||
│ └── config/ # Provider configurations
|
|
||||||
├── tester/ # Testing utilities
|
|
||||||
└── public/ # Static assets
|
|
||||||
```
|
|
||||||
|
|
||||||
## Tech Stack
|
## 📄 License
|
||||||
|
|
||||||
| Layer | Technology |
|
|
||||||
|-------|------------|
|
|
||||||
| **Runtime** | Node.js 20+ / Bun |
|
|
||||||
| **Framework** | Next.js 15 |
|
|
||||||
| **Dashboard** | React 19 + Tailwind CSS 4 |
|
|
||||||
| **Database** | LowDB (JSON file-based) |
|
|
||||||
| **CLI** | Node.js CLI with auto-update |
|
|
||||||
| **Streaming** | Server-Sent Events (SSE) |
|
|
||||||
| **Auth** | OAuth 2.0 (PKCE) + API Keys |
|
|
||||||
| **Deployment** | Standalone / VPS / Docker |
|
|
||||||
| **State Management** | Zustand |
|
|
||||||
|
|
||||||
### Core Libraries
|
|
||||||
- **lowdb**: Lightweight JSON database
|
|
||||||
- **undici**: High-performance HTTP client
|
|
||||||
- **uuid**: Unique identifier generation
|
|
||||||
- **jose**: JWT handling
|
|
||||||
- **bcryptjs**: Password hashing
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
|
|
||||||
### "The language model did not provide any assistant messages"
|
|
||||||
|
|
||||||
This error typically means the upstream provider returned an empty or malformed response. Check:
|
|
||||||
1. Your provider credentials are valid and not rate-limited
|
|
||||||
2. The model name is correct (e.g., `ag/gemini-3-pro-high`)
|
|
||||||
3. Enable debug logging to see the actual provider response
|
|
||||||
|
|
||||||
### OAuth Token Expired
|
|
||||||
|
|
||||||
OAuth tokens are automatically refreshed. If you see authentication errors:
|
|
||||||
1. Re-authenticate via the dashboard
|
|
||||||
2. Check if the provider's OAuth credentials are still valid
|
|
||||||
|
|
||||||
### Rate Limiting
|
|
||||||
|
|
||||||
9Router implements automatic fallback when rate limits are hit:
|
|
||||||
1. Add multiple accounts for the same provider
|
|
||||||
2. Configure account priorities in the dashboard
|
|
||||||
3. Use combos to fallback between different providers
|
|
||||||
|
|
||||||
## Acknowledgments
|
|
||||||
|
|
||||||
Special thanks to:
|
|
||||||
|
|
||||||
- **CLIProxyAPI**: The original Go implementation that inspired this project. 9Router is a JavaScript port with additional features and web dashboard.
|
|
||||||
|
|
||||||
## License
|
|
||||||
|
|
||||||
MIT License - see [LICENSE](LICENSE) for details.
|
MIT License - see [LICENSE](LICENSE) for details.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<div align="center">
|
||||||
|
<sub>Built with ❤️ for developers maximizing AI value</sub>
|
||||||
|
</div>
|
||||||
|
|||||||
Binary file not shown.
|
Before Width: | Height: | Size: 292 KiB After Width: | Height: | Size: 362 KiB |
Reference in New Issue
Block a user