What Is 9Router? A Simple Guide to AI Coding Provider Routing

What Is 9Router? A Simple Guide to decolua/9router for AI Coding Provider Routing

Image extracted from GitHub’s Open Graph preview for the decolua/9router repository. This image is not SVG.¹

Quick summary

9Router is an open-source AI router/proxy for AI coding tools such as Claude Code, Codex, Cursor, Cline, OpenCode, OpenClaw, GitHub Copilot, Antigravity and other CLI/IDE tools. The official README describes it as a “FREE AI Router & Token Saver” that connects AI code tools to 40+ providers and 100+ models, with automatic fallback and RTK-based token savings.²

In plain terms: instead of configuring every AI coding tool with a different provider and key, you run 9Router locally or on a server, then point your tools to one common endpoint:

http://localhost:20128/v1

9Router then decides where each request should go: a subscription provider, a cheap backup provider or a free provider, depending on the combo you configure.

What problem does 9Router solve?

AI coding workflows often run into quota limits, provider rate limits, multiple API keys, multiple subscriptions and long tool outputs. Outputs such as git diff, grep, find, ls, tree and logs can also consume many prompt tokens. 9Router sits between the tool and the provider to handle routing, fallback, format translation and token saving.

Claude Code / Codex / Cursor / Cline / OpenCode
        ↓
OpenAI-compatible endpoint: http://localhost:20128/v1
        ↓
9Router
        ↓
Claude Code subscription / Codex / Copilot / GLM / MiniMax / Kimi / Kiro / OpenCode Free / Vertex / custom provider

The README describes a 3-tier route: subscription → cheap → free. If a quota is exhausted or a provider fails, the router falls back to the next tier.³

What 9Router is not

9Router is a routing layer. It does not make models smarter; it helps you use providers more flexibly.

What stands out in the decolua/9router repo?

The GitHub page shows decolua/9router as a public MIT-licensed repository with around 16k stars at the time accessed. Its README says the main value is: “Never stop coding. Save 20-40% tokens with RTK + auto-fallback to FREE & cheap AI models.”⁴

Main repository parts:

The README lists the stack as Node.js 20+, Next.js 16, React 19, Tailwind CSS 4, SQLite, Server-Sent Events, OAuth 2.0 PKCE, JWT and API keys.⁵

Quick installation

Install globally:

npm install -g 9router
9router

Dashboard:

http://localhost:20128

Default API endpoint:

http://localhost:20128/v1

The README quickstart has three steps: install globally, connect a provider in the dashboard, and point your CLI tool to http://localhost:20128/v1 with the API key copied from the dashboard.⁶

Run from source

git clone https://github.com/decolua/9router.git
cd 9router

cp .env.example .env
npm install

PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev

Production mode:

npm run build
PORT=20128 HOSTNAME=0.0.0.0 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run start

The README notes that the package inside this repository is private (9router-app), so source/Docker execution is the expected path for local development from the repo.⁷

Configure AI coding tools

Claude Code

Edit:

~/.claude/config.json

Example:

{
  "anthropic_api_base": "http://localhost:20128/v1",
  "anthropic_api_key": "your-9router-api-key"
}

Codex CLI

export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-9router-api-key"

codex "your prompt"

Cursor IDE

Settings → Models → Advanced
OpenAI API Base URL: http://localhost:20128/v1
OpenAI API Key: [from 9Router dashboard]
Model: cc/claude-opus-4-7

Cline / Continue / RooCode

Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-7

OpenClaw

The README notes that OpenClaw only works with local 9Router and recommends 127.0.0.1 instead of localhost to avoid IPv6 resolution issues.⁸

{
  "models": {
    "providers": {
      "9router": {
        "baseUrl": "http://127.0.0.1:20128/v1",
        "apiKey": "sk_9router",
        "api": "openai-completions",
        "models": [
          {
            "id": "kr/claude-sonnet-4.5",
            "name": "Claude Sonnet 4.5 (Kiro Free)"
          }
        ]
      }
    }
  }
}

Providers and models

The README groups providers into three broad tiers.⁹

1. Subscription providers

Use these when you already pay for a subscription:

• Claude Code Pro/Max
• Codex Plus/Pro
• GitHub Copilot
• Cursor IDE

Goal: use the quota effectively and fall back when it is exhausted.

2. Cheap providers

Use these as lower-cost backups, such as GLM, MiniMax, Kimi, OpenRouter, DeepSeek, Groq, xAI, Mistral, Perplexity, Together AI, Fireworks, Cerebras, Cohere, NVIDIA, SiliconFlow and custom OpenAI/Anthropic-compatible endpoints.

3. Free providers

The README currently recommends Kiro AI, OpenCode Free and Vertex AI credits, while noting that iFlow, Qwen and Gemini CLI free tiers changed or are no longer recommended in 2026.¹⁰

Important caveat: any “free” or “unlimited” provider status depends on third-party provider policy. Treat it as a state described by 9Router documentation at the time of writing, not a permanent guarantee.

What is a combo?

