AI Tools

9Router Setup Guide: Route Claude Code, Codex, and Cursor with Fallback

Set up 9Router as a local OpenAI-compatible endpoint for Claude Code, Codex, Cursor, and Cline, with provider fallback and token saving.

9Router is a local router for AI coding tools. It lets Claude Code, Codex, Cursor, Cline, Copilot, OpenCode, OpenClaw, and similar tools connect to one OpenAI-compatible endpoint, then routes requests to different models and providers.

It is not trying to be another chat client. It sits between your AI coding tools and model providers, solving a few practical problems: incompatible API formats, manual provider switching, fast token burn from tool output, interrupted work when quotas run out, and messy multi-account configuration.

According to the project README, 9Router supports 40+ providers and 100+ models. It includes RTK Token Saver, automatic fallback, quota tracking, multi-account rotation, format translation, and request logging. The project is written in JavaScript and uses Node.js, Next.js, React, Tailwind CSS, and LowDB. It is licensed under MIT.

Quick Answer

9Router is useful when you want Claude Code, Codex, Cursor, Cline, Continue, or similar tools to share one local OpenAI-compatible endpoint. Its main value is centralized provider routing, fallback when a model or account runs out of quota, and token compression for noisy coding-tool output.

What It Is Good For

9Router is most useful when you use multiple AI coding tools and multiple model sources at the same time.

Examples:

  • Claude Code uses a subscription account.
  • Codex or Cursor needs a custom OpenAI endpoint.
  • Cline, Continue, or RooCode needs an OpenAI-compatible API.
  • Free providers are used for experiments.
  • GLM, MiniMax, or Kimi is used as a cheaper backup.
  • High-quality models are reserved for difficult tasks.

Without 9Router, these settings are scattered across many tools. Each tool needs its own endpoint, API key, model name, and fallback plan. 9Router centralizes that into one local routing layer.

Default local API:

1

http://localhost:20128/v1

Dashboard:

1

http://localhost:20128/dashboard

Quick Install

For local use, npm is the simplest path:

1
2

npm install -g 9router
9router

The dashboard opens locally, and the README uses 20128 as the default port.

Run from source:

1
2
3
4
5

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:

1
2

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

The npm package requires Node.js >=18.0.0. For VPS or Docker deployment, configure JWT_SECRET, INITIAL_PASSWORD, DATA_DIR, and API_KEY_SECRET instead of exposing defaults.

Connect Coding Tools

9Router exposes an OpenAI-compatible API, so most tools that support custom OpenAI endpoints can connect to it.

Typical configuration:

1
2
3

Base URL: http://localhost:20128/v1
API Key: copied from the 9Router dashboard
Model: a model name or combo name configured in 9Router

For Codex CLI:

1
2
3
4

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

codex "your prompt"

For Cline, Continue, or RooCode, choose OpenAI Compatible and set:

1
2
3

Base URL: http://localhost:20128/v1
API Key: your-9router-api-key
Model: cc/claude-opus-4-7

Model names depend on connected providers. The README shows prefixes such as cc/, cx/, gh/, glm/, minimax/, kr/, and vertex/.

RTK Token Saver

AI coding tools often burn tokens fastest on tool outputs:

  • git diff
  • git status
  • grep
  • find
  • ls
  • tree
  • logs
  • long file lists

9Router includes RTK Token Saver, which compresses these outputs before they are sent to the model. The project says this can save 20%-40% input tokens in many requests.

The value is that you do not need to change tools or models. The routing layer removes waste before the request reaches the provider. Still, for critical logs or complete file content, test the behavior first and make sure answer quality does not drop.

Automatic Fallback

9Router can arrange models in priority order:

1
2
3

1. Subscription model
2. Cheap API
3. Free provider

When the first tier is rate-limited, out of quota, or failing, it can switch to the next one. This reduces manual switching and keeps coding sessions from stopping suddenly.

Example:

1
2
3

1. cc/claude-opus-4-7
2. glm/glm-5.1
3. kr/claude-sonnet-4.5

Fallback changes output consistency. Different models have different style and reasoning quality. For large refactors, protocols, migrations, or other consistency-sensitive work, prefer a fixed model and switch manually only when needed.

Be Careful with Free Providers

