# OmniRoute - Free AI Router
**Never stop coding. Auto-route to FREE & cheap AI models with smart fallback.**
**36+ Providers โข Embeddings โข Image Generation โข Think Tag Parsing**
**Free AI Provider for OpenClaw.**
> *This project is inspired by and originally forked from [9router](https://github.com/decolua/9router) by [decolua](https://github.com/decolua). Thank you for the incredible foundation!*
[](https://www.npmjs.com/package/omniroute)
[](https://hub.docker.com/r/diegosouzapw/omniroute)
[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
[](https://omniroute.online)
[๐ Website](https://omniroute.online) โข [๐ Quick Start](#-quick-start) โข [๐ก Features](#-key-features) โข [๐ Docs](#-documentation)
---
## ๐ค Why OmniRoute?
**Stop wasting money and hitting limits:**
- โ Subscription quota expires unused every month
- โ Rate limits stop you mid-coding
- โ Expensive APIs ($20-50/month per provider)
- โ Manual switching between providers
**OmniRoute solves this:**
- โ
**Maximize subscriptions** - Track quota, use every bit before reset
- โ
**Auto fallback** - Subscription โ Cheap โ Free, zero downtime
- โ
**Multi-account** - Round-robin between accounts per provider
- โ
**Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, any CLI tool
---
## ๐ How It Works
```
โโโโโโโโโโโโโโโ
โ Your CLI โ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
โ Tool โ
โโโโโโโโฌโโโโโโโ
โ http://localhost:20128/v1
โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ OmniRoute (Smart Router) โ
โ โข Format translation (OpenAI โ Claude) โ
โ โข Quota tracking + Embeddings + Images โ
โ โข Auto token refresh โ
โโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
โ โ quota exhausted
โโโ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, Together, etc.
โ โ budget limit
โโโ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
โ โ budget limit
โโโ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)
Result: Never stop coding, minimal cost
```
---
## โก Quick Start
**1. Install globally:**
```bash
npm install -g omniroute
omniroute
```
๐ Dashboard opens at `http://localhost:20128`
| Command | Description |
| ----------------------- | --------------------------------- |
| `omniroute` | Start server (default port 20128) |
| `omniroute --port 3000` | Use custom port |
| `omniroute --no-open` | Don't auto-open browser |
| `omniroute --help` | Show help |
**2. Connect a FREE provider:**
Dashboard โ Providers โ Connect **Claude Code** or **Antigravity** โ OAuth login โ Done!
**3. Use in your CLI tool:**
```
Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
Endpoint: http://localhost:20128/v1
API Key: [copy from dashboard]
Model: if/kimi-k2-thinking
```
**That's it!** Start coding with FREE AI models.
**Alternative โ run from source:**
```bash
cp .env.example .env
npm install
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
```
---
## ๐ณ Docker
OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
**Quick run:**
```bash
docker run -d \
--name omniroute \
--restart unless-stopped \
-p 20128:20128 \
-v omniroute-data:/app/data \
diegosouzapw/omniroute:latest
```
**With environment file:**
```bash
# Copy and edit .env first
cp .env.example .env
docker run -d \
--name omniroute \
--restart unless-stopped \
--env-file .env \
-p 20128:20128 \
-v omniroute-data:/app/data \
diegosouzapw/omniroute:latest
```
**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
docker compose --profile base up -d
# CLI profile (Claude Code, Codex, OpenClaw built-in)
docker compose --profile cli up -d
```
| Image | Tag | Size | Description |
| ------------------------ | -------- | ------ | --------------------- |
| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |
| `diegosouzapw/omniroute` | `0.6.0` | ~250MB | Current version |
---
## ๐ก Key Features
| Feature | What It Does |
| ------------------------------- | --------------------------------------------- |
| ๐ฏ **Smart 3-Tier Fallback** | Auto-route: Subscription โ Cheap โ Free |
| ๐ **Real-Time Quota Tracking** | Live token count + reset countdown |
| ๐ **Format Translation** | OpenAI โ Claude โ Gemini seamless |
| ๐ฅ **Multi-Account Support** | Multiple accounts per provider |
| ๐ **Auto Token Refresh** | OAuth tokens refresh automatically |
| ๐จ **Custom Combos** | Create unlimited model combinations |
| ๐งฉ **Custom Models** | Add any model ID to any provider |
| ๐ **Request Logging** | Debug mode with full request/response logs |
| ๐พ **Cloud Sync** | Sync config across devices |
| ๐ **Usage Analytics** | Track tokens, cost, trends over time |
| ๐ **Deploy Anywhere** | Localhost, VPS, Docker, Cloudflare Workers |
| ๐ **Circuit Breaker** | Auto-open/close per-provider with cooldowns |
| ๐ก๏ธ **Anti-Thundering Herd** | Mutex + auto rate-limit for API key providers |
| ๐ง **Semantic Cache** | Two-tier cache reduces cost & latency |
| โก **Request Idempotency** | 5s dedup window for duplicate requests |
| ๐ **Progress Tracking** | Opt-in SSE progress events for streaming |
| ๐งช **LLM Evaluations** | Golden set testing with 4 match strategies |
---
## ๐งช Evaluations (Evals)
OmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ Evals** in the dashboard.
### Built-in Golden Set
The pre-loaded "OmniRoute Golden Set" contains 10 test cases covering:
- Greetings, math, geography, code generation
- JSON format compliance, translation, markdown
- Safety refusal (harmful content), counting, boolean logic
### How It Works
1. Click **"Run Eval"** on a suite in the dashboard
2. Each test case is sent to your proxy endpoint (`/v1/chat/completions`)
3. Real LLM responses are collected and evaluated against expected criteria
4. Results show pass/fail status, latency per case, and overall pass rate
### Evaluation Strategies
| Strategy | Description | Example |
| ---------- | ------------------------------------------------ | -------------------------------- |
| `exact` | Output must match exactly | `"4"` |
| `contains` | Output must contain substring (case-insensitive) | `"Paris"` |
| `regex` | Output must match regex pattern | `"1.*2.*3"` |
| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |
### API Usage
```bash
# List all eval suites
curl http://localhost:20128/api/evals
# Run a suite with pre-collected outputs
curl -X POST http://localhost:20128/api/evals \
-H 'Content-Type: application/json' \
-d '{"suiteId": "golden-set", "outputs": {"gs-01": "Hello there!", "gs-02": "4"}}'
# Get suite details
curl http://localhost:20128/api/evals/golden-set
```
### Custom Suites
Register custom suites programmatically via `registerSuite()` in `src/lib/evals/evalRunner.ts`:
```typescript
registerSuite({
id: "my-suite",
name: "Custom Eval Suite",
cases: [
{
id: "c-01",
name: "API response",
model: "gpt-4o",
input: { messages: [{ role: "user", content: "Say OK" }] },
expected: { strategy: "contains", value: "OK" },
},
],
});
```
---
## ๐ ๏ธ Tech Stack
- **Runtime**: Node.js 20+
- **Language**: TypeScript 5.9 (src/) + JavaScript (open-sse/)
- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
- **Database**: LowDB (JSON) + SQLite (domain state)
- **Streaming**: Server-Sent Events (SSE)
- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys
- **Testing**: Node.js test runner (368+ unit tests)
- **CI/CD**: GitHub Actions (auto npm publish on release)
- **Website**: [omniroute.online](https://omniroute.online)
- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd
---
## ๐ Documentation
| Document | Description |
| ------------------------------------------ | ---------------------------------------------- |
| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
---
## ๐ง Support
- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
---
## ๐ฅ Contributors
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
### How to Contribute
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
### Releasing a New Version
```bash
# Create a release โ npm publish happens automatically
gh release create v0.8.0 --title "v0.8.0" --generate-notes
```
---
## ๐ Acknowledgments
Special thanks to **CLIProxyAPI** - the original Go implementation that inspired this JavaScript port.
---
## ๐ License
MIT License - see [LICENSE](LICENSE) for details.
---