9Router: A Local Gateway That Puts Free and Cheap Models Behind One OpenAI Endpoint

The problem 9Router targets: one endpoint, many quotas

A developer using Claude Code, Cursor and Codex at the same time is managing three billing relationships, three rate limit policies and three sets of credentials. When one provider throttles mid-session, the usual fix is to edit a config file, paste a different key and restart the tool. The README frames this as the cost of the current toolchain: subscription quota expires unused, rate limits stop you mid-coding, and tool outputs such as git diff, grep and ls burn tokens quickly.

9Router's answer is to insert a local process between the coding tool and the providers. The tool keeps pointing at one base URL, http://localhost:20128/v1, and the router decides which upstream account serves each request. The target user is an individual developer or a small team running coding agents locally, not a platform team building a multi-tenant inference service. The project is published on npm as 9router and as a container image at decolua/9router, and the repository's own package is named 9router-app and marked private, so the source tree is the development path rather than the published artifact.

How the routing tiers and RTK compression actually work

The README describes a three-tier cascade. Tier 1 is subscription capacity from Claude Code, Codex or GitHub Copilot. When that quota is exhausted the router moves to Tier 2, cheap paid models the README prices at GLM $0.6 per 1M tokens and MiniMax $0.2 per 1M. When a budget limit is reached it falls to Tier 3, which the README lists as Kiro, OpenCode Free and Vertex credits. The stated goal is that a request never fails outright because one upstream is unavailable.

Two supporting mechanisms sit around that cascade. The first is format translation between OpenAI-shaped and Claude-shaped request and response bodies, which is what lets a tool that speaks one dialect talk to a provider that speaks the other. The second is RTK, described as automatic compression of tool_result content with a claimed 20 to 40 percent token saving per request. That number is the project's own claim; the README does not publish the corpus, the prompts or the measurement method behind it, so treat it as a design target rather than a measured result. Compression of tool output is also where the most interesting trade-off lives: a truncated git diff or a summarized grep result is cheaper, but the model sees less. There is no documented switch in the README for disabling RTK per request, so if you need byte-exact tool output you should verify that before adopting.

The deployment layout in docker-compose.yml shows a second container alongside the router: headroom, from ghcr.io/chopratejas/headroom, exposed on port 8787 and referenced through HEADROOM_URL. The compose file does not explain what headroom does, and the README does not describe it either, so its role is not something this article can confirm. The router container mounts a named volume, 9router-data, mapped to DATA_DIR=/app/data, which is where persistent state lives.

Installing 9Router and pointing Claude Code at it

The README's quick start is two commands: install the package globally and run it. The dashboard then opens on port 20128.

npm install -g 9router
9router

After that, the README's next step is to connect a provider from the dashboard. It names Kiro AI, described as roughly 50 credits per month covering Claude 4.5, GLM-5 and MiniMax, and OpenCode Free, described as requiring no authentication. Then you point your coding tool at the local endpoint, using an API key copied from the dashboard and a model identifier in the form kr/claude-sonnet-4.5.

If you would rather run the source tree, the README gives this sequence, noting that the repository package is private so source or Docker execution is the expected local path:

cp .env.example .env
npm install
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev

The environment contract in .env.example marks three variables as required: JWT_SECRET, INITIAL_PASSWORD and DATA_DIR. It also lists PORT, API_KEY_SECRET, MACHINE_ID_SALT and REQUIRE_API_KEY among the recommended settings. Note the discrepancy between the README, which uses port 20128, and package.json, whose dev and start scripts pass --port 20127. The README's port is the one to follow if you want the documented URLs to work, so set PORT explicitly as shown above rather than relying on the script default.

For a container deployment, the compose file expects an .env file next to it and publishes 20128:20128:

services:
  9router:
    image: decolua/9router:latest
    ports:
      - "20128:20128"
    volumes:
      - 9router-data:/app/data
    environment:
      DATA_DIR: /app/data
      PORT: "20128"

Once the process is up, the dashboard is at http://localhost:20128/dashboard and the OpenAI-compatible API at http://localhost:20128/v1. In Claude Code, Cursor, Cline or Codex, you set the endpoint to the /v1 URL, paste the dashboard key, and pick a model.

