diff --git a/README.md b/README.md index 4fdf43f..31ca660 100644 --- a/README.md +++ b/README.md @@ -1,179 +1,400 @@ -# 9ROUTER - AI Proxy +
+ 9Router Dashboard + + # 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) +
-> 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 + +
+Subscription Providers (Maximize Value) + +### 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 +``` + +
+ +
+Cheap Providers (Backup) + +### 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! + +
+ +
+FREE Providers (Emergency Backup) + +### 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 +``` + +
+ +
+Combo Examples + +### 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! +``` + +
+ +
+CLI Integration + +### 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 +``` + +
+ +
+Deployment + +### 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 +
+ +--- + +## 💡 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 + +
+Subscription Models (Maximize First) + +**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 + +
+ +
+Cheap Models (Backup) + +**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 + +
+ +
+FREE Models (Emergency) + +**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 + +
+ +--- + +## 🐛 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. + +--- + +
+ Built with ❤️ for developers maximizing AI value +
diff --git a/images/9router.png b/images/9router.png index d8520db..861a863 100644 Binary files a/images/9router.png and b/images/9router.png differ