A combo is a virtual model made of multiple real models in priority order. If the first model fails or runs out of quota, 9Router switches to the next one.

Example:

Combo: premium-coding
1. cc/claude-opus-4-7      # primary subscription
2. glm/glm-5.1             # cheap backup
3. minimax/MiniMax-M2.7    # cheaper fallback
4. kr/claude-sonnet-4.5    # free fallback

You then use the combo name as the model:

premium-coding

The README shows examples for subscription-maximizing combos and free-only combos.¹¹

Smart 3-tier fallback

The core routing idea:

Tier 1: Subscription
  ↓ quota exhausted / error
Tier 2: Cheap
  ↓ budget exceeded / error
Tier 3: Free

Benefits:

• no manual provider switching;
• less downtime when a provider fails;
• better use of paid subscriptions;
• cheap providers as backup;
• free providers for emergency fallback or lower-priority work.

RTK Token Saver

9Router integrates RTK Token Saver to compress tool_result content before requests reach the LLM. The README says tool outputs such as git diff, grep, find, ls, tree and logs often consume 30–50% of the prompt budget, and RTK auto-detects content to pick the right filter.¹²

Filters listed in the README:

git-diff
git-status
grep
find
ls
tree
dedup-log
smart-truncate
read-numbered
search-list

Properties:

• auto-detects from the first 1KB of each tool_result;
• if a filter fails or makes output larger, 9Router keeps the original text;
• runs before format translation, so it works across provider formats;
• enabled by default and configurable in the dashboard.

Caveman Mode

9Router also includes Caveman Mode, inspired by the Caveman project. The README describes it as injecting a terse-style prompt so the LLM gives shorter technical answers, reducing output tokens by up to 65% according to the project description.¹³

Use it for concise technical sessions. Avoid it when you need detailed explanations, documentation or blog-style output.

Understanding dashboard costs

The README emphasizes that 9Router does not charge users. Dashboard “cost” values are estimates for tracking and comparison, not invoices from 9Router.¹⁴

Rules:

• 9Router software is free/open source.
• You pay providers directly if you use paid providers.
• Free providers depend on their own policies.
• Dashboard cost is usage/savings estimation.
• 9Router has no billing system and does not store payment cards.

Basic API reference

9Router exposes an OpenAI-compatible API.

Chat completions

curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cc/claude-opus-4-6",
    "messages": [
      {"role": "user", "content": "Write a function to parse CSV"}
    ],
    "stream": true
  }'

List models

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer your-api-key"

The README says /v1/models returns all models and combos in OpenAI format.¹⁵

Docker deployment

Run the Docker Hub image:

docker run -d \
  --name 9router \
  -p 20128:20128 \
  -v "$HOME/.9router:/app/data" \
  -e DATA_DIR=/app/data \
  decolua/9router:latest

Open:

http://localhost:20128

SQLite data is persisted at:

$HOME/.9router/db/data.sqlite

The README says multi-platform linux/amd64 and linux/arm64 images are published to Docker Hub and GHCR.¹⁶

VPS / production deployment

Important environment variables:

export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/9router"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export BASE_URL="https://your-9router.example.com"
export CLOUD_URL="https://9router.com"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"
export MACHINE_ID_SALT="endpoint-proxy-salt"
export AUTH_COOKIE_SECURE="true"
export REQUIRE_API_KEY="true"

Build and run:

npm install
npm run build
npm run start

If exposed to the internet, put it behind HTTPS reverse proxy and use AUTH_COOKIE_SECURE=true plus REQUIRE_API_KEY=true.¹⁷

Important environment variables

The README and .env.example list key runtime variables:¹⁷¹⁸

Security notes

9Router handles API keys, OAuth tokens, request/response data and usage logs, so treat it as a sensitive service.

Checklist:

