🚀 SRouter

Coding with AI agents (Claude Code, Cursor, Windsurf, Cline) is transformative, but developers constantly run into walls:

┌─────────────────────────────────────────────────────────────────────────────┐
│                       Your Coding Agents & IDEs                             │
│       (Claude Code, Cursor, Windsurf, Cline, Roo Code, Codex, Aider)        │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │ http://localhost:20268/v1
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         SRouter Smart AI Gateway                            │
│  • Complexity Gate (System One: routes simple prompts fast, complex deep)  │
│  • Prompt Compressor & Token Saver (compacts tool results, trims context)  │
│  • Protocol Translation (OpenAI ↔ Anthropic Messages ↔ Gemini ↔ Ollama)     │
│  • Per-Key Rate Tracking (RPM / RPD / TPM / TPD tracking with auto-reset)   │
│  • Local AES-256-GCM Key Vault & SQLite Persistence                        │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │
        ┌──────────────────────────────┼──────────────────────────────┐
        ▼                              ▼                              ▼
 ┌──────────────────────────┐   ┌──────────────────────────┐   ┌──────────────────────────┐
 │  Tier 1: Sub / Fast Key  │   │  Tier 2: Generous Quota  │   │ Tier 3: 100% Free / Anon │
 │  • Google Gemini 2.5     │   │  • Mistral / Codestral   │   │  • Kilo Gateway (No Key) │
 │  • Groq (Llama 3.3 70B)  │──►│  • Zhipu GLM-4 / CogView │──►│  • OpenCode Free (No Key)│
 │  • Pollinations (Free)   │   │  • Cloudflare Workers AI │   │  • OVH Endpoints (No Key)│
 │  • OpenRouter / DeepSeek │   │  • Cohere / NVIDIA NIM   │   │  • LLM7 / AI Horde       │
 └──────────────────────────┘   └──────────────────────────┘   └──────────────────────────┘

When a request arrives, SRouter evaluates model health, current RPM/RPD limits, and complexity. If an upstream provider returns 429 Too Many Requests or 5xx Server Error, the key enters a temporary cooldown, and SRouter instantly retries the next best model in your fallback chain.

Choose your preferred way to run SRouter:

Run SRouter anywhere Node 20+ is installed without cloning the repository:

# Install once
npm install -g @baiibayu/srouter
srouter

# Or run directly with npx — no install needed
npx @baiibayu/srouter

The Web Dashboard opens automatically at http://localhost:20268.

# 1. Clone the repository
git clone https://github.com/baiibayu/srouter.git
cd srouter

# 2. Copy environment file and start container
cp .env.example .env
docker compose up -d

# Or run directly via GHCR without cloning:
# docker run -d --name srouter -p 20268:20268 -v srouter-data:/app/server/data ghcr.io/baiibayu/srouter:latest

• Dashboard: http://localhost:20268
• OpenAI Endpoint: http://localhost:20268/v1

Prefer a native application with a system tray menu?

1. Go to Releases.
2. Download the installer:
   • Windows: SRouter-Setup-x.x.x.exe
   • macOS: SRouter-x.x.x-arm64.dmg (Apple Silicon) or x64.dmg (Intel).
3. Launch the app. SRouter runs in your menu bar / system tray with a native popover showing live request stats and your unified API key.

# 1. Clone repository
git clone https://github.com/baiibayu/srouter.git
cd srouter

# 2. Install dependencies & run database migrations
npm install
npm run db:migration:up

# 3. Start development server (Server :20268 + Client :5173 with HMR)
npm run dev

Open your browser and navigate to: 👉 http://localhost:20268 (Web Dashboard).

SRouter includes automated configuration generators (setup-*) that inspect your live model catalog, back up existing settings, and write the exact configuration your tool expects:

Claude Code	Cursor	Codex CLI	Cline	Continue	Aider
OpenCode	Gemini CLI	Roo Code	Kilo Code	Zed	JetBrains
Goose	Qwen Code	Crush	Factory Droid	OpenClaw	DeepSeek Harness
Oh My Pi	Hermes	Pi	AtomCode	Reasonix	Zcode

# Automatic setup with your SRouter instance
srouter setup-claude --url http://localhost:20268 --api-key <your-unified-key>

Not installed? Run the same command with npx @baiibayu/srouter in place of srouter.

# Injects credentials directly into child process without writing keys to disk
srouter launch

{
  "openai.baseUrl": "http://localhost:20268/v1",
  "openai.apiKey": "srouter-your-unified-key",
  "openai.model": "auto"
}

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:20268/v1",
    api_key="srouter-your-unified-key",
)

