🤔 Why SRouter?

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

🔄 How It Works

┌─────────────────────────────────────────────────────────────────────────────┐
│                       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.

⚡ Quick Start

Choose your preferred way to run SRouter:

Option 1: Global CLI / NPX (Easiest)

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

# Run directly with npx
npx @baiibayu/srouter

# Or install globally
npm install -g @baiibayu/srouter
srouter

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

Option 2: Docker Compose (Recommended for Servers & Home Labs)

# 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

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

Option 3: Desktop App (macOS & Windows)

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.

Option 4: Run from Source (Monorepo Development)

# 1. Clone & install dependencies
git clone https://github.com/baiibayu/srouter.git
cd srouter
npm install

# 2. Apply database migrations
npm run db:migration:up

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

🤖 Compatible Coding Agents & CLIs

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

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

Claude Code Zero-Persistence Launch

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

Cursor / Windsurf Settings

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

Python OpenAI SDK

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"))

🔌 Supported Providers

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

1. ⚡ 100% Free / Keyless (No Sign-up / Credit Card Needed)

2. 🌐 Generous Free Tier with API Key

• 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

3. 🌏 Regional & High Quota Gateways

• 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

4. 🔌 Custom Local & Remote Providers

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

🏗️ Project Architecture

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

✨ Key Features

• 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).

🛠️ Command Reference

🖼️ Dashboard Preview

⚠️ Troubleshooting & FAQ

1. Port 20268 is already in use

Change the port via .env or CLI flag:

srouter serve --port 20270

2. Upstream returns 429 Too Many Requests

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).

3. Forgot the Dashboard Password?

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

4. Where is my database and data stored?

• 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

🤝 Contributing

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).

❤️ Support the Developer

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 & Disclaimer

• 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.