Skip to content
Back to search

9routerx

9RouterX (9R Next Go Generation): Single-binary Go AI router, LLM gateway & 20-40% token saver. Route Claude Code, Cursor & Codex across 155 providers, 28 OAuth & 248 free models (24 keyless) — OpenAI, Claude, Gemini, DeepSeek, Groq, Ollama & MCP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/yanstd888/9routerx with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/yanstd888/9routerx'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yanstd888--9routerx/badge.svg)](/listings/yanstd888--9routerx)

HTML

<a href="/listings/yanstd888--9routerx"><img src="/api/listings/yanstd888--9routerx/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Install 9RouterX, create your local gateway API key in the dashboard on port `20128`, and execute your first routed completion in 3 steps.

1. Install 9RouterX

Upgrading from 9Router? Data carries over automatically; run `9routerx service take-over` to replace the old gateway and its autostart in one step ([migration guide](wiki/migration.md)).

**Option A — Via npm (Recommended for Linux, macOS, and Windows):** requires Node.js **>= 18**.

npm install -g 9routerx

**Option B — Via Official Installer Script (Linux / macOS / Windows):**

# Linux & macOS
curl -fsSL https://raw.githubusercontent.com/yanstd888/9routerx/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/yanstd888/9routerx/main/install.ps1 | iex

**Option C — Prebuilt Standalone Binaries:**

Download the standalone archive for `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`, or `win32-x64` directly from [GitHub Releases](https://github.com/yanstd888/9routerx/releases).

2. Start & Create API Key

9routerx
# Dashboard: http://localhost:20128 (Default password: 123456 — change in Settings → Profile)
# Next: Settings → API Keys → Create Key → copy your key (sk-...)

* **Default Login:** First login uses the default compatibility password `123456`. Change it immediately in **Settings → Profile**. * **Gateway Auth Note:** `RequireApiKey` (`internal/middleware/auth.go`) validates client keys against your local SQLite database (`0 keys configured = 401 Authentication required`). Always create at least one gateway API key (`sk-...`) in **Settings → API Keys** before sending requests.

3. Send Your First Request (OpenCode, No Upstream Login)

Once you have created your local gateway key (`sk-YOUR-KEY`), test with `oc/big-pickle` from OpenCode Free without an upstream login. For `antigravity/gemini-3.7-flash-medium`, sign in with Google through Antigravity once first (free); no user-supplied upstream API key is needed.

curl http://127.0.0.1:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR-KEY" \
  -d '{
    "model": "oc/big-pickle",
    "messages": [
      {"role": "user", "content": "Verify 9RouterX local gateway on port 20128 in one sentence."}
    ]
  }'

Keep the Terminal Free (Background Mode)

Run 9RouterX as a background daemon without tying up an active terminal session:

9routerx start          # launch in background (writes DATA_DIR/run/gateway.pid)
9routerx status         # check running PID and active port
9routerx restart        # restart background instance
9routerx logs -n 100    # tail the last 100 lines of DATA_DIR/run/gateway.log
9routerx stop           # stop the background daemon

* **PID & Logs:** Background state is stored in `DATA_DIR/run/gateway.pid` and daemon output is written to `DATA_DIR/run/gateway.log`. * **Windows Note:** On Windows, `9routerx stop` uses `TerminateProcess` (which skips graceful in-flight drain). For a graceful drain on Windows, trigger **Shutdown** from the web dashboard or use `9routerx restart`.

Running with Docker (GHCR)

Run 9RouterX in a container with persistent SQLite storage mounted on port `20128`:

docker run -d \
  --name 9routerx \
  --restart unless-stopped \
  -p 20128:20128 \
  -v ~/.9router:/data \
  -e DATA_DIR=/data \
  ghcr.io/yanstd888/9routerx:latest

* **Experimental Builds:** To test bleeding-edge commits from the experimental branch, pull `ghcr.io/yanstd888/9routerx:exp` (`docker pull ghcr.io/yanstd888/9routerx:exp`). Experimental workflow builds only publish to the `exp` tag and never overwrite `latest`.

Install Alternatives & Build from Source