The README highlights Kiro, OpenCode Free, Vertex, and also notes that some old free tiers have changed or are no longer recommended.

Always confirm provider policy at the time of use:

  • Is it really free?
  • Is it region-limited?
  • Is third-party tool access allowed?
  • Can it trigger bans or rate limits?
  • Does the free quota expire?

9Router manages routing, not upstream terms. Be especially careful when using personal subscriptions, OAuth tokens, or free quotas with automated tools.

Local Deployment Advice

For personal use, bind to localhost. Local tools can reach it, but the internet cannot.

For VPS or LAN deployment:

  • Change the default login password.
  • Set a strong JWT_SECRET.
  • Set API_KEY_SECRET.
  • Put authentication in front of the dashboard.
  • Do not expose the dashboard directly to the public internet.
  • Require Bearer API keys for /v1/*.
  • Back up DATA_DIR.

Docker example:

1
2
3
4
5
6
7

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

Start locally first, verify providers, combos, logs, and model names, then decide whether server deployment is worth it.

Health checks beyond the dashboard

Do not depend on an undocumented /health route. First test the Web service, then the authenticated compatible API:

1
2
3

curl -fsS http://127.0.0.1:20128/dashboard > /dev/null
curl -fsS http://127.0.0.1:20128/v1/models \
  -H "Authorization: Bearer $NINE_ROUTER_KEY"

If the first fails, inspect the process, port, bind address, or reverse proxy. If only the second returns 401/403, inspect the 9Router API key. Finish acceptance with one minimal chat request and verify the provider selected by the combo rule.

Docker users can also check the container and its latest logs:

1
2

docker ps --filter name=9router
docker logs --tail 100 9router

Diagnose upstream failures from logs

DATA_DIR stores db.json, usage.json, and log.txt:

1
2

export DATA_DIR="${DATA_DIR:-$HOME/.9router}"
tail -n 100 "$DATA_DIR/log.txt"
  • 401/403: expired provider credential, missing permission, or broken OAuth grant.
  • 429: quota or rate limit; verify that fallback selected the next tier.
  • 5xx, timeout, DNS, or TLS: likely upstream or network-path failure.
  • Fallback selected but still failed: inspect every provider in the combo.

ENABLE_REQUEST_LOGS=true adds request-level diagnostics but can persist sensitive data. Enable it briefly, restrict permissions, and turn it off after troubleshooting.

Back up and restore the data directory

Stop writes and archive the entire directory:

1
2
3
4

export DATA_DIR="${DATA_DIR:-$HOME/.9router}"
pm2 stop 9router
tar -C "$DATA_DIR" -czf "$HOME/9router-backup-$(date +%Y%m%d-%H%M%S).tgz" .
pm2 start 9router

The archive may contain provider credentials and API keys. To restore, stop the service, move the current directory aside, extract into an empty DATA_DIR, and validate before restarting:

1
2
3
4

python -m json.tool "$DATA_DIR/db.json" > /dev/null
python -m json.tool "$DATA_DIR/usage.json" > /dev/null
pm2 start 9router
tail -n 100 "$DATA_DIR/log.txt"

For Docker, back up the host directory or volume mapped to /app/data while the container is stopped, then repeat the dashboard, /v1/models, and minimal-chat checks.

Who Should Use It

9Router is a good fit if you use multiple AI coding tools, multiple providers, subscription plus free or cheap tiers, and want a central fallback policy. It is less useful if you only use one model and one tool.

Its real value is turning scattered model access into a configurable local routing layer.

Summary

9Router is a local gateway for AI coding tools. It lets Claude Code, Codex, Cursor, Cline, and similar tools talk to http://localhost:20128/v1, while it handles model selection, format translation, token compression, quota tracking, and fallback.

It is best for heavy AI coding users who already switch between providers. Start with one tool and one provider, then add accounts and combos gradually.

FAQ

What is this project?

It is an AI tooling project covered in this article, with a focus on what it does, how to use it, and when it is worth trying.

Who is it for?

It is mainly for developers and AI tool users who want a practical way to connect the project to real workflows rather than only read the README.

What should I check before using it?

Check installation method, supported tools, data and permission boundaries, and whether the project is still changing quickly.

Is it suitable for production use?

Treat it as a tool to test carefully first. Verify behavior on a small workflow before applying it to sensitive or production tasks.

References