9Router is a local gateway for AI coding clients. Your editor or CLI talks to one address, normally http://localhost:20128/v1, while 9Router handles provider authentication, request translation, usage records, and fallback.
That is different from a provider switcher that rewrites each client’s configuration. Once a client points at 9Router, changes happen behind the endpoint. The benefit is central control. The cost is a new service that can see prompts, hold credentials, and spend quota.
How 9Router routes a request
The project is a Next.js application with API routes for its dashboard and compatibility endpoints. Its routing and streaming layers translate between OpenAI, Anthropic, Gemini, Ollama, and other supported formats.
flowchart LR A[Coding client] --> B[localhost:20128] B --> C[Authentication and model alias] C --> D[Protocol translation] D --> E[Primary model or account] E -->|error or limit| F[Fallback model] E --> G[Streaming response] F --> G G --> A
Core parts
| Compatibility endpoints | Accept client requests under /v1 and other documented API paths |
|---|---|
| Provider connections | Store OAuth or API-key-backed upstream accounts |
| Aliases and combos | Give clients stable model names with ordered fallbacks |
| Streaming core | Normalizes provider events and returns a client-compatible stream |
| Usage records | Tracks requests, tokens, and configured prices |
| Local database | Stores state in the selected data directory |
Install from npm or Docker
The repository documents a global npm path:
npm install -g 9router
9routerIt also publishes Docker images. A local container keeps persistent state in a mounted directory:
docker run -d \
--name 9router \
-p 127.0.0.1:20128:20128 \
-v "$HOME/.9router:/app/data" \
-e DATA_DIR=/app/data \
decolua/9router:latestThe repository example publishes port 20128 on all interfaces. The version above binds it to 127.0.0.1 for a workstation. Use a reverse proxy with authentication and TLS if remote access is intentional.
Open http://localhost:20128/dashboard, create the local client key, and add one provider. Do not begin with a long fallback chain. One known-good route makes troubleshooting much easier.
Connect a coding client
For an OpenAI-compatible editor, use the local endpoint, the API key issued by 9Router, and a model alias from its dashboard:
Base URL: http://127.0.0.1:20128/v1
API key: your local 9Router client key
Model: your configured aliasDo not copy model names from promotional examples. Provider catalogs change, and examples can retain an old Claude, GLM, or Gemini ID after the router itself has moved on. Select from the live dashboard.
Current Codex uses the Responses wire protocol. Confirm that the installed 9Router release supports its current Responses event stream and use the project’s Codex integration. An environment variable alone may not override a custom Codex provider correctly. The Codex custom provider guide explains the client side.
Build a fallback combo
A combo is an ordered model sequence. Start with two routes:
- A primary model that you have tested with the client’s tool calls.
- A fallback using a separate provider or account.
Trigger conditions matter. Authentication failures, quota limits, network timeouts, and invalid request formats are not equivalent. Retrying a malformed request against five providers creates noise without fixing the request. Configure fallback for errors that another route can realistically solve.
Account rotation also needs restraint. Round-robin can distribute legitimate team traffic, but it must not be used to bypass provider restrictions. Keep an audit trail that maps every connected account to its owner and allowed use.
Token compression claims
9Router includes RTK and other request-shaping options intended to reduce tool-result input. The repository advertises percentage savings, but real savings depend on the task, tool output, and compression settings. Measure your own workload before budgeting around a headline percentage.
Compression changes what the model receives. A shortened build log may be fine; a shortened stack trace can remove the line that explains the failure. Begin with non-destructive test repositories and compare results with compression disabled.
Security decisions
The gateway can read prompts and responses because it translates them. It can also hold OAuth tokens and API keys. Keep the dashboard private, use a separate client key, and limit filesystem access to its data directory.
Request logs may contain source code, file paths, prompts, and tool output. Decide how long to retain them. Disable detailed logging when the diagnostic benefit does not justify the data exposure.
Cloud sync is optional. Synchronizing router state across devices is convenient, but credentials then leave the local machine. Use an encrypted, access-controlled target and verify what fields the sync feature includes.
When a gateway is too much
A direct provider connection is easier to audit when one client uses one model. It removes a database, translation layer, dashboard, and local service from the request path. Start directly unless you need shared aliases, account pools, usage records, or fallback between genuinely independent providers.
9Router is also not a guaranteed availability layer. Several routes can still depend on the same internet connection, identity provider, or upstream cloud. A malformed request may fail everywhere. For a work-critical setup, monitor the gateway itself and keep a documented direct-provider recovery path.
Teams with compliance requirements should review logging, data retention, cloud sync, and every connected provider before routing source code through it. Local hosting controls the gateway process; it does not make an upstream API local.
Troubleshooting
If the dashboard opens but clients fail, call one route through the dashboard or a simple API request. That separates upstream authentication from client configuration. A 401 from the local endpoint usually concerns the 9Router client key; a provider 401 concerns the upstream connection.
Streaming hangs can come from the client, router, or provider. Update 9Router, disable the combo, and test one model. Recent release notes include fixes for stream stalls and Codex behavior, which makes version checking relevant here.
If OpenClaw or another Node client resolves localhost to IPv6 while the service listens only on IPv4, use 127.0.0.1. For Docker, confirm the port binding and mounted data path before deleting or recreating the container.
9Router deployment check
- Install from the official npm package, source repository, or container image
- Bind port 20128 to localhost on a workstation
- Protect the data directory and exclude it from source control
- Test one provider before creating a combo
- Use model IDs from the live dashboard
- Verify streaming, tool calls, and edits with the actual client
- Measure compression on your workload before enabling it broadly
9Router is useful when several clients need one endpoint and centralized fallback. A lighter single-client setup may be easier with LiteLLM or a direct provider. For desktop configuration management rather than routing, see CC Switch.
