🤔 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 prompt 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

1. Run the Gateway via NPM / NPX

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

# Install globally
npm install -g @baiibayu/srouter

# Launch the gateway & open the Web Dashboard (default port 20268)
srouter

# Or run headless with custom port
srouter serve --port 3000 --no-browser

# Or run directly without installing using npx
npx @baiibayu/srouter

The Web Dashboard opens automatically at http://localhost:20268. Data is safely stored in ~/.srouter.

2. Upgrading

Upgrades are seamless — your SQLite database and configuration survive updates:

# Check if a newer version exists
srouter update --check

# Upgrade to latest
srouter update
# or
npm install -g @baiibayu/srouter@latest

3. Docker & GHCR Alternative

# Run instantly from GitHub Container Registry
docker run -d --name srouter -p 20268:20268 -v srouter-data:/app/server/data ghcr.io/baiibayu/srouter:latest

🤖 Compatible Coding Agents & CLIs

SRouter includes automated configuration generators (setup-*) that inspect your live model catalog, take timestamped backups of 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	OpenClaude

Setup Commands Reference

Configure any agent with one command:

# Point Claude Code to SRouter
srouter setup-claude --url http://localhost:20268 --api-key <your-unified-key>

# Or run via npx without global install
npx @baiibayu/srouter setup-cursor --url http://localhost:20268 --api-key <your-unified-key>

Zero-Persistence Launchers

Launch agents without writing sensitive keys to your disk:

# Injects credentials directly into Claude Code's child process environment
srouter launch

# Injects credentials directly into Codex CLI
srouter launch-codex

Diagnostics & Health Check (srouter doctor)

Diagnose whether your coding tools are actually reaching the gateway (resolving environment variables, configuration precedence, and reachability):

srouter doctor
# or check a specific tool:
srouter doctor claude
srouter doctor codex

CLI Generator Flags

🔑 Provider Keys Management

Manage upstream provider keys right from your terminal without opening a browser. These commands authenticate using your dashboard session token (SROUTER_DASHBOARD_TOKEN or --token):

export SROUTER_URL=http://localhost:20268
export SROUTER_DASHBOARD_TOKEN='<dashboard-session-token>'

# Interactive prompt (hidden input)
srouter keys add groq

# Non-interactive addition
srouter keys add groq --key 'gsk_...'

# List all stored keys (shows ID, platform, active models, health status)
srouter keys list

# Test provider key health through the gateway
srouter keys test groq
srouter keys test groq --id 3

# Remove a provider key safely
srouter keys remove groq --id 3

🔌 Supported Providers

SRouter aggregates ~60 providers and ~1,200+ endpoints behind one unified /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

Provider Tiers

1. ⚡ 100% Free / Keyless: Kilo Gateway (No Key), OpenCode Free (No Key), OVH AI Endpoints, LLM7, AI Horde.
2. 🌐 Generous Free Tier with Key: Google AI Studio (Gemini 2.5 Flash / Pro), Groq (Llama 3.3 70B @ 30 RPM), Mistral AI (Codestral), Cloudflare Workers AI (10k neurons/day), Cohere, Zhipu GLM-4, NVIDIA NIM.
3. 🌏 Regional & High Quota: ModelScope (Aliyun, 2,000 req/day), Baidu Qianfan, Volcengine Ark, NaraRouter, Sea-Lion.
4. 🔌 Custom Local / Self-Hosted: Connect Ollama, LM Studio, vLLM, or llama.cpp directly via the Keys page.

🌐 Unified API Endpoints

SRouter translates diverse API wire protocols into standard surfaces:

[!TIP] Decision System One (/v1/decision): Use this endpoint before sending expensive queries to determine whether a prompt requires a lightweight fast model or a heavy reasoning model.

Web Tools (/v1/search & /v1/fetch): Built-in web scraping and search tools allow your coding agents to research latest docs, packages, and troubleshooting guides directly through the gateway.

🛠️ MCP Server Setup

SRouter includes a native Model Context Protocol (MCP) server over Streamable HTTP at http://localhost:20268/mcp.

Claude Desktop Configuration

Add SRouter to your claude_desktop_config.json:

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

Cursor / Cline Configuration

In your editor's MCP settings, add a new server:

• Name: srouter
• Type: sse or streamable-http
• URL: http://localhost:20268/mcp
• Headers: {"Authorization": "Bearer srouter-your-unified-key"}

Available MCP tools include list_models, get_model_status, check_provider_health, and web_search.

🔒 Safety, Security & Local Privacy

• Non-Destructive Generators: Generator commands merge into existing configuration files rather than overwriting them, taking a timestamped .bak backup first. --dry-run shows the exact diff beforehand.
• Zero-Exposure Launchers: srouter launch and srouter launch-codex inject credentials only into child process memory — no keys are ever written to disk.
• Local AES-256-GCM Vault: Upstream API keys are encrypted locally using AES-256-GCM in SQLite (~/.srouter/srouter.db). No telemetry, no cloud relays, no credential leakage.
• Fail-Open Compression: Token saver and regex compression filters will fail-open safely: if a filter cannot parse an input, the raw prompt is forwarded intact.

⚠️ Troubleshooting & FAQ

Port 20268 is already in use

Specify an alternate port with --port:

srouter serve --port 3000

Rate limit hit (429 Too Many Requests)

SRouter automatically cools down the exhausted key and seamlessly retries the next provider in your fallback chain. If all keys for that model tier are exhausted, enable 100% keyless providers (such as Kilo Gateway or OpenCode Free) via the Web Dashboard.

Where is my data stored?

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

❤️ Support the Developer

If SRouter saves you tokens, boosts your coding workflow, or saves you money, consider supporting development. Every coffee keeps this project independent and actively maintained!

📄 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.
• Repository: https://github.com/baiibayu/srouter
• Author: baiibayu