RouteKit

One gateway for your coding subscriptions and model providers.

RouteKit is an open-source CLI and authenticated model gateway for coding agents. Pool Codex and Claude Code subscriptions with API providers, then pin an exact route or let eval-driven model: "auto" routing choose for each request.

• Pick or route automatically. Pin one exact provider/model, or send auto to choose from the policy-filtered catalog with your published eval evidence and configured routing objective.
• Pool subscription accounts. Route across eligible Codex or Claude Code accounts of the same kind.
• Connect API providers. Use OpenAI, Anthropic, OpenRouter, Amazon Bedrock, and other configured routes behind one stable gateway.
• See what happened. Inspect model, provider, account, usage, and cost attribution for individual calls.

Documentation · Installation · User guide · CLI reference · Security

_{Watch RouteKit switch models and route a Codex session through the gateway.}

Why RouteKit

Coding agents increasingly support multiple model backends, but each tool has its own configuration, model names, credentials, and account state. Switching tools or providers often means rebuilding that setup.

RouteKit puts one local control plane and authenticated gateway in the middle:

• configure providers and subscription accounts once;
• discover a policy-filtered catalog of canonical, namespaced model IDs;
• pin a route or use eval-driven automatic model routing;
• launch Codex or Claude Code against the same gateway;
• point OpenAI-, Responses-, or Anthropic-compatible clients at the same gateway; and
• inspect which provider and account handled a request.

Quickstart

RouteKit supports macOS and Linux. If Node.js 22 or newer is installed:

npm install -g @velum-labs/routekit
routekit setup
routekit status

routekit setup walks through the routes you want to connect, validates API providers, enrolls selected subscriptions, starts the daemon, and asks you to choose a default model. API keys stay in environment variables; RouteKit does not prompt for or store them.

Launch your preferred coding tool from any project:

cd ~/code/my-project

routekit codex
routekit claude

RouteKit opens the native coding tool in the current directory and connects it to the gateway. The session starts with a suitable model, and the compatible RouteKit catalog is available in the tool's native model picker. Switch models inside the tool instead of restarting it or copying an ID for every launch.

To force the startup model for one session:

routekit codex openai/gpt-5.5
routekit claude claude-code/claude-sonnet-4-6

Use routekit models list when you want to inspect the catalog, troubleshoot a route, or copy an exact model ID for a deterministic command.

Headless setup is available with routekit setup --no-browser. For deterministic or automated configuration, see the installation guide.

Choose a model

RouteKit has two request-time selection modes:

• Pin an exact route. Use a canonical provider/model from routekit models list. The gateway either serves that advertised route or rejects it; it does not rewrite an explicit ID to another model.
• Route automatically. Send auto after publishing an eval-driven routing activation. RouteKit classifies the request against the activation's workload dimensions, excludes models that fail request requirements or configured constraints, and ranks the remaining policy-filtered candidates using the activation's objective and model-by-dimension eval evidence.

The published activation carries its routing objective: highest-quality, lowest-cost, lowest-latency, balanced, or pareto. The compositionalRouting config sets the online objective and constraints used while building and running that policy. modelPolicy controls which discovered models can enter the catalog, while defaultModel handles clients that omit the model. modelAliases are exact short names for one canonical target; they do not create fallback or automatic routing. Only auto invokes the implicit eval-driven router.

From Codex or Claude Code, pass auto as the optional model argument:

routekit codex auto
routekit claude auto

Omit the argument to use defaultModel or the launcher's compatible startup selection instead. Pass an exact ID to pin it:

routekit codex openai/gpt-5.5

HTTP clients use the normal request model field on the OpenAI Chat Completions, OpenAI Responses, or Anthropic Messages endpoint:

{
  "model": "auto",
  "messages": [{ "role": "user", "content": "Fix the flaky concurrency test." }]
}

What you can connect

Subscription accounts

Enroll one or more accounts from either supported subscription kind:

routekit config init --empty
routekit accounts login codex --name personal
routekit accounts login codex --name work
routekit accounts login claude-code --name team

routekit accounts status
routekit usage

RouteKit discovers model eligibility and selects an available account from the matching pool.

API providers

The guided setup supports OpenAI, Anthropic, OpenRouter, and Amazon Bedrock. For automation, initialize a provider directly:

