marketing-shibata50/9router
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update Readme

Browse source
This commit is contained in:
decolua 2026-01-31 13:44:19 +07:00
parent 8897df5036
commit 814e02ae31
2 changed files with 580 additions and 294 deletions
Download patch file Download diff file Expand all files Collapse all files

874
README.md
View file

@ -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**
[![npm](https://img.shields.io/npm/v/9router.svg)](https://www.npmjs.com/package/9router)
[![Downloads](https://img.shields.io/npm/dm/9router.svg)](https://www.npmjs.com/package/9router)
[![License](https://img.shields.io/npm/l/9router.svg)](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?
[![npm version](https://img.shields.io/npm/v/9router.svg)](https://www.npmjs.com/package/9router)
[![Downloads](https://img.shields.io/npm/dm/9router.svg)](https://www.npmjs.com/package/9router)
[![License](https://img.shields.io/npm/l/9router.svg)](https://github.com/yourusername/9router/blob/main/LICENSE)
Stop wasting your AI subscriptions and paying full price:
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 Dashboard](./images/9router.png)
**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:**
- **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
## ⚡ Quick Start
## Recent Updates
### 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
**Install globally:**
```bash
# Install globally
npm install -g 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
9router # Start server with default settings
9router --port 8080 # Custom port
9router --no-browser # Don't open browser
9router --skip-update # Skip auto-update check
9router --help # Show help
Dashboard → Providers → Connect Claude Code
→ OAuth login → Auto token refresh
→ 5-hour + weekly quota tracking
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
### 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)
### OpenAI Codex (Plus/Pro)
```bash
# Clone the repository
git clone https://github.com/yourusername/9router.git
cd 9router
Dashboard → Providers → Connect Codex
→ OAuth login (port 1455)
→ 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 run build
# Set environment variables
export JWT_SECRET="your-secure-random-secret"
export INITIAL_PASSWORD="your-secure-password"
# Configure
export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/9router"
export NODE_ENV="production"
# Build the application
npm run build
# Start the server
# Start
npm run start
# Or use PM2
npm install -g pm2
pm2 start npm --name 9router -- start
pm2 save
pm2 startup
```
### Using 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:
### Docker
```bash
docker build -t 9router .
@ -185,7 +406,17 @@ docker run -d \
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
server {
@ -198,11 +429,7 @@ server {
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
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
proxy_buffering off;
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
```
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)
```
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
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:
- **macOS/Linux**: `~/.9router/db.json`
- **Windows**: `%APPDATA%/9router/db.json`
- **Custom**: Set `DATA_DIR` environment variable
## 📧 Support
## 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
npm install
## 🙏 Acknowledgments
# Start development server
npm run dev
```
Special thanks to **CLIProxyAPI** - the original Go implementation that inspired this JavaScript port.
### 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
| 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
## 📄 License
MIT License - see [LICENSE](LICENSE) for details.
---
<div align="center">
<sub>Built with ❤️ for developers maximizing AI value</sub>
</div>

BIN
images/9router.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 292 KiB

After

Width:  |  Height:  |  Size: 362 KiB

Before After
Before After