• Change INITIAL_PASSWORD.
• Use a long random JWT_SECRET.
• Replace default API_KEY_SECRET.
• Replace default MACHINE_ID_SALT.
• Do not expose dashboard publicly without HTTPS and authentication.
• Use REQUIRE_API_KEY=true for exposed /v1/*.
• Use AUTH_COOKIE_SECURE=true behind HTTPS.
• Avoid ENABLE_REQUEST_LOGS=true for code, secrets or customer data unless debugging.
• Back up ${DATA_DIR}/db/data.sqlite.
• Never commit .env.
• Do not share the SQLite database; it may contain provider settings, tokens, keys or usage history.
• Review each provider’s terms before using OAuth/subscription/IDE traffic.
• Use MITM bridge only where provider/tool policy allows it.

The website mentions a MITM Bridge feature for intercepting Antigravity, GitHub Copilot and Kiro IDE traffic and explicitly says to mind each tool’s policy.¹⁹

When should you use 9Router?

Use it when:

• you use multiple AI coding tools;
• you have multiple providers, subscriptions or API keys;
• rate limits interrupt work;
• you want automatic fallback;
• you want quota and usage tracking;
• you want token savings from tool output compression;
• your team needs a shared OpenAI-compatible endpoint;
• you want to self-host a routing layer.

Be cautious when:

• one provider is enough for your workflow;
• you do not want provider keys stored in a router;
• enterprise policy blocks self-managed proxies;
• provider policy restricts external routing/intercept;
• you plan to expose the service without HTTPS/auth;
• requests contain sensitive data and logs are enabled.

Personal setup guide

Recommended first run:

npm install -g 9router
9router

Then:

1. Open http://localhost:20128.
2. Change or confirm the dashboard password.
3. Add a provider or connect OAuth.
4. Create an endpoint API key.
5. Create a combo such as free-combo or premium-coding.
6. Point Claude Code, Codex, Cursor or Cline to http://localhost:20128/v1.
7. Run a small test request.
8. Check usage analytics and quota tracking.

Team rollout guide

Phase 1: local trials

• Each developer runs 9Router locally.
• Each developer creates a personal combo.
• Test with Claude Code, Codex and Cursor.
• Track token savings and fallback behavior.

Phase 2: standard combos

Example team combos:

team-premium
1. primary subscription model
2. cheap backup
3. free fallback

team-review
1. cheaper long-context model
2. free fallback

team-experiment
1. free provider
2. cheap backup when needed

Phase 3: internal self-hosting

• Deploy on a VPS or private network.
• Use HTTPS.
• Set REQUIRE_API_KEY=true.
• Restrict dashboard access to VPN or IP allowlist.
• Back up SQLite.
• Disable request logs by default.
• Write setup docs for each AI tool.

Phase 4: governance

• Define which providers can be used for internal code.
• Define which models can process customer data.
• Track estimated cost and actual provider bills.
• Review logs only when needed.
• Review cloud sync policy.
• Revoke tokens when team members leave.

9Router vs related tools

9Router operates at the provider routing layer. It can complement Claude Tap, Headroom and RTK rather than replace them.

FAQ

What is 9Router?

9Router is an open-source AI router/proxy that exposes an OpenAI-compatible endpoint for AI coding tools, routes requests to many providers/models, and includes fallback, quota tracking, token saving and a local dashboard.²

Is 9Router free?

The 9Router software is free and open source under the MIT license. The README says 9Router does not charge users, but users still pay providers directly when using paid subscriptions or API services.¹⁴²⁰

Which tools does 9Router support?

The README and website list support for Claude Code, Codex, OpenClaw, OpenCode, Cursor, Antigravity, Cline, Continue, Roo, Copilot, Kilo Code and other OpenAI-compatible tools.²¹²²

What does RTK Token Saver do?

It compresses tool results such as git diff, grep, find, ls, tree and logs before they reach the LLM. The README says it can save 20–40% input tokens per request.¹²

Should 9Router be exposed to the internet?

Only with HTTPS, strong password, API key enforcement, a secure reverse proxy and careful logging policy. For individuals, localhost-only use is safer.

What database does 9Router use?

The README says 9Router uses SQLite, with main state stored at ${DATA_DIR}/db/data.sqlite, including providers, combos, aliases, keys, settings and usage history.²³

Conclusion

decolua/9router is useful if you use AI coding agents every day. It addresses practical problems: quota limits, provider switching, multiple API keys and long tool outputs. Its strengths are a shared endpoint, visual dashboard, fallback combos, RTK token savings, format translation and deployment flexibility across localhost, Docker and VPS.

The easiest start is npm install -g 9router, run 9router, connect a provider in the dashboard, then point Claude Code, Codex, Cursor or Cline to http://localhost:20128/v1. For team or internet deployments, treat 9Router as a secrets-bearing service: use API keys, HTTPS, strong passwords, SQLite backups, restricted dashboard access and careful request logging.

References

Footnotes

1. GitHub Open Graph preview image for decolua/9router. https://opengraph.githubassets.com/9router-guide/decolua/9router ↩

2. 9Router README. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩ ↩²

3. 9Router README, “How It Works.” https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

4. GitHub. decolua/9router. https://github.com/decolua/9router ↩

5. 9Router README, Tech Stack. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

6. 9Router README, Quick Start. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

7. 9Router README, run from source and production mode. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

8. 9Router README, CLI Integration. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

9. 9Router README, Supported Providers. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

10. 9Router README, Free Providers and discontinued free tiers note. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

11. 9Router README, Create Combos. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

12. 9Router README, RTK Token Saver. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩ ↩²

13. 9Router README, Key Features. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

14. 9Router README, Understanding 9Router Costs & Billing. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩ ↩²

15. 9Router README, API Reference. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

16. 9Router README, Docker deployment. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

17. 9Router README, Environment Variables. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩ ↩²

18. 9Router .env.example. https://raw.githubusercontent.com/decolua/9router/master/.env.example ↩

19. 9Router website, Advanced Features and MITM Bridge note. https://9router.com ↩

20. 9Router MIT license. https://raw.githubusercontent.com/decolua/9router/master/LICENSE ↩

21. 9Router README, Supported CLI Tools. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩

22. 9Router website, CLI/IDE integrations. https://9router.com ↩

23. 9Router README, Runtime Files and Storage. https://raw.githubusercontent.com/decolua/9router/master/README.md ↩