response = client.chat.completions.create(
    model="auto:smart",  # or "auto:fast", "auto", or specific model ID
    messages=[{"role": "user", "content": "Explain async/await in TypeScript."}],
)

print(response.choices[0].message.content)
print("Served via:", response.headers.get("x-routed-via"))

SRouter aggregates ~60 providers and ~1,200+ endpoints behind one /v1 endpoint.

Google Gemini	Groq	Mistral	OpenRouter	Alibaba Qwen	Nous Research
SiliconFlow	ModelScope	Cloudflare	Cohere	Zhipu GLM	NVIDIA NIM
Baidu Qianfan	ByteDance Ark	iFlytek Spark	AMD Radeon	HuggingFace	Kilo
LLM7	Ollama	OVH	Pollinations	OpenCode	AI Horde

• Google AI Studio: Gemini 2.5 Flash / Pro (Generous free daily requests)
• Groq: Ultra-fast Llama 3.3 70B & Mixtral (30 RPM free tier)
• Pollinations: Free text + image generation (no key needed)
• Mistral AI: Codestral, Mistral Small, Embeddings
• Cloudflare Workers AI: 10,000 neurons/day free tier
• Cohere: Command R / Command R+ trial credits
• Zhipu AI (Z.ai): GLM-4 and visual models
• NVIDIA NIM: 1,000 free API trial calls across open frontier models

• ModelScope (Aliyun): Qwen3.8, DeepSeek V4 Pro, GLM-5.2 (2,000 req/day free)
• Baidu Qianfan & Volcengine Ark: DeepSeek & Doubao free tiers
• NaraRouter: Indonesian & Southeast Asian low-latency AI endpoints
• Sea-Lion: Southeast Asian specialized multilingual models

Connect local models from Ollama, LM Studio, vLLM, or llama.cpp directly via the Keys page in the dashboard.

All gateway surfaces are unified under a single API key (Bearer sr-xxx or header x-api-key: sr-xxx), accessible anytime in the Keys tab of your dashboard.