Where 9Router breaks down: free tiers, state and silent failures

The weakest part of the pitch is the word free. The README's Tier 3 points at Kiro, OpenCode Free and Vertex credits, and the quick start leans on Kiro's roughly 50 monthly credits as the no-signup option. Those are third-party allowances that the router does not control. When a provider changes its terms, tightens a quota or starts requiring authentication, the router's fallback chain loses a link, and the failure surfaces as a request that no longer completes rather than as a clear message about which upstream refused. There is no documented health check or preflight command in the README for validating that each configured provider still works.

State is the second concern. The compose file mounts 9router-data into DATA_DIR, and .env.example sets DATA_DIR to /var/lib/9router for a non-container install. That directory holds the router's configuration and account state. The README does not document a backup, export or migration procedure for it, so a lost volume means reconnecting providers by hand. If you run this on a laptop, that is an inconvenience. If you run it on a shared host for a team, it is a single point of failure with no documented recovery path.

Security defaults deserve a look too. .env.example ships REQUIRE_API_KEY=false and AUTH_COOKIE_SECURE=false, and marks both as recommended settings rather than required ones. A router that holds upstream provider credentials and listens on a port should not be reachable from a network you do not control with those defaults. The Dockerfile also rewrites Alpine's package repositories to mirrors.aliyun.com in the base stage, which will affect build speed and reachability depending on where you build. None of this is disqualifying for a local tool, but it means the defaults are tuned for a laptop, not for an exposed host.

Alternatives and how their approach differs

The closest comparison is LiteLLM. Both expose an OpenAI-compatible endpoint in front of many providers, and both do format translation and fallback. The difference is the center of gravity. LiteLLM is a Python proxy aimed at teams, with a configuration file that declares models and routing rules, and it is typically deployed as a shared service. 9Router is a Node application with a web dashboard, aimed at an individual developer's machine, and its distinguishing features are the RTK token compression and the quota-tracking view of subscription accounts. If your requirement is a declarative config checked into a repository and reviewed like code, LiteLLM's model fits better. If your requirement is a dashboard that shows how much of this month's Claude Code quota is left, 9Router is doing something LiteLLM does not emphasize.

A second option is to skip the router entirely and use each provider's own CLI with its own credentials, switching manually. That costs you the fallback behavior and the token savings, but it removes a local process that holds every key you own. For a developer with a single subscription and no rate limit problems, the router adds a component without removing a task. The value only appears when you actually run into quotas or juggle multiple accounts.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-05, which is recent enough that the project is being worked on. The release cadence visible in the changelog is fast: v0.5.18 on 2026-07-03, v0.5.20 four days later, v0.5.35 on 2026-07-16, while package.json carries version 0.5.75. Releases at that pace mean frequent updates and a moving target for anyone pinning a version. The changelog entries mix feature work (Grok Imagine video, a Copilot Claude route, thinking-level pickers) with provider fixes, which is the pattern you would expect from a project whose correctness depends on third-party APIs that change without notice.

Upgrade cost is mostly operational. The router is a single process holding credentials and configuration in DATA_DIR, so an upgrade means restarting it and hoping the state format is compatible. The README does not document a migration step between versions, and there is no documented rollback procedure. Running the container with a pinned tag instead of latest is the obvious mitigation, though the compose file as written uses latest.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is permissive and unsurprising for a tool of this kind. It says nothing about the terms of the upstream providers you connect through it; those are separate agreements between you and each provider, and the repository does not speak to them. Whether routing your traffic through a local proxy is permitted by a given provider is a question for that provider's terms, not for this licence.

Editorial conclusion

Adopt 9Router if you already pay for one or two AI subscriptions and want a single local endpoint that keeps working when a quota runs out, and you are willing to run a Node process on your machine. Do not adopt it if you need a documented SLA, per-request cost accounting you can hand to finance, or a stable free tier you did not verify yourself. Before wiring it into a team workflow, check three things: whether the free providers you plan to rely on still accept your account, whether RTK compression changes the answers your prompts produce, and whether the data directory on your host is backed up, because that is where the router keeps its state.

Frequently asked questions

Official sources

1. decolua/9router on GitHub
2. License: MIT
3. Project website
4. README
5. Releases