Local AI Routing Gateway — one endpoint, 96+ providers, automatic format translation.
Route any AI client (Claude Code, Codex, Cursor, Cline, any OpenAI SDK) to any upstream provider with streaming, fallback, token savings, and a web dashboard.
Quick Start • Features • CLI Reference • Agent Skills • Architecture
Mairouter is a local AI traffic gateway that runs on your machine. Point any OpenAI-compatible client to http://localhost:12890/v1 and mairouter automatically:
- Routes to the best upstream provider (Anthropic, OpenAI, Gemini, DeepSeek, Qwen, Kiro, Ollama, and 90+ more)
- Translates request/response formats on the fly (Claude ↔ OpenAI ↔ Gemini ↔ Kiro ↔ Cursor ↔ Ollama)
- Falls back across accounts and model combos when rate limits or errors occur
- Saves tokens with RTK compression (caveman mode, pony tail, filter-based)
- Streams thinking/reasoning blocks from non-Anthropic providers into Claude's thinking panel
┌──────────────┐ ┌──────────────────────────────────────────────┐ ┌──────────────────┐
│ Your Tool │ │ mairouter (port 12890) │ │ AI Providers │
│ │ │ │ │ │
│ Claude Code │────▶│ /v1/* → Format Detect → Translate │────▶│ Anthropic │
│ Codex CLI │ │ ↓ │ │ OpenAI │
│ Cursor │ │ Executor (SSE/REST) │ │ Gemini │
│ Cline │ │ Account Fallback │ │ DeepSeek │
│ OpenAI SDK │ │ Combo Router │ │ Kiro │
│ OpenClaw │ │ RTK Compression │ │ Ollama │
│ │ │ │ │ ... 96+ more │
└──────────────┘ └──────────────────────────────────────────────┘ └──────────────────┘
npm install -g mairouterOr run directly without installing:
npx mairoutermairouterThis starts the server on http://localhost:12890 and opens the dashboard in your browser.
- OAuth providers (Claude Code, Codex, Kiro, Cursor, Qwen, xAI, Gemini CLI, GitHub): click "Add Provider" in the dashboard and follow the OAuth flow.
- API key providers (OpenAI, Anthropic, DeepSeek, OpenRouter, etc.): enter your API key in the dashboard.
With Claude Code:
export ANTHROPIC_BASE_URL=http://localhost:12890With any OpenAI SDK:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "http://localhost:12890/v1",
apiKey: "sk-...", // from Dashboard → Keys
});With cURL:
curl http://localhost:12890/v1/chat/completions \
-H "Authorization: Bearer sk-..." \
-H "Content-Type: application/json" \
-d '{"model":"openai/gpt-4o","messages":[{"role":"user","content":"Hello"}]}'| Feature | Description |
|---|---|
| Multi-Provider Routing | Route to 96+ providers from a single OpenAI-compatible endpoint |
| Format Translation | Automatic conversion between Claude, OpenAI, Gemini, Kiro, Cursor, Ollama formats |
| Combo Models | Fallback, round-robin, and fusion strategies across multiple models |
| Account Fallback | Multi-account per provider with automatic failover on rate limits and errors |
| OAuth Support | Claude Code, Codex, Cursor, Kiro, Qwen, xAI, Gemini CLI, GitHub, Antigravity |
| Streaming Thinking | Thinking/reasoning blocks from non-Anthropic providers render in Claude's thinking panel |
| RTK Token Saver | Auto-compress tool_result content; caveman mode for terse responses; pony tail for senior-dev style |
| Web Dashboard | Manage providers, API keys, combos, usage tracking, settings, proxy pools |
| CLI + Tray | Terminal UI menu and system tray mode (Windows PowerShell NotifyIcon, macOS/Linux systray2) |
| MITM Proxy | TLS-intercepting proxy for Antigravity, Copilot, Cursor, Kiro CLI tools |
| MCP Bridge | SSE bridge for MCP plugins |
| Tunnels | Cloudflare Tunnel and Tailscale support |
| Proxy Pools | HTTP proxy, Cloudflare Workers, Vercel Edge, Deno Deploy relays |
| Embeddings | OpenAI-compatible /v1/embeddings for RAG and semantic search |
| TTS / STT | Text-to-speech and speech-to-text via OpenAI, ElevenLabs, Deepgram, Edge TTS, Groq, AssemblyAI |
| Image Generation | DALL-E, Gemini Imagen, FLUX, MiniMax, Stable Diffusion, ComfyUI |
| Web Search & Fetch | Tavily, Firecrawl, Jina Reader, Exa, Brave, Serper, SearXNG, Google PSE |
| Headroom | External proxy-based token compression |
| Cloud Sync | Optional multi-device state synchronization |
| Prompt Caching | Automatic Claude header caching |
| OIDC Auth | External OIDC provider for dashboard login |
| Docker | Multi-stage build, ghcr.io/NatrocTeam/mairouter |
docker pull ghcr.io/NatrocTeam/mairouter:latest
docker run -p 12890:12890 ghcr.io/NatrocTeam/mairouter:latest- CLI Manual — Full CLI reference with options, TUI menu, and system tray
- Agent Skills — Drop-in skills for AI assistants (chat, image, TTS, embeddings, search)
- Architecture — System design and internal architecture
- Upstream 9Router Docs — Reference copies of original 9Router documentation (archival)
| Variable | Required | Purpose |
|---|---|---|
JWT_SECRET |
Yes | Dashboard session cookie signing |
INITIAL_PASSWORD |
Yes (setup) | Default dashboard password (change on first login) |
DATA_DIR |
No | Data directory (default: ~/.mairouter/) |
PORT |
No | Server port (default: 12890) |
API_KEY_SECRET |
No | HMAC secret for API key generation |
MACHINE_ID_SALT |
No | Salt for machine ID hashing |
REQUIRE_API_KEY |
No | Require API key for all requests |
HTTP_PROXY |
No | Outbound HTTP proxy for upstream calls |
HTTPS_PROXY |
No | Outbound HTTPS proxy |
NEXT_PUBLIC_BASE_URL |
No | Public URL for cloud sync |
See .env.example for the full list.
See CONTRIBUTING.md for development setup, build instructions, and PR guidelines.
Mairouter is MIT licensed. It is a fork of 9Router by decolua. See NOTICE.md for attribution and LICENSE for the full license text.