SRouter includes a built-in Model Context Protocol (MCP) server over Streamable HTTP (POST http://localhost:20268/mcp), following protocol revision 2025-06-18.

Coding assistants like Claude Desktop, Cursor, Cline, and Roo Code can inspect active models, monitor quota allowances, review token compression metrics, and dynamically adjust routing strategies.

{
  "mcpServers": {
    "srouter": {
      "url": "http://localhost:20268/mcp",
      "headers": {
        "Authorization": "Bearer sr-your-unified-key"
      }
    }
  }
}

Add an HTTP-based MCP server in your editor's settings:

• Server Name: srouter
• Server URL: http://localhost:20268/mcp
• HTTP Headers: Authorization: Bearer sr-your-unified-key

Built-in MCP Tools: list_models, check_health, get_routing_scores, set_routing_strategy, get_cache_stats, clear_cache, get_compression_stats, get_quota_outlook, ask_srouter.

• Circuit Breaker Disabled by Default (0): Optimized for aggressive multi-provider fallback. 429 rate limit or timeout errors only cool down the affected key/model and instantly redirect traffic to the next fallback candidate, rather than tripping a global breaker.
• SSE Keepalive Heartbeats: Streaming pipes (OpenAI, Anthropic, Responses) periodically send heartbeat comments (: keepalive\n\n) to prevent premature connection drops by reverse proxies (Nginx, Cloudflare) or NAT state tables during deep reasoning.
• Coherent Time Budgets: Timeout allowances are aligned per fallback hop with the overall stream deadline to eliminate unexpected request cancellations.

SRouter is built as a modular, high-performance monorepo:

srouter/
├── cli/                 ← CLI tools & agent auto-generators (`srouter setup-*`)
├── client/              ← Admin Dashboard (React + Vite + Tailwind + Lucide, 60 locales)
├── desktop/             ← Electron desktop app (macOS / Windows tray popover)
├── docker/              ← Dockerfile & container runtime configurations
├── docs/                ← Comprehensive multi-language documentation & API references
│   ├── en/              ← English guides & architecture documentation
│   ├── zh-cn/           ← Chinese documentation
│   └── README.md        ← Documentation navigation hub
├── repo-assets/         ← Brand logos, architecture flows, and UI screenshots
├── scripts/             ← Automated bootstrap, dev tests, and release helpers
├── server/              ← Gateway engine (Node.js + TypeScript + SQLite)
│   ├── src/
│   │   ├── db/          ← SQLite database, migrations, and model catalog seed
│   │   ├── providers/   ← 60+ upstream provider adapters & wire protocols
│   │   ├── routes/      ← OpenAI, Anthropic, Gemini, Ollama & admin API routes
│   │   ├── services/    ← Bandit scoring, quota tracker, crypto vault, token saver
│   │   └── index.ts     ← Main gateway server entry point
├── shared/              ← Shared TypeScript types, schemas, and catalog definitions
├── CONTRIBUTING.md      ← Contributor onboarding, testing guide & PR policies
├── LICENSE              ← Open-source MIT License
└── package.json         ← Monorepo workspaces definition

Do I need a password? Not for the desktop app — the dashboard signs itself in with a hidden local account, so there is nothing to set up and nothing to forget. Open it from the tray icon → Open Dashboard, or in any browser on the same computer (for example http://127.0.0.1:20268); both sign in on their own. Another device reaching the app over LAN access still sees the sign-in form. Server installs (Docker, one-liner, npm run dev) do have an email + password account.

• Multi-Wire Protocol Translation:
  • Full OpenAI surface (/v1/chat/completions, /v1/models, /v1/embeddings, /v1/images/generations, /v1/audio/*).
  • Native Anthropic Messages API (/v1/messages) for seamless Claude Code support.
  • Native Google Gemini API (/v1beta/models/*:generateContent).
  • Native Ollama Emulation for local-first IDEs like Zed and JetBrains AI.
  • Native Codex CLI /v1/responses support.
• Prompt Compression Pipeline:
  • Fail-open structure-aware & regex compression filters bloated tool results (git diff, file reads, shell stdout).
  • Compacts repeated JSON structures and removes stale conversational context to typically save 20–40% tokens.
• Six Intelligent Routing Strategies:
  • auto: Automatically balances speed, intelligence, and provider quota.
  • auto:fast: Prioritizes ultra-low latency providers (Groq).
  • auto:smart: Routes to highest capability models (Gemini 2.5 Pro, Codestral).
  • auto:cheap: Conserves premium quotas by routing to lightweight free endpoints.
  • auto:<profile>: Custom named fallback chains created in the dashboard.
• Fusion Multi-Model Synthesis:
  • Request virtual model fusion: fans prompt out to multiple diverse models in parallel; a judge model synthesizes one optimal final response.
• Complexity Gate (System One):
  • Heuristic pre-routing analyzer classifies prompt complexity: sends simple tasks to lightweight instant models and deep multi-step code to heavy models.
• Built-in MCP Server (/mcp):
  • Connects SRouter directly to ChatGPT, Claude Desktop, and MCP-compatible agents with model inspection and live health monitoring tools.
• Zero-Exposure Local Security:
  • Upstream provider keys are encrypted using AES-256-GCM inside local SQLite.
  • Your agents only ever see your unified srouter-... bearer token.
• 60 Languages Supported:
  • Dashboard auto-detects browser locale with full RTL support (Arabic, Hebrew, Persian, Urdu).

Change the port via .env or CLI flag:

srouter serve --port 20270

SRouter automatically cools down that key/provider and routes the request to the next model in your fallback chain. If all keys for that model are exhausted, configure a fallback chain in the Models tab or enable keyless free providers (Kilo, OpenCode Free).

Click "Forgot password?" on the login screen. Since SRouter is local-first, the one-time reset code is printed directly to the server console log:

# Docker users:
docker compose logs -f srouter

# Source / Desktop users:
# Look for the 6-digit reset code in terminal stdout or ~/.srouter/logs/srouter.log

• Global CLI / Source: ~/.srouter/srouter.db
• Docker: Named volume mounted to /app/server/data
• Windows Desktop: %APPDATA%\SRouter\srouter.db
• macOS Desktop: ~/Library/Application Support/SRouter/srouter.db

Contributions are warmly welcomed! Whether you want to add a new free provider, optimize the prompt compression pipeline, or improve translations:

1. Check out our Contributing Guidelines (CONTRIBUTING.md).
2. Read our Code of Conduct (CODE_OF_CONDUCT.md).
3. Review our Security Policy (SECURITY.md).

If SRouter saves you money, boosts your coding flow, or helps your workflow, consider supporting development. Every coffee keeps this project alive and independent!

• License: Open-source under the MIT License.
• Disclaimer: SRouter is designed for personal development, experimentation, and coding agent enhancement. Free tiers are governed by the terms of service of each respective upstream provider. For mission-critical production workloads, we recommend using official enterprise paid endpoints.