9Router Plus - Enhanced AI Router

Never stop coding. Auto-route to FREE & cheap AI models with smart fallback.

Connect All AI Code Tools (Claude Code, Cursor, Antigravity, Copilot, Codex, Gemini, OpenCode, Cline, OpenClaw...) to 40+ AI Providers & 100+ Models.

🚀 Quick Start • 💡 Features • 📖 Setup • 🔄 vs 9Router

Based on 9Router by decolua

🔄 9Router Plus vs 9Router

| Feature | 9Router | 9Router Plus | |---------|---------|--------------| | Core Routing | ✅ Smart fallback | ✅ Smart fallback | | Providers | 40+ providers | 40+ providers | | Translation Layer | OpenAI ↔ Claude | ✅ OpenAI ↔ Claude ↔ Gemini | | Morph Proxy | ❌ | ✅ Full morphllm namespace (apply, compact, embeddings, rerank, warpgrep) | | Morph Key Rotation | ❌ | ✅ Round-robin key failover + auto-exhausted detection | | Morph Usage Dashboard | ❌ | ✅ Credits tracking, capability breakdown, auto-compact stats | | Tab-Based UI | ❌ | ✅ Main/Cloud tabs | | Security Hardening | Basic | ✅ 12 critical bug fixes + SSRF protection | | Real-Time Monitoring | Basic | ✅ Live status + logs viewer | | Auto-Restart | ❌ | ✅ Config change detection | | Responsive Design | Basic | ✅ Mobile/Tablet/Desktop optimized |

Key Enhancements:

• 🔄 Enhanced Translation - Full OpenAI ↔ Claude ↔ Gemini format support
• 🎨 Modern UI - Tab-based interface with glassmorphism design
• 🔒 Security First - Fixed 12 critical bugs, added SSRF protection
• 📊 Real-Time Monitoring - Live status updates and log streaming
• 📱 Responsive - Optimized for all screen sizes
• 🔀 Morph Proxy - Built-in proxy ke Morph API (api.morphllm.com) dengan namespace morphllm, round-robin key rotation, usage tracking, dan dedicated dashboard

🤔 Why 9Router Plus?

Stop wasting money and hitting limits:

• ❌ Subscription quota expires unused every month
• ❌ Rate limits stop you mid-coding
• ❌ Expensive APIs ($20-50/month per provider)
• ❌ Manual switching between providers

9Router Plus solves this:

• ✅ 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, Gemini CLI, Cursor, Cline, any CLI tool
• ✅ Enhanced Security - 12 critical bug fixes + SSRF protection + audit logging

🔄 How It Works

┌─────────────┐
│  Your CLI   │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
│   Tool      │
└──────┬──────┘
       │ http://localhost:20128/v1
       ↓
