Skip to main content
kRouter

Getting Started

Install kRouter, connect a first provider, and point Claude Code, Codex or any OpenAI-compatible tool at it. Takes about five minutes.

kRouter is a self-hosted, MIT-licensed router for AI coding tools. It runs on your machine, connects to 95+ providers (subscriptions, free services and API keys), and serves them all from one local endpoint that speaks the OpenAI, Anthropic and Responses formats. This guide gets you from install to a working tool in three steps.

1. Install

You need Node.js 20.9 or newer; kRouter refuses to start on older versions and says so.

npm install -g @sifxprime/krouter
krouter -t

-t runs kRouter in the background with a tray icon, so you can close the terminal. Run plain krouter instead to get a menu in the terminal. The dashboard is at http://localhost:20128/dashboard: open it in your browser, or choose Open Dashboard from the tray icon.

First login: until you set a password, it is 123456, and that password is accepted only from the machine kRouter runs on. Set your own under Settings, in the Security section.

Network exposure: kRouter listens on 0.0.0.0 by default, so other devices on your network can reach it. They still need an API key for the API and a login for the dashboard. Start it with krouter -t --host 127.0.0.1 to keep it on this machine.

Prefer Docker?

KROUTER_PASSWORD="$(openssl rand -base64 18)" && echo "Dashboard password: $KROUTER_PASSWORD"
docker run -d -p 20128:20128 \
  -e INITIAL_PASSWORD="${KROUTER_PASSWORD:?run the line above first}" \
  -v "$HOME/.krouter:/app/data" --name krouter sifxprime/krouter:latest

The first line prints a random dashboard password: log in with it, then set your own under Settings → Security. Docker needs INITIAL_PASSWORD because the default 123456 only works from the machine kRouter runs on, and your browser reaches the container from outside it. MITM mode does not work inside a container. More options are in Deployment.

2. Connect a provider

For a first run, pick a provider that needs no account at all:

  • OpenCode Free: no sign-in; its model list comes from OpenCode
  • MiMo Code Free: no sign-in; serves mimo-auto

Or connect something you already have: a Claude Code, OpenAI Codex or GitHub Copilot subscription (OAuth sign-in), or an API key from OpenAI, Anthropic, OpenRouter, DeepSeek, GLM and many others. Some subscription logins are not licensed for proxy use; the dashboard shows a risk notice for those before you connect, so read it.

In the dashboard:

  1. Open Providers and choose a provider
  2. Add a connection: sign in, paste an API key, or nothing for the no-auth providers
  3. Press Test on one of its models to check that it answers

Models are named <alias>/<model-id>, for example cc/claude-sonnet-4-6 (Claude Code) or ocg/kimi-k2.6 (OpenCode Go). Providers lists the aliases.

3. Point your tool at kRouter

The dashboard's CLI Tools page writes the configuration for Claude Code, Codex, OpenCode, Cline, Kilo Code, Factory Droid and other tools, and shows step-by-step guides for the rest. Use it when you can; the manual setup is below.

API keys. Requests from the machine kRouter runs on need no key, unless you start kRouter with REQUIRE_API_KEY=true. Requests from any other machine do. Keys are on the dashboard's Endpoint page, in the API Keys section: a "Default Key" is created on your first visit, and Create Key makes more. Replace <your-krouter-key> below with one.

Claude Code. Add an env block to ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128/v1",
    "ANTHROPIC_AUTH_TOKEN": "<your-krouter-key>"
  }
}

The CLI Tools page can also choose which models fill Claude Code's Opus, Sonnet and Haiku slots.

Codex CLI. Codex reaches kRouter through the Responses API. The CLI Tools page (OpenAI Codex CLI / App) writes this to ~/.codex/config.toml for you and leaves your auth.json and ChatGPT login alone. By hand:

model = "cx/gpt-5.5"
model_provider = "krouter"
 
[model_providers.krouter]
name = "kRouter"
base_url = "http://localhost:20128/v1"
wire_api = "responses"
 
[model_providers.krouter.http_headers]
Authorization = "Bearer <your-krouter-key>"
 
[agents]
default_subagent_model = "cx/gpt-5.5"

model can be any provider/model ID or a combo name, and default_subagent_model is the default model for agents that Codex spawns. kRouter converts the Responses request for whichever provider serves the model, so Codex can run on Claude, GLM, Kimi or anything else you connected. kRouter's integration uses this model_providers entry, not OPENAI_BASE_URL, and sends your kRouter key as a static header. More in Codex CLI with any model.

Cursor. Cursor sends requests from its own servers, so it cannot reach http://localhost:20128. Turn on the Tunnel on the dashboard's Endpoint page and use that public URL, ending in /v1, as the base URL. Then in Cursor: Settings → Models, enable the OpenAI API key option, enter the base URL and a kRouter key, and add a custom model such as cc/claude-sonnet-4-6. kRouter's Cursor guide notes that this needs a Cursor Pro account. Why localhost fails, and the tunnel setup step by step: Cursor and a localhost base URL.

Anything else that speaks OpenAI: base URL http://localhost:20128/v1, a kRouter key, and a provider/model name.

Check that it works:

curl http://localhost:20128/v1/models

From the same machine this needs no key. It lists the models of the providers you connected, plus your combos. Open Usage in the dashboard to watch requests arrive.

Next steps