**Release binary:** download from [GitHub Releases](https://github.com/yanstd888/9routerx/releases/latest) and verify against `SHA256SUMS.txt`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 531 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. ![9RouterX — Local AI Router, LLM Gateway, and Token Saver Single Binary](docs/9routerx-readme-hero-motion.gif)
  3. # 9RouterX — FREE AI Router & Token Saver (Single Binary)
  4. **High-performance local AI gateway and OpenAI/Anthropic-compatible LLM router compiled into a single Go binary.**
  5. Cut tool-output token consumption by **20–40%**, automate multi-tier failover (**Subscription → Cheap → Free**), and route across **155 AI providers** and **248 free models** with zero Node.js runtime overhead.
  6. **9RouterX is the self-hosted 9Router & LiteLLM alternative** — one native Go binary you own: per-key financial governance, semantic cache, and 248 free models (24 keyless) running locally on port `20128`.
  7. If 9RouterX helps your workflow, please give the repository a star — it helps other developers discover the project.
  8. <a href="https://trendshift.io/repositories/348263?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-348263" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/348263/daily?language=Go" alt="yanstd888%2F9routerx | Trendshift" width="250" height="55"/></a> <br>
  9. [![CI](https://github.com/yanstd888/9routerx/actions/workflows/ci.yml/badge.svg)](https://github.com/yanstd888/9routerx/actions/workflows/ci.yml)
  10. [![Release CI](https://github.com/yanstd888/9routerx/actions/workflows/release.yml/badge.svg)](https://github.com/yanstd888/9routerx/actions/workflows/release.yml)
  11. [![npm version](https://img.shields.io/npm/v/9routerx.svg?style=flat-square&logo=npm)](https://www.npmjs.com/package/9routerx)
  12. [![npm downloads](https://img.shields.io/npm/dm/9routerx.svg?style=flat-square&label=downloads&color=22c55e)](https://www.npmjs.com/package/9routerx)
  13. [![GHCR Container](https://img.shields.io/badge/GHCR-yanstd888%2F9routerx-2496ED?style=flat-square&logo=github&logoColor=white)](https://github.com/yanstd888/9routerx/pkgs/container/9routerx)
  14. [![Container & Binary Pulls](https://img.shields.io/github/downloads/yanstd888/9routerx/total?style=flat-square&logo=docker&logoColor=blue&label=Docker%20pulls&color=0ea5e9)](https://github.com/yanstd888/9routerx/pkgs/container/9routerx)
  15. [![Telegram Community](https://img.shields.io/badge/Telegram-%40aiclub__id-26A5E4?style=flat-square&logo=telegram)](https://t.me/aiclub_id)
  16. [Quick Start](#quick-start) • [Why 9RouterX?](#why-9routerx) • [Comparison](#9routerx-vs-9router-vs-omniroute) • [Key Features](#key-features) • [Supported Clients](#supported-ai-coding-clients) • [Free Providers](#free-ai-providers-and-keyless-models-catalog) • [Database Sharing](#sharing-a-database-with-9router) • [Screenshots](#screenshots) • [Setup Guide](#setup-guide-summary-and-wiki-documentation) • [Architecture Matrix](#architecture-comparison) • [FAQ](#frequently-asked-questions-faq) • [Docs](#docs) • [Wiki](https://yanstd888.github.io/9routerx/)
  17. **155** Providers · **28** OAuth One-Click · **29** Free-Tier · **248** Free Models (**24** Keyless) · **20–40%** Token Saved · **5** Platforms · **1** Binary
  18. </div>
  19. ---
  20. > **What is 9RouterX?**
  21. >
  22. > **9RouterX** is an open-source, self-hosted AI routing gateway, local LLM API proxy, and request/response token optimizer written in Go with an embedded Svelte 5 + Vite + Tailwind 4 web dashboard (listening on default port `20128`). It exposes a unified OpenAI-compatible (`/v1/chat/completions`, `/v1/messages`, `/v1/responses`, `/v1/embeddings`, `/v1/models`), Anthropic-compatible, Ollama-compatible, MCP Server, and A2A local endpoint that connects AI coding assistants (Claude Code, Cursor, OpenAI Codex CLI, Cline, Roo Code, OpenCode, Antigravity, Gemini CLI, OpenClaw) to **155 AI providers**—comprising **91 API key services**, **28 one-click OAuth integrations**, **29 free-tier providers** (**248 cataloged free models across 36 providers**, including **24 cataloged keyless models** requiring no user-supplied upstream API key; Antigravity requires one Google OAuth login), and **4 web cookie providers**.
  23. ## Why 9RouterX?
  24. AI-assisted software engineering workflows suffer from fragmented monthly subscriptions, sudden upstream rate limits, runaway token billing, and bloated CLI tool context windows. 9RouterX resolves these operational bottlenecks locally at the gateway layer before requests leave your machine:
  25. * **Unused Monthly Quotas & Rate-Limit Interruptions → Smart 3-Tier Cascade (`Subscription → Cheap → Free`):** Stop losing unused monthly subscription credits or hitting `429 Too Many Requests` in the middle of a complex multi-file refactor. 9RouterX prioritizes your active **Subscription** tier first (via 28 one-click OAuth or 4 web cookie providers), overflows seamlessly to **Cheap API** providers (such as DeepSeek, Groq, Fireworks, or Nebius), and automatically falls back to **Free-Tier / Keyless** models (`248 free models across 36 providers`, including `24 keyless models`) when primary limits are exhausted.
  26. * **Verbose CLI & Tool-Call Outputs → 20–40% Token Saver Suite:** Autonomous coding agents regularly burn tens of thousands of input tokens reading raw terminal logs, directory trees, build outputs, and repetitive JSON responses. Built-in RTK compression (`internal/tokensaver`, `internal/compression`), **50+ ready-made per-tool output filters** (`git diff`, `git log`, `grep`, `ripgrep`, `docker logs`, `npm install`, `pnpm`, `cargo build`, `go test`, `terraform plan`, `kubectl`, `pytest`, and friends), GCF/tabular headroom compression (`internal/compression/gcf`, `internal/headroom`), context squeezing, and output style directives (`Caveman`, `Ponytail`, `ADHD`, and `Anti-Slop` modes) strip redundant noise before forwarding requests upstream.
  27. * **Uncontrolled API Spend → Per-Key Financial Governance & Guardrails:** Enforce strict daily USD spending ceilings with hard cutoffs checked when each request starts (`internal/budget`), per-key request rate limits, CIDR/IP whitelists, per-key system prompt injection, and scoped endpoint permissions (`internal/policy`, `internal/guardrails`, `internal/keikey`) before distributing local gateway keys (`sk-...`) to autonomous agents, CI pipelines, or team members.
  28. * **Silent Endpoint Failures & Broken Tool Calls → Active Health Probing & Auto-Repair:** Upstream LLM providers frequently return malformed JSON tool-call arguments, truncated schemas, or suffer silent latency degradation. 9RouterX repairs broken tool-call structures in transit (`tool-call repair fallback`), guards against SSRF dispatch and leaks via PII masking, and continuously tracks live endpoint health (`internal/modelhealth`, `internal/resilience`) with a 3-tier circuit breaker to bypass degraded nodes automatically.
  29. * **Redundant Repeated Prompts → Semantic, Prompt & Sticky TTL Caching:** Reduce round-trip latency and API token billing through local vector-similarity semantic caching (`internal/semanticcache`), automatic upstream prompt cache header passthrough (`internal/promptcache`), **cache-aware sticky TTL routing** (saving up to ~90% on cached input reads), and zero-allocation FastJSON parsing (`internal/fastjson`).
  30. * **Heavy Runtime Dependencies → Single Self-Contained Go Binary:** No Node.js runtime memory bloat, no Python virtual environments, and no external PostgreSQL or Redis containers required. Everything—including the reactive Svelte 5 dashboard, SQLite storage engine, MCP server, and MITM inspector—runs from a single native binary across Linux (`x64`/`arm64`), macOS (`x64`/`arm64`), and Windows (`x64`).
  31. ## 9RouterX vs 9Router vs OmniRoute
  32. 9RouterX is an independent Go + Svelte 5 evolution of 9Router (`decolua/9router` and `luqman-v1/9router-go`) that expanded its own enterprise governance and token-saving architecture, sitting in the same self-hosted gateway space as OmniRoute (`cheaper-inference/OmniRoute`). Every row in the table below states a verifiable fact—where an architectural trait has no standardized public benchmark behind it, it is explicitly labeled *On paper* rather than given a synthetic number. Star counts were checked live on **Nov 14, 2026**; evaluate each gateway by its operational requirements and feature rows.
  33. | Metric / Capability | **9RouterX** (This Repo) | **9Router** (`decolua`) | **OmniRoute** (`cheaper-inference`) |
  34. | :--- | :--- | :--- | :--- |
  35. | **GitHub Stars (Nov 14, 2026)** | 68 | 32,422 | 87,366 |
  36. | **Language / Runtime** | **Go, single native binary + Svelte 5 dashboard** | JavaScript / Node.js + Next.js | TypeScript / Node.js |
  37. | **Installation Footprint** | **One native binary (~48 MB linux-amd64), zero runtime dependencies** | `npm i -g 9router` (6 deps, requires Node.js runtime) | npm (~105 deps) / Docker / pnpm |
  38. | **Supported Providers** | **155** (`91 API` · `28 OAuth` · `29 free` · `4 cookie`) | 40+ | 375–380 (150+ free) |
  39. | **Cataloged Free Models** | **248 across 36 providers (24 keyless)** | 100+ | 1,400+ models (~1.62B free tokens/mo) |
  40. | **Embedded Dashboard** | **Svelte 5 + Vite + Tailwind 4, embedded in binary** | Next.js React web app | Desktop / PWA |
  41. | **Database Engine** | **Embedded SQLite, drop-in schema-compatible** | Same SQLite schema | SQLite |
  42. | **Behavior Under Heavy Traffic** | *On paper:* a compiled native Go process—one process for the gateway, dashboard, and SQLite engine, with no V8 heap or GC pauses growing with the request queue. Measure on your own workload. | *On paper:* Node.js runtime (V8 + single-threaded event loop); sustained throughput depends on Node version and warm-up state. | *On paper:* Node.js runtime, same event-loop and V8 heap considerations. |
  43. | **Latency Profile** | *On paper:* zero cold-start tax after boot; hot request paths use allocation-conscious Go routines and FastJSON. | *On paper:* first-request warm-up on the Node/Next.js side. | *On paper:* first-request warm-up on the Node side. |
  44. ### What 9RouterX Adds on Top of 9Router
  45. 9RouterX preserves 100% SQLite database compatibility with upstream 9Router while adding a dedicated optimization and security stack:
  46. * **Full Per-Key Governance:** Daily USD hard cutoffs checked at request start, per-key rate limits, IP whitelists, reusable plan templates, SSRF dispatch protection, and PII masking (versus basic key authentication).
  47. * **Token Saver Suite:** 20–40% RTK compression, 50+ per-tool CLI output filters, GCF/tabular headroom compression, context squeezer, output style directives (`Caveman`, `Ponytail`, `ADHD`, `Anti-Slop`), and automated tool-call repair fallback.
  48. * **Multi-Layer Caching & Resilience:** Semantic cache + prompt cache passthrough + cache-aware sticky TTL routing, windowed-LRU rotation, auto-prune for dead credentials, and burn-in account recovery.
  49. * **Expanded Free & Keyless Catalog:** 248 free models across 36 providers (including 24 keyless models).
  50. * **Advanced Protocols & Ops Modules:** Built-in MCP Server, A2A protocol, TLS stealth fingerprinting, MITM traffic inspector, multi-target webhooks, Telegram bot alerts, encrypted credential Vault, and one-command service migration (`9routerx service take-over`).
  51. ### Where OmniRoute is Bigger
  52. OmniRoute's upstream catalog is larger, stated plainly: roughly 375–380 providers (150+ of them free), 1,400+ models, a pooled ~1.62B free tokens/month allowance, 20 routing strategies, and quota-aware fallback. That catalog breadth is their core strength. Where **9RouterX** differs: it ships as **one compiled Go binary with zero runtime dependencies** (versus an npm installation pulling ~105 packages), stays lightweight enough for **small self-hosted VPS instances or edge hardware**, enforces **granular per-key financial governance and RTK/GCF tool compression**, and embeds the **Svelte 5 dashboard directly inside the binary**. Compare features against your infrastructure requirements—neither replaces the other.
  53. ### Go + Svelte 5 vs a Node.js Stack
  54. The architectural difference manifests in day-to-day operations (*on paper throughout — measure on your own workload*):
  55. * **Single-File Distribution:** One native executable per platform (`linux-x64`, `linux-arm64`, `win32-x64`, `darwin-x64`, `darwin-arm64`) versus `npm install` pulling a Node.js runtime dependency tree and `node_modules`.
  56. * **Instant Cold Start:** The compiled Go gateway serves its first completion request immediately upon process boot without waiting for JIT/module graph warm-up.
  57. * **Predictable Memory Footprint:** Compiled Go services of comparable scope typically idle with a smaller resident memory footprint than Node.js/Next.js servers.
  58. * **Concurrency Under Load:** Concurrent streaming connections are multiplexed across lightweight Go goroutines rather than competing on a single-threaded V8 event loop.
  59. * **Atomic Self-Updates:** Updating swaps a single binary (`9routerx update` or container image pull) without rebuilding local package trees.
  60. ## System Architecture
  61. ```text
  62. AI Coding Clients (Claude Code, Cursor, Codex, Cline, OpenCode, Gemini CLI, OpenClaw)
  63. │
  64. http://localhost:20128/v1 (OpenAI / Anthropic / MCP / A2A)
  65. ▼
  66. ┌─────────────────────────────────────────────────────────────────────────────────────┐
  67. │ 9RouterX Single Go Binary │
  68. │ ┌────────────────────────┐ ┌────────────────────────┐ ┌───────────────────────┐ │
  69. │ │ Governance & Policy │→ │ Token Saver Suite │→ │ Semantic & Prompt │ │
  70. │ │ • Daily Cost Cutoff │ │ • RTK Compression │ │ Caching │ │
  71. │ │ • Rate Limit / IP WL │ │ • 50+ Tool Filters │ │ • Vector Similarity │ │
  72. │ │ • Guardrails & Vault │ │ • GCF / Headroom │ │ • Sticky TTL (~90%) │ │
  73. │ │ • PII Mask / SSRF Grd │ │ • Tool-Call Repair │ │ • FastJSON Engine │ │
  74. │ └────────────────────────┘ └────────────────────────┘ └───────────────────────┘ │
  75. │ │ │
  76. │ ▼ │
  77. │ ┌───────────────────────────────────────────────────────────────────────────────┐ │
  78. │ │ Smart Combo Router & Resilience Engine (Model Health Probes) │ │
  79. │ │ Strategies: Fallback │ Round-Robin │ Sticky TTL │ Capacity │ Fusion │ Auto │ │
  80. │ └───────────────┬────────────────────────┬────────────────────────┬─────────────┘ │
  81. └──────────────────┼────────────────────────┼────────────────────────┼────────────────┘
  82. ▼ ▼ ▼
  83. [Tier 1: Subscription] [Tier 2: Cheap API] [Tier 3: Free / Keyless]
  84. 28 One-Click OAuth + 91 API Key Providers 248 Free Models across
  85. 4 Web Cookie Providers (DeepSeek, Groq...) 36 Providers (24 Keyless)
  86. ```
  87. ## Key Features
  88. | Feature Group | Capabilities & Internal Modules |
  89. | :--- | :--- |
  90. | **Routing & Fallback** | **Auto 3-Tier Fallback** (`Subscription → Cheap → Free`), **Combo Routing** (`fallback`, `round-robin`, `sticky`, `capacity`, `fusion`, `cache-optimized`, `auto`, `quota-weighted`, `reset-aware` via `internal/routing`, `internal/combos` & `internal/combopresets`), multi-account round-robin load balancing, active **Model Health** probing (`internal/modelhealth`), and 3-stage circuit-breaker resilience (`internal/resilience`). |
  91. | **Token Saver Suite** | **20–40% tool-output token savings** (`internal/tokensaver`, `internal/compression`), **RTK Compression**, **50+ ready-made per-tool output filters** (for `git diff`, `grep`, `docker logs`, `npm install`, `terraform plan`, and friends), **GCF/Tabular Headroom** (`internal/compression/gcf`, `internal/headroom`), **Context Squeezer** for long histories, **Output Style Directives** (`Caveman`, `Ponytail`, `ADHD`), **Anti-Slop Injector** (`internal/tokensaver/antislop`), and automated **Tool-Call Repair Fallback**. |
  92. | **Governance per Key** | **Daily Cost Ceiling + Hard Cutoff** (`internal/budget`, checked per request), per-key request rate limits, **IP Whitelist**, per-key custom system prompts, granular endpoint permissions, reusable **Plan Templates** (`internal/policy`, `internal/guardrails`, `internal/keikey`), SSRF dispatch protection, PII masking, encrypted credential storage (`internal/vault`, `internal/sessionvault`), and audit logs (`internal/securitylog`). |
  93. | **Providers & Auth** | **155 total providers**: **91 API Key** providers, **28 One-Click OAuth** integrations, **29 Free-Tier** providers, and **4 Web Cookie** providers (`internal/browsercookies`, `internal/browserlogin`). Supports custom OpenAI-/Anthropic-compatible base URLs, custom HTTP headers, Kiro `external_idp` JSON auth import, dual-column cookie paste parser (Gemini/Grok Web), per-key proxy pools, and Codex quota tracking (`internal/codexquota`). |
  94. | **Free Tier & Keyless** | **29 free-tier providers** (23 `CategoryFreeTier` + 6 `CategoryFree`) and **248 free models cataloged across 36 providers**, including **24 cataloged keyless models** without a user-supplied upstream API key (`antigravity`, `opencode`, `blackbox`); Antigravity requires Google OAuth login once. Tracks daily, monthly, credit, one-time, and uncapped quota regimes automatically. |
  95. | **Cache & Performance** | **Semantic Cache** (`internal/semanticcache`) for vector-matched query deduplication, upstream **Prompt Cache** optimization (`internal/promptcache`), **Cache-Aware Sticky TTL** (reduces cached input costs by up to ~90%), and high-throughput **FastJSON** serialization (`internal/fastjson`). |
  96. | **Observability** | **Extended Logging + Payload Inspector**, custom usage analytics windows (`12h`, `14d`, custom date ranges), Tremor-inspired data visualizations (`bits-ui` + `layerchart`), distributed **Tracing** (`internal/tracing`, `internal/observ`), **Uptime** monitoring (`internal/uptime`), **Security Log**, multi-target **Webhooks + Notifications** (`internal/notifications`), and **Telegram Bot** alerts (`internal/telegram`). |
  97. | **Infra & Extras** | **Single Go Binary** across 5 OS/arch targets, background daemon CLI (`start`/`stop`/`restart`/`status`/`logs`), one-command migration (`9routerx service take-over`), Docker container (`ghcr.io`), desktop **Tray App**, built-in **Tunnel** (`internal/tunnel`), self-**Updater** (`internal/updater`), encrypted **Sync Bundle** backup/restore (`internal/syncbundle`), **TLS Stealth** (`internal/tlsstealth`), **MITM Traffic Inspection** (`internal/mitm`), **MCP Server** (`internal/mcpserver`), **A2A Protocol** (`internal/a2a`), and **Media TTS/STT**. |
  98. ### v1.2 Cost & Resilience Controls (Conservative Opt-In Defaults)
  99. All advanced v1.2 cost-reduction and account-protection mechanisms ship **disabled (`OFF`) by default** to guarantee predictable baseline behavior until explicitly enabled by the operator:
  100. | Control Feature | Environment / Config Flag | Default | Operational Impact |
  101. | :--- | :--- | :---: | :--- |
  102. | **Cache-Aware Sticky TTL** | Combo strategy `ttl` mode (`5m` Claude default, up to `60m` Gemini) | `OFF` | Pins consecutive requests to the same warm upstream account within the vendor's prompt-cache window so cached prefixes are reused instead of re-billed—delivering **up to ~90% input-cost reduction on cache hits** (e.g., Anthropic bills cached reads at ~10% of standard input pricing). |
  103. | **Windowed-LRU Rotation** | `ROTATION_WINDOW=N` | `OFF` | Restricts round-robin selection to the top `N` active candidate connections to prevent pool-wide rate-limit burn-in across large account pools. |
  104. | **Dead-Credential Auto-Prune** | `AUTOPRUNE_ENABLED` (supports dry-run mode) | `OFF` | Automatically deactivates upstream connections after consecutive permanent credential failures (`401 Unauthorized`, `403 Banned`, `402 Payment Required`). |
  105. | **Account Burn-In Protection** | `BURNIN_ENABLED` | `OFF` | Guides degraded accounts through an automated **Suspect → Heal (1-in-5 request throttle) → Rescue (temporary rotation quarantine)** recovery cycle. |
  106. ## Quick Start
  107. Install 9RouterX, create your local gateway API key in the dashboard on port `20128`, and execute your first routed completion in 3 steps.
  108. ### 1. Install 9RouterX
  109. > **Upgrading from 9Router?** Your existing SQLite data carries over automatically. Run `9routerx service take-over` to replace the legacy gateway process and its system autostart service in a single step (see the [Installation & Migration Guide](https://yanstd888.github.io/9routerx/installation.html)).
  110. **Option A — Via npm (Recommended for Linux, macOS, and Windows; requires Node.js >= 18 for wrapper install only):**
  111. ```bash
  112. npm install -g 9routerx
  113. ```
  114. **Option B — Via Official Installer Script (Linux / macOS / Windows):**
  115. ```bash
  116. # Linux & macOS
  117. curl -fsSL [https://raw.githubusercontent.com/yanstd888/9routerx/main/install.sh](https://raw.githubusercontent.com/yanstd888/9routerx/main/install.sh) | sh
  118. # Windows (PowerShell)
  119. irm [https://raw.githubusercontent.com/yanstd888/9routerx/main/install.ps1](https://raw.githubusercontent.com/yanstd888/9routerx/main/install.ps1) | iex
  120. ```
  121. **Option C — Prebuilt Standalone Binaries:**
  122. Download the standalone archive for `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`, or `win32-x64` directly from [GitHub Releases](https://github.com/yanstd888/9routerx/releases).
  123. ### 2. Start & Create API Key
  124. ```bash
  125. 9routerx
  126. # Dashboard: http://localhost:20128 (Default password: 123456 — change in Settings → Profile)
  127. # Next: Settings → API Keys → Create Key → copy your key (sk-...)
  128. ```
  129. * **Default Login:** First login uses the default compatibility password `123456`. Change it immediately in **Settings → Profile**.
  130. * **Gateway Auth Note:** `RequireApiKey` (`internal/middleware/auth.go`) validates client keys against your local SQLite database (`0 keys configured = 401 Authentication required`). Always create at least one gateway API key (`sk-...`) in **Settings → API Keys** before sending requests.
  131. ### 3. Send Your First Request (OpenCode Keyless, Zero Upstream Login)
  132. Once you have created your local gateway key (`sk-YOUR-KEY`), test immediately with `oc/big-pickle` from OpenCode Free without any upstream login. To test `antigravity/gemini-3.7-flash-medium`, sign in with Google through Antigravity once first (free); no user-supplied upstream API key is needed.
  133. ```bash
  134. curl [http://127.0.0.1:20128/v1/chat/completions](http://127.0.0.1:20128/v1/chat/completions) \
  135. -H "Content-Type: application/json" \
  136. -H "Authorization: Bearer sk-YOUR-KEY" \
  137. -d '{
  138. "model": "oc/big-pickle",
  139. "messages": [
  140. {"role": "user", "content": "Verify 9RouterX local gateway on port 20128 in one sentence."}
  141. ]
  142. }'
  143. ```
  144. ### Keep the Terminal Free (Background Mode)
  145. Run 9RouterX as a background daemon without tying up an active terminal session:
  146. ```bash
  147. 9routerx start # launch in background (writes DATA_DIR/run/gateway.pid)
  148. 9routerx status # check running PID and active port
  149. 9routerx restart # restart background instance
  150. 9routerx logs -n 100 # tail the last 100 lines of DATA_DIR/run/gateway.log
  151. 9routerx stop # stop the background daemon
  152. 9routerx service take-over # migrate from legacy 9Router service & take over autostart
  153. 9routerx version # print running binary version & build metadata
  154. ```
  155. * **PID & Logs:** Background state is stored in `DATA_DIR/run/gateway.pid` and daemon output is written to `DATA_DIR/run/gateway.log`.
  156. * **Windows Note:** On Windows, `9routerx stop` uses `TerminateProcess` (which skips graceful in-flight drain). For a graceful drain on Windows, trigger **Shutdown** from the web dashboard or use `9routerx restart`.
  157. ### Running with Docker (GHCR)
  158. Run 9RouterX in a container with persistent SQLite storage mounted on port `20128`:
  159. ```bash
  160. docker run -d \
  161. --name 9routerx \
  162. --restart unless-stopped \
  163. -p 20128:20128 \
  164. -v ~/.9router:/data \
  165. -e DATA_DIR=/data \
  166. ghcr.io/yanstd888/9routerx:latest
  167. ```
  168. * **Experimental Builds:** To test bleeding-edge commits from the experimental branch, pull `ghcr.io/yanstd888/9routerx:exp` (`docker pull ghcr.io/yanstd888/9routerx:exp`). Experimental workflow builds only publish to the `exp` tag and never overwrite `latest`.
  169. ### Install Alternatives & Build from Source
  170. **Release binary:** download from [GitHub Releases](https://github.com/yanstd888/9routerx/releases/latest) and verify against `SHA256SUMS.txt`.
  171. **Experimental builds:** unpublished work ships as experimental builds — GitHub Releases marks them **Pre-release** (so `9routerx update` keeps pointing at stable), and GHCR tags them `exp` (`ghcr.io/yanstd888/9routerx:exp`), never `latest`. Opt in only to help shake out bugs.
  172. **Build from source:** prerequisites Go 1.27 and Bun 1.x (dashboard is embedded into the binary, so build web first) — then `make build`. Full flags and steps: [wiki — installation](https://yanstd888.github.io/9routerx/installation.html).
  173. **Start on boot:** autostart/service installation is documented in the wiki — [installation](https://yanstd888.github.io/9routerx/installation.html).
  174. ## Sharing a Database with 9Router
  175. 9RouterX is engineered as a drop-in compatible upgrade for existing **9Router** and **9router-go** installations. It listens on the exact same default port (`20128`) and opens the same `DATA_DIR/db/data.sqlite` database—meaning your configured **providers, OAuth connections, combos, client API keys, and usage history carry over automatically without migration**.
  176. | Deployment Mode | Default `DATA_DIR` / SQLite Database Path |
  177. | :--- | :--- |
  178. | **Linux / macOS (Native)** | `~/.9router` (opens `~/.9router/db/data.sqlite`) |
  179. | **Windows (Native)** | `%APPDATA%\9router` (opens `%APPDATA%\9router\db\data.sqlite`) |
  180. | **Docker Container** | Mount host `~/.9router:/data` with `-e DATA_DIR=/data` |
  181. * **Caveat:** Do not run both 9Router and 9RouterX against the same SQLite file simultaneously. Stop the old process first (or run `9routerx service take-over` / back up `data.sqlite` before switching) so only one binary holds the SQLite write lock.
  182. ## Screenshots
  183. Every screen ships in dark and light themes, at desktop and mobile widths. The
  184. full gallery — with per-page commentary — lives on the wiki's
  185. [**Screenshots**](https://yanstd888.github.io/9routerx/screenshots.html) page.
  186. | | Dark | Light |
  187. |---|---|---|
  188. | **Providers** — connect AI providers and manage custom OpenAI/Anthropic-compatible endpoints | ![Providers view, dark theme — the provider catalog and connection list in the 9RouterX dashboard](docs/screenshots/providers.png) | ![Providers view, light theme — the same provider catalog and connection list in light mode](docs/screenshots/providers-light.png) |
  189. ## Supported AI Coding Clients
  190. 9RouterX works out of the box with any OpenAI-compatible, Anthropic-compatible, Responses API, Ollama-compatible, MCP, or A2A client:
  191. * **Claude Code** (`@anthropic-ai/claude-code`)
  192. * **OpenAI Codex CLI**
  193. * **Cursor**
  194. * **Antigravity**
  195. * **Gemini CLI**
  196. * **OpenCode**
  197. * **Cline / Roo Code**
  198. * **OpenClaw**
  199. > **IPv6 Resolution Note (`localhost` vs `127.0.0.1`):** Some CLI tools (upstream documentation specifically notes **OpenClaw** and certain Node/Go CLIs) may resolve `localhost` to IPv6 `::1` first and fail to connect. If a client refuses to connect via `localhost`, use explicit IPv4 **`http://127.0.0.1:20128`** instead.
  200. ### Example 1: Claude Code Setup
  201. Route Claude Code through `http://localhost:20128` to enable 20–40% tool-output token compression, 50+ per-tool filters, and multi-provider failover:
  202. ```bash
  203. export ANTHROPIC_BASE_URL="http://localhost:20128"
  204. export ANTHROPIC_API_KEY="sk-YOUR-KEY"
  205. claude
  206. ```
  207. ### Example 2: Codex / OpenCode / OpenClaw (Explicit IPv4 `127.0.0.1`)
  208. ```bash
  209. export OPENAI_BASE_URL="[http://127.0.0.1:20128/v1](http://127.0.0.1:20128/v1)"
  210. export OPENAI_API_KEY="sk-YOUR-KEY"
  211. ```
  212. ### Example 3: Cline / Cursor JSON Configuration
  213. ```json
  214. {
  215. "apiProvider": "openai-compatible",
  216. "openAiBaseUrl": "[http://127.0.0.1:20128/v1](http://127.0.0.1:20128/v1)",
  217. "openAiApiKey": "sk-YOUR-KEY",
  218. "openAiModelId": "oc/big-pickle"
  219. }
  220. ```
  221. ### Example 4: Gemini CLI / Custom Anthropic-Compatible Clients
  222. ```bash
  223. export GEMINI_API_BASE_URL="[http://127.0.0.1:20128/v1](http://127.0.0.1:20128/v1)"
  224. export GEMINI_API_KEY="sk-YOUR-KEY"
  225. ```
  226. ## Free AI Providers and Keyless Models Catalog
  227. 9RouterX includes a built-in catalog of **248 free models across 36 providers** (verified in `freemodels.go`), featuring **24 cataloged keyless models** (`antigravity`, `opencode`, `blackbox`) without a user-supplied upstream API key. Antigravity requires Google OAuth login once (free); OpenCode offers zero-login access. Gemini Web requires a browser login/session cookie.
  228. ### Supported Free Quota Regimes
  229. * **`keyless`**: No user-supplied upstream provider API key (`antigravity`, `opencode`, `blackbox`). Antigravity requires Google OAuth login once; OpenCode and the cataloged Blackbox free endpoint do not require an upstream login.
  230. * **`recurring-daily`**: Free request or token allowance resets automatically every 24 hours.
  231. * **`recurring-monthly`**: Free quota refreshes each calendar or billing month.
  232. * **`recurring-credit`**: Periodic free credit grants replenished by the provider.
  233. * **`recurring-uncapped`**: Rate-limited free endpoints without hard lifetime exhaustion caps.
  234. * **`one-time-initial`**: Initial trial credit pool granted upon account creation.
  235. ### Complete Free Provider Directory (36 Providers · 248 Free Models)
  236. | Provider | Model free | Keyless | Quota / Access Regime |
  237. | :--- | :---: | :---: | :--- |
  238. | `bazaarlink` | 32 | — | Free API tier (`recurring-daily` / `recurring-uncapped`) |
  239. | `bluesminds` | 22 | — | Free API tier (`recurring-daily` / `recurring-uncapped`) |
  240. | `vertex` | 21 | — | Google Cloud credits / free tier (`one-time-initial` / `recurring-credit`) |
  241. | `kilo-gateway` | 12 | — | Free gateway tier (`recurring-daily`) |
  242. | `fireworks` | 10 | — | Initial / recurring free inference credits (`one-time-initial`) |
  243. | `antigravity` | 9 | 9 | **Free after Google OAuth login once; no user-supplied upstream API key (e.g. `gemini-3.7-flash-high/medium/low`)** |
  244. | `opencode` | 9 | 9 | **Keyless (`keyless` — zero upstream setup, e.g. `oc/big-pickle`)** |
  245. | `cloudflare-ai` | 9 | — | Recurring daily free Workers AI neurons (`recurring-daily`) |
  246. | `qoder` | 9 | — | One-click OAuth free coding tier (`recurring-daily` / `recurring-monthly`) |
  247. | `opencode-zen` | 9 | — | Free developer coding tier (`recurring-daily`) |
  248. | `ollama` | 8 | — | Local / free cloud endpoints (`recurring-uncapped`) |
  249. | `hyperbolic` | 8 | — | Initial trial inference credits (`one-time-initial`) |
  250. | `nous` | 7 | — | Nous Research free API tier (`recurring-credit` / `one-time-initial`) |
  251. | `api-airforce` | 7 | — | Recurring daily / uncapped free tier (`recurring-daily`) |
  252. | `kiro` | 7 | — | Free developer tier + `external_idp` auth support (`recurring-monthly`) |
  253. | `blackbox` | 6 | 6 | **Keyless (`keyless` — zero upstream setup)** |
  254. | `cohere` | 6 | — | Recurring monthly trial evaluation key (`recurring-monthly`) |
  255. | `huggingface` | 6 | — | Serverless inference API free tier (`recurring-daily`) |
  256. | `groq` | 5 | — | Recurring daily high-speed LPU free tier (`recurring-daily`) |
  257. | `mistral` | 5 | — | La Plateforme experiment free tier (`recurring-monthly`) |
  258. | `sambanova` | 5 | — | Recurring free developer cloud tier (`recurring-daily`) |
  259. | `glm-cn` | 4 | — | One-click OAuth / Zhipu CN free models (`recurring-daily`) |
  260. | `gemini` | 4 | — | Google AI Studio recurring daily free tier (`recurring-daily`) |
  261. | `nvidia` | 4 | — | NVIDIA NIM developer free credit tier (`one-time-initial` / `recurring-credit`) |
  262. | `llm7` | 4 | — | One-click OAuth free routing tier (`recurring-daily`) |
  263. | `openrouter` | 3 | — | Recurring `:free` and `openrouter/auto` model endpoints (`recurring-daily`) |
  264. | `agnes` | 3 | — | Free API inference tier (`recurring-daily`) |
  265. | `glm` | 2 | — | Zhipu GLM global free models (`recurring-daily`) |
  266. | `cerebras` | 2 | — | Recurring daily wafer-scale free inference tier (`recurring-daily`) |
  267. | `deepseek` | 2 | — | Initial credit / off-peak developer tier (`one-time-initial`) |
  268. | `morph` | 2 | — | Fast code-apply free developer tier (`recurring-monthly`) |
  269. | `tokenharbor` | 2 | — | Free API routing tier (`recurring-daily`) |
  270. | `baidu` | 1 | — | Ernie / Qianfan free model (`recurring-daily`) |
  271. | `nebius` | 1 | — | Nebius AI Studio trial credit free model (`one-time-initial`) |
  272. | `sensenova` | 1 | — | SenseTime free model endpoint (`recurring-daily`) |
  273. | `tencent` | 1 | — | Tencent Hunyuan free model endpoint (`recurring-daily`) |
  274. | **Total (36 Providers)** | **248** | **24** | **Verified in `freemodels.go`** |
  275. ## Provider Categories Breakdown (155 Providers)
  276. 9RouterX organizes its **155 supported providers** into four distinct authentication architectures:
  277. 1. **91 API Key Providers:** Standard bearer token providers including OpenAI, Anthropic, Google Gemini, Groq, DeepSeek, Fireworks, Mistral, Cohere, Cerebras, SambaNova, NVIDIA NIM, OpenRouter, xAI, Together AI, Perplexity, Hyperbolic, Nebius, Cloudflare Workers AI, and 70+ global and regional inference platforms.
  278. 2. **28 One-Click OAuth Providers:** Authenticate directly from the web dashboard without manually copying static tokens:
  279. `antigravity`, `claude`, `cline`, `clinepass`, `codebuddy-cn`, `codebuddy-intl`, `codex`, `cursor`, `github`, `gitlab`, `glm-cn`, `grok-cli`, `iflow`, `jina-reader`, `kilocode`, `kimi`, `llm7`, `minimax-code-global`, `muse`, `qoder`, `qoder-cn`, `runcrate`, `topaz`, `voyage-ai`, `xai`, `xiaomi-mimo`, `zcode`, `zed`.
  280. 3. **29 Free-Tier Providers:** Dedicated zero-cost provider configurations (**23 `CategoryFreeTier` + 6 `CategoryFree`**) engineered for automated fallback routing when paid quotas expire.
  281. 4. **4 Web Cookie Providers:** Session-authenticated browser integrations powered by the internal `browsercookies` and `browserlogin` encrypted vault modules, featuring a dual-column cookie input with an auto-split paste parser for Gemini Web and Grok Web session cookies.
  282. ### Adding a Custom Provider
  283. You can register any custom OpenAI-compatible or Anthropic-compatible upstream server directly in the dashboard (`http://localhost:20128` → **Providers** → **Add Custom**):
  284. * Set custom base URLs for local or private inference servers (vLLM, Ollama, llama.cpp, LM Studio, LiteLLM, or enterprise gateways).
  285. * Inject custom HTTP authentication or routing headers per provider.
  286. * Attach dedicated per-key outbound HTTP/SOCKS5 proxy pools and configure SSRF dispatch guard rules.
  287. ## Embedded Dashboard Overview
  288. 9RouterX compiles a reactive **Svelte 5 + Vite + Tailwind 4** management interface (built with `shadcn-svelte`, `bits-ui`, and `layerchart`) directly into the Go binary at `http://localhost:20128` (default password: `123456`):
  289. * **Token Saver & Compression Analytics:** Monitor real-time 20–40% token reduction ratios, RTK compression metrics, **50+ ready-made per-tool output filters**, GCF/tabular headroom stats, output style directives (`Caveman`, `Ponytail`, `ADHD`, `Anti-Slop`), context squeezer activity, and semantic cache hit rates.
  290. * **Connections & 1-Click OAuth Manager:** Dual-column cookie input with auto-split paste parser for Gemini Web and Grok Web session cookies. Configure all 155 providers, trigger browser OAuth flows for 28 providers, import Kiro `external_idp` JSON credentials, inspect live model health latency, and assemble multi-tier combo routing presets (`fallback`, `round-robin`, `sticky`, `capacity`, `fusion`, `cache-optimized`, `auto`, `quota-weighted`, `reset-aware`).
  291. * **Per-Key Governance & Custom Usage Ranges:** Issue client API keys (`sk-...`) with daily USD cutoffs enforced at request start, request rate limits, IP whitelists, and custom system prompts; inspect Tremor-style usage charts across `12h`, `14d`, or custom date ranges; and inspect full request/response JSON payloads in the Extended Logging & Payload Inspector.
  292. ## Setup Guide Summary and Wiki Documentation
  293. For advanced deployment and module configuration, refer to the [**Official 9RouterX Documentation & Wiki**](https://yanstd888.github.io/9routerx/):
  294. * [**Installation, Background CLI & Docker Guide**](https://yanstd888.github.io/9routerx/installation.html) — Custom port configuration (default `20128`), daemon commands (`start`/`stop`/`restart`/`status`/`logs`), one-step `9routerx service take-over`, autostart on boot, desktop tray mode, and GHCR containers.
  295. * [**Client Setup Guide**](https://yanstd888.github.io/9routerx/client-setup.html) — Ready-to-copy snippets for Claude Code, Cursor, Codex CLI, Cline, OpenCode, and OpenClaw.
  296. * [**Combo Routing & 3-Tier Failover**](https://yanstd888.github.io/9routerx/) — Setting up `Subscription → Cheap → Free` cascades plus `fallback`, `round-robin`, `sticky` (with cache-aware TTL), `capacity`, and `fusion` strategies.
  297. * [**Token Saver, RTK Compression & 50+ Tool Filters**](https://yanstd888.github.io/9routerx/) — Tuning compression aggressiveness, per-tool CLI output filters, GCF tabular compression, Caveman/Ponytail/ADHD directives, anti-slop rules, and tool-call repair.
  298. * [**Key Governance, Budgets & Alerts**](https://yanstd888.github.io/9routerx/) — Configuring daily USD cost cutoffs, plan templates, SSRF/PII guards, multi-target webhooks, and Telegram bot notifications.
  299. * [**MCP Server, A2A, MITM & TLS Stealth**](https://yanstd888.github.io/9routerx/) — Connecting Model Context Protocol clients, Agent-to-Agent workflows, inspecting traffic on `http://localhost:20128`, and syncing encrypted configuration bundles.
  300. ## Architecture Comparison
  301. Factual capability matrix comparing **9RouterX**, upstream **9router-go**, and the original **9Router (Next.js)**:
  302. | Capability / Metric | **9RouterX** (This Repository) | **9router-go** (Upstream Port) | **9Router** (Original Next.js) |
  303. | :--- | :--- | :--- | :--- |
  304. | **Runtime Binary** | **Single Native Go Binary** | Single Native Go Binary | Node.js + Next.js Runtime |
  305. | **Default Port** | **`20128`** | `20128` | `20128` |
  306. | **Database Compatibility** | **Drop-in `DATA_DIR/db/data.sqlite` sharing** | `DATA_DIR/db/data.sqlite` | `~/.9router/db/data.sqlite` |
  307. | **Embedded Dashboard** | **Svelte 5 + Vite + Tailwind 4 (`shadcn-svelte` + `layerchart`)** | Embedded Web UI | Next.js React Web App |
  308. | **Supported Providers** | **155 Providers (`91 API` · `28 OAuth` · `29 Free` · `4 Cookie`)** | Core Provider Subset | Core JS Providers |
  309. | **Cataloged Free Models** | **248 Free Models across 36 Providers (24 Keyless)** | Static Subset | Manual Configuration |
  310. | **Token Saver Suite** | **20–40% RTK Compression, 50+ Tool Filters, GCF Headroom, Context Squeezer, Tool Repair** | Not Included | Not Included |
  311. | **Per-Key Governance** | **Daily Cost Cutoff, Request Limits, IP Whitelist, Plan Templates, PII Masking** | Basic Key Auth | Basic Key Auth |
  312. | **Caching Layer** | **Semantic Cache + Prompt Cache + Sticky TTL (~90% Read Savings) + FastJSON** | Passthrough | Passthrough |
  313. | **Resilience Controls** | **3-Tier Circuit Breaker, Windowed-LRU, Auto-Prune, Burn-In Protection** | Basic Failover | Basic Failover |
  314. | **Advanced Modules** | **MCP Server, A2A, TLS Stealth, MITM Inspector, Multi-Target Webhooks, Telegram Bot, Vault** | Core Proxy Routing | Core Proxy Routing |
  315. | **Supported Platforms** | **5 Platforms** (`linux-x64`, `linux-arm64`, `win32-x64`, `darwin-x64`, `darwin-arm64`) | Go Target Builds | Requires Node.js Environment |
  316. ## Claude Web (Unofficial, Opt-in)
  317. 9RouterX can also drive claude.ai's web interface with the `sessionKey` browser cookie through a provider named `claude-web`. **It is disabled by default and it is not part of the free-tier catalog.** Enable it with `CLAUDE_WEB_ENABLED=true` or the toggle in Dashboard → Web Cookie Providers; `CLAUDE_WEB_ENABLED=false` is the operator kill-switch that always wins.
  318. Be clear about what this lane is before enabling it:
  319. - It violates [Anthropic's terms of service](https://www.anthropic.com/legal/consumer-terms) — the account you paste the cookie from risks restriction or ban.
  320. - It is unofficial and unverified against a live session: claude.ai can change or remove the endpoints at any time, and when it breaks there is no support and no fix on any schedule.
  321. - The session key is a full-account credential: it never leaves the gateway except inside the Cookie header, but anyone with dashboard access can read the stored connection, so treat it like a password.
  322. - Usage is estimated locally (characters per token); claude.ai reports no counts on this lane.
  323. If you enable it anyway: paste the `sessionKey` cookie from a logged-in claude.ai browser into the connection's API-key field, keep the toggle on, and point your client's model at `claude-web`.
  324. ## Frequently Asked Questions (FAQ)
  325. <details>
  326. <summary><strong>1. Does 9RouterX support Claude Code, Cursor, Codex, and Cline?</strong></summary>
  327. Yes. 9RouterX exposes Anthropic-compatible (`http://localhost:20128`), OpenAI-compatible (`http://localhost:20128/v1`), Responses API, and Ollama-compatible endpoints, alongside built-in MCP Server and A2A protocol support. You can connect Claude Code, Cursor, OpenAI Codex CLI, Cline, Roo Code, OpenCode, OpenClaw (use explicit IPv4 `http://127.0.0.1:20128`), Antigravity, and Gemini CLI directly to port `20128`.
  328. </details>
  329. <details>
  330. <summary><strong>2. Is 9RouterX free, and how do the 24 keyless models work?</strong></summary>
  331. Yes. 9RouterX is free and open-source software (MIT License) that runs locally as a single binary with no proxy markup fees. It ships with **29 free-tier providers** and **248 cataloged free models across 36 providers**, including **24 cataloged keyless models** (`antigravity`, `opencode`, `blackbox`) without a user-supplied upstream API key. Antigravity (for example `antigravity/gemini-3.7-flash-medium`) requires a Google OAuth login once, which is free. Use `oc/big-pickle` from OpenCode for a zero-login test. Create a local 9RouterX gateway key in Settings → API Keys → Create Key (`http://localhost:20128`, default password `123456`) before making API requests; 0 keys returns `401 Authentication required`.
  332. </details>
  333. <details>
  334. <summary><strong>3. How is 9RouterX different from LiteLLM or OpenRouter?</strong></summary>
  335. * **Versus OpenRouter:** OpenRouter is a cloud intermediary that adds per-token markup fees and routes prompts through external third-party servers. 9RouterX runs **100% locally on your machine** as a single binary with zero markup.
  336. * **Versus LiteLLM:** LiteLLM requires a Python environment; advanced budget/usage tracking needs external databases (PostgreSQL/Redis). **9RouterX** compiles a full AI gateway, **Svelte 5 dashboard**, **20–40% Token Saver suite (with 50+ per-tool filters)**, **semantic cache**, **per-key USD budget cutoffs checked at request start**, and **28 one-click OAuth flows** into a **single zero-dependency Go binary** backed by an embedded SQLite file.
  337. </details>
  338. <details>
  339. <summary><strong>4. How does the 20–40% Token Saver work without breaking code generation?</strong></summary>
  340. AI coding agents consume massive context windows when reading CLI outputs, directory listings, and tool responses. 9RouterX's `tokensaver` and `compression` modules apply RTK compression, **50+ ready-made per-tool output filters** (`git diff`, `grep`, `docker logs`, `npm install`, `terraform plan`), GCF tabular headroom compression, context squeezing, output style directives (`Caveman`, `Ponytail`, `ADHD`), and anti-slop rules to tool outputs in transit—cutting 20–40% of token volume while repairing malformed JSON tool calls automatically.
  341. </details>
  342. <details>
  343. <summary><strong>5. Can I migrate from 9Router or 9router-go without losing my keys and combos?</strong></summary>
  344. Yes. 9RouterX shares the exact same default port (`20128`) and SQLite database schema (`DATA_DIR/db/data.sqlite`). Run `9routerx service take-over` (or stop your existing 9Router instance and start 9RouterX)—all providers, OAuth connections, combos, client API keys, and usage statistics carry over immediately without migration scripts.
  345. </details>
  346. <details>
  347. <summary><strong>6. What happens when my primary AI subscription hits a rate limit?</strong></summary>
  348. When a request hits a `429` rate limit, quota exhaustion, or upstream `5xx` error, 9RouterX's `resilience` circuit breaker and `modelhealth` probes automatically cascade the request through your configured combo tier (**Subscription OAuth → Cheap API Key → Free-Tier / Keyless**) without dropping your active coding session.
  349. </details>
  350. <details>
  351. <summary><strong>7. How do I run 9RouterX in the background or update to the latest release?</strong></summary>
  352. Use the built-in daemon commands: `9routerx start`, `9routerx status`, `9routerx restart`, `9routerx logs -n 100`, and `9routerx stop`. To update, run `npm install -g 9routerx@latest`, `9routerx update`, or pull the latest GHCR container (`ghcr.io/yanstd888/9routerx:latest`).
  353. </details>
  354. ## Contributing
  355. Issues and pull requests use templates, so pick the right one rather than opening a blank report:
  356. - **Bug report** — something behaves incorrectly. Include a reproduction, `9routerx version`, OS, and the log excerpt around the failure.
  357. - **Feature request** — the problem you cannot solve today, the surface it touches, and whether upstream already has it.
  358. - **Question** — configuration and usage help.
  359. PRs follow the checks CI runs: `go vet ./...`, `go test -count=1 ./...`, `make test-integration`, plus `cd web && bun test` and `make vet-svelte` for anything touching the dashboard. Before writing code, skim [`AGENTS.md`](AGENTS.md) — provider isolation and the Go/Svelte conventions keep reviews fast.
  360. ## Docs
  361. **Full documentation, searchable:** [**9routerx Wiki**](https://yanstd888.github.io/9routerx/) — installation, usage, API reference, dashboard, providers, governance, architecture, database, CLI, and a screenshot gallery. Every page supports `?q=` search and `#section` deep links.
  362. Repository references:
  363. - [`ARCHITECTURE.md`](ARCHITECTURE.md) — routing, providers, runtime layout
  364. - [`DATABASE.md`](DATABASE.md) — SQLite schema & operator contract
  365. - [`CHANGELOG.md`](CHANGELOG.md) — release history. Work merged since the last tag lives in `.changes/` fragments and is folded in at the next release; the dashboard's changelog modal shows both. Check what you are running with `9routerx version`.
  366. ## Acknowledgments
  367. | Repository | Stars | Contribution to 9RouterX |
  368. |---|---|---|
  369. | [decolua/9router](https://github.com/decolua/9router) | ![stars](https://img.shields.io/github/stars/decolua/9router?style=social) | the original Next.js gateway & dashboard that 9RouterX preserves compatibility with (same SQLite data dir, no-migration upgrade path) |
  370. | [luqman-v1/9router-go](https://github.com/luqman-v1/9router-go) | ![stars](https://img.shields.io/github/stars/luqman-v1/9router-go?style=social) | the Go + Svelte port 9RouterX continues from; gateway core, provider lanes, CLI |
  371. | [serenhope/9router](https://github.com/serenhope/9router) | ![stars](https://img.shields.io/github/stars/serenhope/9router?style=social) | per-key governance, token-saver suite, security log, web executors, dashboard features ported into 9RouterX |
  372. | [cheaper-inference/OmniRoute](https://github.com/cheaper-inference/OmniRoute) | ![stars](https://img.shields.io/github/stars/cheaper-inference/OmniRoute?style=social) | SSRF dispatch guard + PII masking, routing strategies, circuit breaker, multi-target webhooks, Tremor-style data-viz patterns |
  373. | [router-for-me/CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) | ![stars](https://img.shields.io/github/stars/router-for-me/CLIProxyAPI?style=social) | Kiro `external_idp` auth JSON importer (port of their auth format, see `internal/handlers/oauth/kiro_external_idp.go`) |
  374. | [rtk-ai/rtk](https://github.com/rtk-ai/rtk) | ![stars](https://img.shields.io/github/stars/rtk-ai/rtk?style=social) | the request-side token-compression concept behind the RTK Token Saver (20-40% input savings) |
  375. | [headroomlabs-ai/headroom](https://github.com/headroomlabs-ai/headroom) | ![stars](https://img.shields.io/github/stars/headroomlabs-ai/headroom?style=social) | GCF/tabular compression concepts ported into `internal/compression/gcf` and `internal/headroom` |
  376. | [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman) | ![stars](https://img.shields.io/github/stars/JuliusBrussee/caveman?style=social) | the terse-output style directive (Caveman mode, `internal/tokensaver/caveman.go`) |
  377. | [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) | ![stars](https://img.shields.io/github/stars/DietrichGebert/ponytail?style=social) | the structured-output style directive (Ponytail mode) |
  378. | [ayghri/i-have-adhd](https://github.com/ayghri/i-have-adhd) | ![stars](https://img.shields.io/github/stars/ayghri/i-have-adhd?style=social) | the scannable/bulleted output style (ADHD mode) |
  379. | [miqdadbadjuber/anti-slop](https://github.com/miqdadbadjuber/anti-slop) | ![stars](https://img.shields.io/github/stars/miqdadbadjuber/anti-slop?style=social) | antislop injector rules bundled in `internal/tokensaver/antislop` with their original text and attribution preserved |
  380. | [huntabyte/shadcn-svelte](https://github.com/huntabyte/shadcn-svelte) | ![stars](https://img.shields.io/github/stars/huntabyte/shadcn-svelte?style=social) | the dashboard component layer (chart, table, tooltip, separator via bits-ui + layerchart) |
  381. 9RouterX stands on this lineage — thank you to the upstream maintainers and their communities for the gateway, the port, and the ideas this project builds on. The complete three-layer ownership inventory (inherited / ported / original) lives in [ATTRIBUTION.md](ATTRIBUTION.md), and everyone whose commit landed in the repository is credited on the wiki's [**Owner & Contributors**](https://yanstd888.github.io/9routerx/team.html) page.
  382. ## Star History
  383. [![Star History Chart](https://api.star-history.com/chart?repos=yanstd888/9routerx&type=date&legend=top-left)](https://www.star-history.com/?repos=yanstd888%2F9routerx&type=date&legend=top-left)
  384. ## License
  385. MIT License — see [`LICENSE`](https://github.com/yanstd888/9routerx/blob/main/LICENSE).
  386. ---
  387. ## Attribution
  388. **9RouterX — all source code port and modification by [yanstd888](https://github.com/yanstd888/) — [t.me/aiclub_id](https://t.me/aiclub_id).**
  389. This repository is an independent Go + Svelte port of [9Router](https://github.com/decolua/9router) (MIT); all port and modification work is by Muhammad Dian (yanstd888). Re-hosting this code without the LICENSE copyright notice and this attribution violates the MIT license terms. For the full file-by-file ownership breakdown, see [`ATTRIBUTION.md`](ATTRIBUTION.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.