┌─────────────────────────────────────────┐
│        9Router Plus (Smart Router)      │
│  • Format translation (OpenAI ↔ Claude ↔ Gemini) │
│  • Quota tracking                       │
│  • Auto token refresh                   │
└──────┬──────────────────────────────────┘
       │
       ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
       │   ↓ quota exhausted
       ├─→ [Tier 2: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
       │   ↓ budget limit
       └─→ [Tier 3: FREE] iFlow, Qwen, Kiro (unlimited)

Result: Never stop coding, minimal cost

⚡ Quick Start

1. Run directly with npx

npx 9router-plus

Or install globally:

npm install -g 9router-plus
9router-plus

Or install locally in a project:

mkdir 9router-plus-app
cd 9router-plus-app
npm init -y
npm install 9router-plus
npx 9router-plus

2. Start 9Router Plus

You can also run the underlying script directly if needed:

PORT=20128 HOSTNAME=0.0.0.0 node ./node_modules/9router-plus/scripts/start.js

Open:

• Dashboard: http://localhost:20128/dashboard
• OpenAI-compatible API: http://localhost:20128/v1

Notes:

• This package is published on npm and now exposes the 9router-plus CLI for both npx and global install.
• If you need custom environment variables, create a .env in your app directory before starting.
• Default port is 20128; override with PORT=3000, 9router-plus --port 3000, or 9router-plus -p 3000.
• Startup now prints the exact Dashboard and API URLs, plus the runtime mode being used.

3. Connect a FREE provider (no signup needed):

Dashboard → Providers → Connect Claude Code or Antigravity → OAuth login → Done!

3. Use in your CLI tool:

Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
  Endpoint: http://localhost:20128/v1
  API Key: [copy from dashboard]
  Model: if/kimi-k2-thinking

That's it! Start coding with FREE AI models.

Start command examples:

npx 9router-plus
# or
9router-plus
# or
9router-plus --port 3000
# or
PORT=20128 HOSTNAME=0.0.0.0 node ./node_modules/9router-plus/scripts/start.js

If port 20128 is already in use, 9Router Plus will print a clear error showing:

• which port is blocked
• the Dashboard and API URLs that would have used that port
• commands to free the port
• how to rerun on another port with --port 3000

If the package cannot find a runnable runtime, 9Router Plus will also explain whether the standalone build is missing or whether you are starting it from the wrong directory.

If you want to free the default port manually:

fuser -k 20128/tcp
# fallback:
lsof -ti :20128 | xargs -r kill -9

Default URLs:

• Dashboard: http://localhost:20128/dashboard
• OpenAI-compatible API: http://localhost:20128/v1

🎥 Video Tutorial

📺 Complete Setup Guide - 9Router + Claude Code FREE

🎬 Watch the complete step-by-step tutorial:

• ✅ 9Router installation & setup
• ✅ FREE Claude Sonnet 4.5 configuration
• ✅ Claude Code integration
• ✅ Live coding demonstration

⏱️ Duration: 20 minutes | 👥 By: Developer Community

▶️ Watch on YouTube

🛠️ Supported CLI Tools

9Router works seamlessly with all major AI coding tools:

🌐 Supported Providers

🔐 OAuth Providers

🆓 Free Providers

🔑 API Key Providers (40+)

💡 Key Features

| Feature | What It Does | Why It Matters | |---------|--------------|----------------| | 🎯 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 seamless | 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 |

🎯 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 ↔ 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

💰 Pricing at a Glance

| Tier | Provider | Cost | Quota Reset | Best For | |------|----------|------|-------------|----------| | 💳 SUBSCRIPTION | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | | | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | | | Gemini CLI | FREE | 180K/mo + 1K/day | Everyone! | | | GitHub Copilot | $10-19/mo | Monthly | GitHub users | | 💰 CHEAP | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | | | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | | | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | | 🆓 FREE | iFlow | $0 | Unlimited | 8 models free | | | Qwen | $0 | Unlimited | 3 models free | | | Kiro | $0 | Unlimited | Claude free |

💡 Pro Tip: Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost!

📊 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-6        (use subscription fully)
  2. glm/glm-4.7               (cheap backup when quota out)
  3. if/kimi-k2-thinking       (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. gc/gemini-3-flash         (180K free/month)
  2. if/kimi-k2-thinking       (unlimited free)
  3. qw/qwen3-coder-plus       (unlimited free)

Monthly cost: $0
Quality: Production-ready models

Case 3: "I need 24/7 coding, no interruptions"

Problem: Deadlines, can't afford downtime

Solution:

Combo: "always-on"
  1. cc/claude-opus-4-6        (best quality)
  2. cx/gpt-5.2-codex          (second subscription)
  3. glm/glm-4.7               (cheap, resets daily)
  4. minimax/MiniMax-M2.1      (cheapest, 5h reset)
  5. if/kimi-k2-thinking       (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. if/glm-4.7                (unlimited free)
  2. if/minimax-m2.1           (unlimited free)
  3. if/kimi-k2-thinking       (unlimited free)

Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...

❓ Frequently Asked Questions

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.

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.

Yes! Providers marked as FREE (iFlow, Kiro, Qwen) are genuinely unlimited with no hidden charges.

These are free services offered by those respective companies:

• iFlow: Free unlimited access to 8+ models via OAuth
• Kiro: Free unlimited Claude models via AWS Builder ID
• Qwen: Free unlimited access to Qwen models via device auth

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.

Note: Some subscription providers (Antigravity, GitHub Copilot) may have free preview periods that could become paid later, but this would be clearly announced by those providers, not 9Router.

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!

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.

📖 Setup Guide

Claude Code (Pro/Max)

Dashboard → Providers → Connect Claude Code
→ OAuth login → Auto token refresh
→ 5-hour + weekly quota tracking

Models:
  cc/claude-opus-4-6
  cc/claude-sonnet-4-5-20250929
  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)

Dashboard → Providers → Connect Codex
→ OAuth login (port 1455)
→ 5-hour + weekly reset

Models:
  cx/gpt-5.2-codex
  cx/gpt-5.1-codex-max

Gemini CLI (FREE 180K/month!)

Dashboard → Providers → Connect Gemini CLI
→ Google OAuth
→ 180K completions/month + 1K/day

Models:
  gc/gemini-3-flash-preview
  gc/gemini-2.5-pro

Best Value: Huge free tier! Use this before paid tiers.

GitHub Copilot

Dashboard → Providers → Connect GitHub
→ OAuth via GitHub
→ Monthly reset (1st of month)

Models:
  gh/gpt-5
  gh/claude-4.5-sonnet
  gh/gemini-3-pro

GLM-4.7 (Daily reset, $0.6/1M)

1. Sign up: Zhipu AI
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
2. Get API key
3. Dashboard → Add API Key

Use: minimax/MiniMax-M2.1

Pro Tip: Cheapest option for long context (1M tokens)!

Kimi K2 ($9/month flat)

1. Subscribe: Moonshot AI
2. Get API key
3. Dashboard → Add API Key

Use: kimi/kimi-latest

Pro Tip: Fixed $9/month for 10M tokens = $0.90/1M effective cost!

iFlow (8 FREE models)

Dashboard → Connect iFlow
→ iFlow OAuth login
→ Unlimited usage

Models:
  if/kimi-k2-thinking
  if/qwen3-coder-plus
  if/glm-4.7
  if/minimax-m2
  if/deepseek-r1

Qwen (3 FREE models)

Dashboard → Connect Qwen
→ Device code authorization
→ Unlimited usage

Models:
  qw/qwen3-coder-plus
  qw/qwen3-coder-flash

Kiro (Claude FREE)

Dashboard → Connect Kiro
→ AWS Builder ID, AWS IAM Identity Center, Google, GitHub
→ Unlimited usage

Models:
  kr/claude-sonnet-4.5
  kr/claude-haiku-4.5

Example 1: Maximize Subscription → Cheap Backup

Dashboard → Combos → Create New

Name: premium-coding
Models:
  1. cc/claude-opus-4-6 (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: Free-Only (Zero Cost)

Name: free-combo
Models:
  1. gc/gemini-3-flash-preview (180K free/month)
  2. if/kimi-k2-thinking (unlimited)
  3. qw/qwen3-coder-plus (unlimited)

Cost: $0 forever!

Cursor IDE

Settings → Models → Advanced:
  OpenAI API Base URL: http://localhost:20128/v1
  OpenAI API Key: [from 9router dashboard]
  Model: cc/claude-opus-4-6

Or use combo: premium-coding

Claude Code

Edit ~/.claude/config.json:

{
  "anthropic_api_base": "http://localhost:20128/v1",
  "anthropic_api_key": "your-9router-api-key"
}

Codex CLI

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:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "9router/if/glm-4.7"
      }
    }
  },
  "models": {
    "providers": {
      "9router": {
        "baseUrl": "http://127.0.0.1:20128/v1",
        "apiKey": "sk_9router",
        "api": "openai-completions",
        "models": [
          {
            "id": "if/glm-4.7",
            "name": "glm-4.7"
          }
        ]
      }
    }
  }
}

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-6

