Skip to main content
kRouter

Core concepts

Providers, combos, account routing, token savers, MITM mode, quota tracking, the response cache and remote access: the eight ideas behind kRouter.

Eight ideas. Read this first if you want to understand what kRouter is doing.

1. Providers

A provider is one upstream AI service: Claude Code, Antigravity, GLM, Kiro, OpenRouter and so on. kRouter supports 95+ of them, plus any OpenAI-compatible or Anthropic-compatible endpoint you add yourself. Each has its own sign-in and its own API format; kRouter hides both behind one local endpoint.

The dashboard groups them by how you connect:

  • OAuth: sign in with a subscription you already have (Claude Code, OpenAI Codex, GitHub Copilot, Antigravity, Cursor, Grok CLI and others)
  • Free: no payment (Kiro, OpenCode Free, MiMo Code Free and others)
  • Free tier: an API key from a platform with a free allowance (OpenRouter, NVIDIA NIM, Vertex AI, Gemini, Cloudflare Workers AI and others)
  • API key: pay per token (OpenAI, Anthropic, DeepSeek, GLM, MiniMax, Kimi and the rest)
  • Browser cookie: paste a session cookie (Grok Web, Perplexity Web)

Model names are <provider-alias>/<model-id>, for example cc/claude-sonnet-4-6. Details in Providers.

2. Combos and fallback

A combo is a named list of provider/model IDs. Call the combo's name as if it were a model, and kRouter tries the entries until one succeeds. That is how you put a subscription, a cheap API key and a free provider behind one model name.

Combo: "always-on"
  1. cc/claude-opus-4-7        subscription
  2. glm/glm-5.1               cheap API key
  3. kr/claude-sonnet-4.5      free

When the Claude Code account is rate limited or out of quota, the request goes on to GLM, and if GLM fails too, to Kiro. Your tool only sees an error when every entry fails. Details in Combos & fallback.

3. Account routing

Connect several accounts of one provider and kRouter picks one per request. The default, labelled Fill First under Settings, actually runs Zenith: it scores each account on recent success rate, response time and remaining quota, and picks the highest score. Round-robin, P2C and random are also available, globally or per provider. Details in The Zenith Routing Engine.

4. Token savers

Agents resend long tool output on every turn. kRouter can shrink a request before it leaves your machine:

  • RTK is the only saver on by default. It compresses tool output in the request (git diff and status, grep, find, ls, tree, file reads, logs, build output) and leaves anything under 500 bytes alone. The project estimates 20-40% fewer input tokens on tool-heavy requests.
  • Caveman and Ponytail add a system prompt that asks for shorter answers. Off by default.
  • Headroom and PXPIPE compress long context. Off by default, and both need an extra install.

A client can skip all of them for one request with the header X-9Router-Token-Saver: off. Details in Token Savers.

5. MITM mode

A few apps talk to a fixed backend that you cannot change: Antigravity, GitHub Copilot, Kiro IDE and Claude Desktop. To route them through kRouter anyway, MITM mode installs a local root certificate, points those apps' hostnames at 127.0.0.1 in your hosts file, and answers on port 443. Chat requests go through kRouter; everything else passes through unchanged.

It is a man-in-the-middle setup in the technical sense: kRouter ends the TLS connection with its own certificate. It needs admin rights, does not work inside Docker, and stays off until you turn it on for a tool on the dashboard's MITM page. Cursor is not supported by MITM; reach it through the tunnel instead (see Getting Started).

6. Quota tracking

For providers that report usage (Claude Code, Codex, GitHub Copilot, Antigravity, Kiro, Gemini CLI, Qoder, GLM, MiniMax and a few more), the Quota Tracker page shows used and remaining quota per account, and when it resets.

Routing uses the same numbers:

  • Accounts under 30% remaining are scored down.
  • Combos try the entry with the most quota left first.
  • When a provider names an exact reset time, that model is parked on that account until then (6 hours at most), instead of being retried every few minutes.
  • A 429 on an account whose quota data says plenty is left is treated as a per-minute limit: the account sits out for 90 seconds, not the full reset window.

7. Response cache

Off by default. When you turn it on, kRouter answers repeats of an identical non-streaming request from memory for 300 seconds, as long as the request sets no temperature or one of 0.3 or lower. That catches warm-up probes, title generation and retried structured output. Cached replies carry an X-Cache: HIT header. Antigravity and Gemini models are never cached.

8. Network exposure, tunnel and Tailscale

kRouter listens on all interfaces (0.0.0.0) by default, so other devices on your network can reach it. They still need an API key for /v1/* and a login for the dashboard. Start it with --host 127.0.0.1 to keep it on this machine.

To reach kRouter from outside your network, turn on the built-in tunnel on the Endpoint page: Cloudflare's tunnel by default, or Tailscale. Dashboard login through the tunnel is allowed by default; switch off Allow dashboard access via tunnel on the same page to block it.

Where to go next