🌿 ZenRouter

Unified High-Performance AI Gateway & Intelligent Multi-Provider Routing Engine

---

⚡ What is ZenRouter?

ZenRouter is an open-source, high-performance local AI gateway and routing platform that exposes a clean, drop-in OpenAI & Anthropic-compatible API endpoint (/v1/*) while intelligently orchestrating, translating, and load-balancing requests across 40+ upstream AI providers.

Designed for developers, agentic frameworks, and multi-account setups, ZenRouter delivers:

• 🚀 Zero-Downtime Smart Fallback: Dynamic circuit breaker, quota reset tracking, and instant failover across model combos and pooled accounts.
• ✂️ Real-Time Token Compression (RTK / Headroom): In-place prompt and tool execution compression saving up to 40% input tokens.
• 🎭 Universal Format Translation: Lossless bi-directional transformation between OpenAI Chat, Anthropic Claude Messages, OpenAI Responses API, Google Gemini, and Ollama.
• 📊 Local-First & Multi-Driver SQLite: Lightning-fast query performance with automatic driver fallback (better-sqlite3 ➔ node:sqlite ➔ bun:sqlite ➔ sql.js).
• 🌐 Web Search Grounding: Integrated Google Search, Xquik (X platform search), and Ollama search providers.
• 💻 One-Click CLI Tool Presets: Instant configuration for Claude Code CLI, OpenAI Codex CLI, Cursor, Cline, OpenClaw, Hermes Agent, and Droid.

---

🚀 Quick Start

1. Run with NPX (Zero-Install)

npx @joyccn/zenrouter

2. Global NPM Install

npm install -g @joyccn/zenrouter
zenrouter

3. Docker & Docker Compose

docker run -d \
  --name zenrouter \
  -p 20128:20128 \
  -v zenrouter-data:/root/.zenrouter \
  --restart unless-stopped \
  joyccn/zenrouter:latest

Using docker-compose.yml:

services:
  zenrouter:
    image: joyccn/zenrouter:latest
    container_name: zenrouter
    restart: unless-stopped
    ports:
      - "20128:20128"
    volumes:
      - ./data:/root/.zenrouter
    environment:
      - PORT=20128
      - INITIAL_PASSWORD=admin12345

---

🎯 Architecture Overview

[Client / Agent / SDK]
  (Claude Code, Codex, Cline, Cursor, Hermes Agent, OpenAI SDK)
             │
             ▼
┌────────────────────────────────────────────────────────┐
│  ZenRouter Server (Port 20128 / /v1/*)                 │
│  • Format Detection & Bidirectional Translation        │
│  • RTK / Headroom In-Place Token Compression           │
│  • Multi-Account & Model-Combo Fallback Circuit        │
│  • Real-Time Token & Quota Tracking                    │
└───────────────────────┬────────────────────────────────┘
                        │
                        ▼
┌────────────────────────────────────────────────────────┐
│  Multi-Provider Upstream Pools (40+ Providers)         │
│  • Google Antigravity / Gemini CLI (Multi-OAuth Pool)  │
│  • Anthropic Claude / OpenAI GPT / DeepSeek            │
│  • NVIDIA NIM (130+ Node Load-Balancing Pool)          │
│  • Mistral, Groq, Cerebras, Moonshot Kimi, MiniMax     │
└────────────────────────────────────────────────────────┘

---

🛠️ Configuration & Port Alignment

Endpoint	Purpose	Description
http://localhost:20128	Web Dashboard	Manage providers, credentials, combos, and live logs
http://localhost:20128/v1	API Base URL	OpenAI / Anthropic-compatible routing endpoint
http://localhost:20128/v1/models	Catalog	Active models & single-model lookup endpoint
http://localhost:20128/v1/search	Web Search	Unified multi-provider web & X search

---

📄 License

ZenRouter is open-source software licensed under the MIT License. Sponsored & maintained by Joy and the open-source community.