# kRouter — Kodelyth AI Infrastructure
> Hardened, MIT-licensed, self-hosted MULTIMODAL AI gateway & token saver. Routes chat, text-to-speech, speech-to-text, image, video, embeddings, web search, and web fetch across 98+ AI providers through ONE local OpenAI-compatible endpoint at http://localhost:20128. Connects Claude Code, Cursor, Antigravity, GitHub Copilot, Codex, Kiro, OpenCode, Cline, Continue, Roo, and any OpenAI-compatible client. Saves up to 92% tokens via RTK + Caveman + Headroom + PXPIPE compression. Self-hosted Next.js + Node.js application.

## Install
- NPM (recommended): `npm install -g @sifxprime/krouter && krouter -t`
- Docker: `docker run -d -p 20128:20128 -v "$HOME/.krouter:/app/data" sifxprime/krouter:latest`
- Git (development): `git clone https://github.com/sifxprime/krouter.git && cd krouter && npm install && npm run dev`

## Documentation
- [Getting Started](https://krouter.kodelyth.com/docs/getting-started): install, configure your first provider, point your IDE at it
- [Providers](https://krouter.kodelyth.com/providers): 98+ providers with OAuth, Free, API-key, and browser-cookie setup steps
- [API Reference](https://krouter.kodelyth.com/docs/api): OpenAI-compatible chat, messages, and model-list endpoints on http://localhost:20128
- [Combos](https://krouter.kodelyth.com/docs/combos): subscription → cheap → free fallback stacks
- [CLI Reference](https://krouter.kodelyth.com/docs/cli): commands, environment variables, and troubleshooting
- [Architecture](https://krouter.kodelyth.com/docs/architecture): MITM stream layer, RTK compression, multi-tier fallback, auth race-condition handling
- [Token Savers](https://krouter.kodelyth.com/docs/token-savers): RTK, Caveman, Headroom, PXPIPE — what each compresses and how they stack
- [Routing Engine](https://krouter.kodelyth.com/docs/routing-engine): Zenith scoring, sub-5ms RAM layer, multi-account fairness, strategies
- [Multimodal & Skills](https://krouter.kodelyth.com/docs/multimodal-skills): TTS/STT/image/video/embeddings/search endpoints + agent skills
- [Deploy](https://krouter.kodelyth.com/docs/deploy): VPS, Docker, Cloudflare, PM2, environment variables

## Key Features
- **RTK Token Saver**: lossless compression of tool_result content (git diff, grep, find, ls, tree, dedup-log) before requests reach the LLM. Saves 20-40% input tokens. Default on.
- **Caveman Mode**: optional terse-response prompt injection (Lite / Full / Wenyan variants) to cut output tokens up to 65%.
- **Headroom Token Saver**: de-duplicates and compresses conversation context (repeated files, large tool outputs, long histories) via an external fail-open proxy. Measured 92.4% reduction on code-heavy requests (27,187 → 2,056 tokens). See https://krouter.kodelyth.com/docs/token-savers.
- **PXPIPE**: renders bulky context as dense PNGs (images bill by pixels, not encoded length); fail-open, runs last in the token-saver pipeline.
- **Zenith Routing Engine**: Kodelyth's proprietary AI-driven scoring engine. Instead of dumb failover, Zenith evaluates accounts based on live health data (TTFB latency, success rate) and quota headroom, picking the absolute best account mathematically to eliminate rate-limit stalls.
- **Sub-5ms RAM Layer**: In-memory HealthCache completely eliminates SQLite reads/writes from the hot path during chat routing, enabling instant sub-5ms failover when a 429 is hit.
- **3-Tier Auto-Fallback**: subscription → cheap → free combos; never stops when a quota runs out.
- **Routing Strategies**: defaults to Zenith, but supports fill-first, round-robin (sticky), p2c, and random strategies.
- **Response Cache**: in-memory cache for repeated non-streaming requests (warmup probes, title generation, structured-output retries).
- **Real-Time Quota Tracking**: per-model token counts, reset countdowns, and cost estimation pulled from each provider's backend.
- **MITM Intercept Mode**: hooks Antigravity, Kiro, Copilot, and Cursor IDE traffic to route through your provider stack.
- **Format Translation**: OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro ↔ Vertex ↔ Antigravity ↔ Ollama ↔ OpenAI Responses.
- **Multi-Account Support**: multiple accounts per provider with load balancing, atomic backoff, and cooldown handling.
- **Auto OAuth Refresh**: concurrent-safe refresh that never mutates caller credentials mid-request.
- **Tunnel / Tailscale Access**: expose the dashboard over a public tunnel or Tailscale; configurable dashboard access controls.
- **Proxy Pools**: route outbound provider requests through HTTP, Vercel, Cloudflare, or Deno proxy pools.
- **Provider SSRF Guard**: blocks cloud-metadata endpoints and non-HTTP(S) schemes in user-supplied baseUrl.
- **Usage Analytics & Request Logging**: track tokens, cost, trends, and full request/response logs for debugging.
- **Cloud Sync**: optional encrypted sync of config across devices.

## Comparison
kRouter is a hardened fork of [decolua/9router](https://github.com/decolua/9router). See [the comparison page](https://krouter.kodelyth.com/compare) for honest, side-by-side differences vs the upstream and vs OmniRoute, including: numeric vs string OAuth enums (verify-account 403 fix), per-provider concurrency, NGHTTP2 stream recovery, thinking-config preservation through the Antigravity blacklist, lazy-clear stale testStatus on read, and atomic SQLite backoff.

## Optional
- [Changelog](https://krouter.kodelyth.com/changelog)
- [Blog](https://krouter.kodelyth.com/blog)
- [GitHub](https://github.com/sifxprime/krouter)
- [npm package](https://www.npmjs.com/package/@sifxprime/krouter)
- [Docker Hub](https://hub.docker.com/r/sifxprime/krouter)
- [Upstream](https://github.com/decolua/9router)

## Multimodal Endpoints
kRouter is a full multimodal AI gateway, not just an LLM router. It proxies EIGHT modalities through one local OpenAI-compatible endpoint. Every path below is served under the base URL http://localhost:20128:
- **Chat / Code**: `http://localhost:20128/v1/chat/completions` and `http://localhost:20128/v1/messages` — Claude, GPT, Gemini, GLM, Kimi, DeepSeek, and more
- **Text-to-Speech (TTS)**: `http://localhost:20128/v1/audio/speech` — OpenAI TTS-1, GPT-4o Mini TTS, Gemini TTS, MiniMax TTS, NVIDIA FastPitch, ElevenLabs, Edge TTS, Deepgram, Cartesia, PlayHT
- **Speech-to-Text (STT)**: `http://localhost:20128/v1/audio/transcriptions` — OpenAI Whisper, GPT-4o Transcribe, Gemini STT, Groq Whisper, Deepgram, AssemblyAI
- **Image Generation**: `http://localhost:20128/v1/images/generations` — DALL-E 3, Imagen, FLUX (Black Forest Labs), MiniMax, Stable Diffusion WebUI, Recraft, ComfyUI
- **Video Generation**: `http://localhost:20128/v1/videos/generations` — Grok Imagine (xAI), RunwayML; async submit + status polling
- **Embeddings**: `http://localhost:20128/v1/embeddings` — OpenAI text-embedding-3, Gemini embedding-004, Voyage AI, Jina, NVIDIA NV-EmbedQA, Mistral embeddings
- **Web Search**: `http://localhost:20128/v1/search` — Tavily, Exa, Brave, Serper, SearXNG, Google PSE, You.com, Linkup
- **Web Fetch**: `http://localhost:20128/v1/web/fetch` — URL to markdown/text/HTML via Firecrawl, Jina Reader, Tavily, Exa

## Routing & Model Discovery
- **Zenith Routing Engine** (default): mathematically pre-ranks accounts by live TTFB latency, success rate, and quota headroom; sub-5ms in-memory HealthCache failover; decision log for visibility; multi-account fairness + exponential ban recovery. Alt strategies: fill-first, round-robin (sticky), p2c, random. See https://krouter.kodelyth.com/docs/routing-engine.
- **Live Model Catalog**: fetches the current model list from every API-key provider in real time (no hardcoded lists); `http://localhost:20128/v1/models` with cache + refresh de-dup; modality-scoped `http://localhost:20128/v1/models/{kind}`.

## Agent Skills
kRouter ships prompt-injection skill files that auto-configure AI agents. Each skill is a single GitHub URL an agent pastes into its system prompt to learn how to call kRouter's endpoints:
- `krouter` (Entry): setup, auth, model discovery
- `krouter-chat`: chat/completions and messages
- `krouter-tts`: text-to-speech generation
- `krouter-stt`: speech-to-text transcription
- `krouter-image`: image generation
- `krouter-embeddings`: vector embeddings for RAG
- `krouter-web-search`: web search queries
- `krouter-web-fetch`: URL scraping to markdown

## Dashboard Security
- **Dashboard Guard**: enforces localhost-only UI access when deployed remotely. Blocks all remote IPs unless whitelisted or protected by HTTP Basic Auth.
- **Login system**: local-only password reset, brute-force lockout, timing-safe token compare.