VPS Deployment

# 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

# Build image (from repository root)
docker build -t 9router .

# Run container (command used in current setup)
docker run -d \
  --name 9router \
  -p 20128:20128 \
  --env-file /root/dev/9router/.env \
  -v 9router-data:/app/data \
  -v 9router-usage:/root/.9router \
  9router

Portable command (if you are already at repository root):

docker run -d \
  --name 9router \
  -p 20128:20128 \
  --env-file ./.env \
  -v 9router-data:/app/data \
  -v 9router-usage:/root/.9router \
  9router

Container defaults:

• PORT=20128
• HOSTNAME=0.0.0.0

Useful commands:

docker logs -f 9router
docker restart 9router
docker stop 9router && docker rm 9router

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | JWT_SECRET | 9router-default-secret-change-me | JWT signing secret for dashboard auth cookie (change in production) | | INITIAL_PASSWORD | 123456 | First login password when no saved hash exists | | DATA_DIR | ~/.9router | Main app database location (db.json) | | 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 | | REDIS_URL, REDIS_HOST, REDIS_PORT, REDIS_DB, REDIS_USERNAME, REDIS_PASSWORD, REDIS_TLS, REDIS_CLIENT_NAME, REDIS_CONNECT_TIMEOUT_MS | empty | Optional Redis backend for hot quota/account state; if unset, local fallback is used |

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.