export ANTHROPIC_API_KEY='your-key'
routekit config init --provider anthropic
routekit providers status
routekit models list --provider anthropic

Coding tools

From a project directory, launch Codex or Claude Code and choose among compatible RouteKit models from the native picker:

routekit codex
routekit claude

Pass an exact provider/model only when you need to control the startup model for a one-off comparison, script, or reproducible run.

Or install persistent, additive RouteKit configuration into the native clients:

routekit codex install
routekit claude install

The installers preserve existing client configuration, MCPs, skills, plugins, and native history. Check the client compatibility matrix for currently qualified versions.

HTTP clients

RouteKit exposes authenticated OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages endpoints. It also publishes a live model catalog.

ROUTEKIT_URL='http://127.0.0.1:8080'
ROUTEKIT_TOKEN="$(routekit daemon auth show)"

curl -sS "$ROUTEKIT_URL/v1/models" \
  -H "Authorization: Bearer $ROUTEKIT_TOKEN"

routekit daemon auth show prints the private owner token. Do not paste it into logs or source control. Issue a named data-plane token for another user or application:

routekit token issue <label>

See the HTTP gateway walkthrough for request examples.

How it works

flowchart LR
    subgraph Clients["Coding tools and HTTP clients"]
        Codex["Codex"]
        Claude["Claude Code"]
        HTTP["OpenAI / Responses / Anthropic clients"]
    end

    subgraph RouteKit["RouteKit"]
        CLI["CLI"]
        Daemon["Singleton daemon"]
        Gateway["Authenticated model gateway"]
        Router["Exact or eval-driven auto router"]
        CLI --> Daemon
        Daemon --> Gateway --> Router
    end

    subgraph Routes["Configured routes"]
        CodexPool["Codex subscription pool"]
        ClaudePool["Claude Code subscription pool"]
        APIs["API providers"]
    end

    Codex --> Gateway
    Claude --> Gateway
    HTTP --> Gateway
    Router --> CodexPool
    Router --> ClaudePool
    Router --> APIs

One singleton daemon per ROUTEKIT_HOME owns provider discovery, subscription pools, usage, call attribution, and the canonical router configuration. The gateway listens on 127.0.0.1:8080 by default, while the CLI manages it through a separate local control plane.

The canonical configuration is:

~/.config/routekit/router.yaml

Inspect a routed call

Model responses include an x-routekit-model-call-id header. Use it to inspect the route that handled the request:

routekit calls inspect <call-id>

The inspection reports the effective and provider-native model, provider, billing mode, retries, usage, cost when known, and account attribution without storing prompt or response text. For an auto request, it also shows the selected model, evidence digest, dimension weights, unknown weight, and classifier call ID when available.

Common commands

Documentation

• Installation
• Complete user guide
• Subscription pooling
• Client compatibility
• Model catalog
• Configuration
• Privacy
• CLI commands
• Agent-readable guide

Develop from source

RouteKit is a TypeScript pnpm/Turborepo monorepo. It requires Node.js 22.22.0 or newer and uses pnpm 11.15.1 through Corepack.

corepack pnpm install --frozen-lockfile
corepack pnpm check
corepack pnpm build
corepack pnpm test

Useful focused commands:

corepack pnpm build:cli
corepack pnpm dev:link-routekit
corepack pnpm docs:dev
corepack pnpm docs:build
corepack pnpm verify

corepack pnpm dev:link-routekit installs a separate routekit-dev command that rebuilds and runs this checkout without replacing the published routekit binary. The wrapper also keeps the repository-pinned pnpm version on the complete Turbo build process path.

Repository map

• packages/cli — published CLI and routekit executable
• packages/daemon — singleton daemon and lifecycle
• packages/gateway — authenticated model gateway and protocol adapters
• packages/accounts — subscription enrollment, eligibility, and account state
• packages/tool-* — coding-tool integration boundaries
• apps/docs — public documentation website
• docs — maintainer documentation and qualification evidence

Security

Report vulnerabilities privately through GitHub Security Advisories. Do not open public issues containing vulnerabilities, credentials, or tokens.

See SECURITY.md for details.

License

RouteKit is licensed under the Apache License 2.0.