🔒 Security Configuration

IP Whitelist

By default, dashboard access from localhost and Docker networks is allowed. Configure custom IPs in Settings or data/db.json:

{
  "ipWhitelist": ["127.0.0.1", "::1", "172.17.0.0/16", "10.0.0.0/8"]
}

Supports:

• Exact IPs: 127.0.0.1, ::1
• CIDR ranges: 172.17.0.0/16, 10.0.0.0/8

Trusted Proxy Mode

If behind nginx/Cloudflare, enable trusted proxy to read X-Forwarded-For:

{
  "trustedProxyEnabled": true
}

⚠️ Only enable if you trust the proxy. Malicious proxies can spoof IPs.

Audit Logging

Security events are logged to data/audit.log (default: enabled, 10MB max):

{
  "auditLogEnabled": true,
  "auditLogMaxSize": 10485760
}

Events logged:

• Login attempts (success/failure)
• Auth bypass attempts
• Rate limit exceeded
• Tunnel access attempts

Rate Limiting

Login endpoint: 5 attempts per IP per 15 minutes. Automatic cleanup every 5 minutes.

See docs/security/DASHBOARD_AUTH.md for complete security documentation.

Runtime Files and Storage

• Main app state: ${DATA_DIR}/db.json (providers, combos, aliases, keys, settings), managed by src/lib/localDb.js.
• Usage history and logs: ~/.9router/usage.json and ~/.9router/log.txt, managed by src/lib/usageDb.js.
• Optional request/translator logs: <repo>/logs/... when ENABLE_REQUEST_LOGS=true.
• Usage storage currently follows ~/.9router path logic and is independent from DATA_DIR.
• Hot quota/account state can optionally use Redis when REDIS_URL or REDIS_HOST is configured; otherwise the app keeps the current local fallback path.

📊 Available Models

Claude Code (cc/) - Pro/Max:

• cc/claude-opus-4-6
• cc/claude-sonnet-4-5-20250929
• cc/claude-haiku-4-5-20251001

Codex (cx/) - Plus/Pro:

• cx/gpt-5.2-codex
• cx/gpt-5.1-codex-max

Gemini CLI (gc/) - FREE:

• gc/gemini-3-flash-preview
• gc/gemini-2.5-pro

GitHub Copilot (gh/):

• gh/gpt-5
• gh/claude-4.5-sonnet

GLM (glm/) - $0.6/1M:

• glm/glm-4.7

MiniMax (minimax/) - $0.2/1M:

• minimax/MiniMax-M2.1

iFlow (if/) - FREE:

• if/kimi-k2-thinking
• if/qwen3-coder-plus
• if/deepseek-r1

Qwen (qw/) - FREE:

• qw/qwen3-coder-plus
• qw/qwen3-coder-flash

Kiro (kr/) - FREE:

• kr/claude-sonnet-4.5
• kr/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-4-6 → glm/glm-4.7 → if/kimi-k2-thinking

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

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: LowDB (JSON file-based)
• Streaming: Server-Sent Events (SSE)
• Auth: OAuth 2.0 (PKCE) + JWT + API Keys

📝 API Reference

Chat Completions

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

GET http://localhost:20128/v1/models
Authorization: Bearer your-api-key

→ Returns all models + combos in OpenAI format

📧 Support

• Website: 9router.com
• GitHub: github.com/decolua/9router
• Issues: github.com/decolua/9router/issues

👥 Contributors

Thanks to all contributors who helped make 9Router better!

📊 Star Chart

🔀 Forks

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

Special thanks to CLIProxyAPI - the original Go implementation that inspired this JavaScript port.

📄 License

MIT License - see LICENSE for details.