Getting Started

This page covers how to download cc-router and wire it into Claude Code.

Prerequisites

  • Operating system: macOS, Windows, or Linux
  • Claude Code installed
  • At least one supported LLM provider account with an API key (e.g. Zhipu GLM, DeepSeek, Kimi, MiniMax, Alibaba Bailian — see the README for the full list)

Download & Install

Pick the package for your OS and architecture. Both download sources serve identical files; users in mainland China should pick China mirror for faster downloads. The links always point to the latest release — older versions are on the Releases page, and everything is also listed on the Download page.

macOS

ArchitecturePackageDownload
Apple Silicon (M-series)cc-router_macOS-arm64.dmgGlobal · China mirror
Intelcc-router_macOS-x64.dmgGlobal · China mirror

Not sure which one? Open the Apple menu → About This Mac: if it shows “Chip Apple M…”, pick Apple Silicon; if it shows “Processor … Intel …”, pick Intel.

Double-click the .dmg to mount it, then drag cc-router into Applications.

Windows

ArchitecturePackageDownload
x64cc-router_windows-x64-setup.exeGlobal · China mirror
x64 (MSI)cc-router_windows-x64.msiGlobal · China mirror
ARM64cc-router_windows-arm64-setup.exeGlobal · China mirror

For a personal PC, use setup.exe; use the .msi when you need to roll it out via Group Policy or a software distribution tool. Double-click the download to run the installer. For using it with Claude Desktop on Windows, see Claude Desktop on Windows.

Linux

ArchitecturePackageDownload
x64 · AppImagecc-router_linux-x64.AppImageGlobal · China mirror
x64 · debcc-router_linux-x64.debGlobal · China mirror
ARM64 · AppImagecc-router_linux-arm64.AppImageGlobal · China mirror
ARM64 · debcc-router_linux-arm64.debGlobal · China mirror
  • .AppImage (recommended, supports in-app auto-update): chmod +x cc-router_linux-*.AppImage && ./cc-router_linux-*.AppImage
  • .deb (Debian / Ubuntu): sudo apt install ./cc-router_linux-*.deb — upgrades require downloading and installing the new package manually

Configure Virtual Models

On first launch, cc-router walks you through an onboarding flow:

  1. Add a subscription — Pick a provider → pick an endpoint (subscription / pay-as-you-go API) → enter your API key. cc-router automatically fetches the available model list.
  2. Bind virtual models — Assign the fetched real models to the opus / sonnet / haiku virtual slots.
  3. Pick a scheduling mode — When multiple subscriptions sit on the same slot, choose Sequential (move to the next one only when the current one is exhausted or fails) or Round-robin (rotate between requests).

You can revisit and tweak providers or slot bindings any time from the Models page in the main UI.

Connect to Claude Code

After launch, cc-router runs a local proxy listening on 127.0.0.1:23456. Open cc-router’s Settings page, copy the full env snippet, and paste it into the env field of ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:23456",
    "ANTHROPIC_AUTH_TOKEN": "paste the real token shown in the app",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "ANTHROPIC_MODEL": "model-opus",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "model-sonnet",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "model-opus",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "model-haiku"
  }
}

model-opus, model-sonnet, and model-haiku are the virtual model names cc-router exposes to Claude Code — the app translates them to the real model names you configured behind the scenes.

If your model supports a 1M context window, you can write model-opus[1m] — this is the syntax Claude Code understands.

Port already in use

If the default port 23456 is taken, cc-router auto-increments to the next free port. Always copy the latest snippet from the Settings page so the port stays in sync.

Restart Claude Code after saving, and your requests will flow through cc-router to the real models you configured.

Next Steps

  • Open the Request logs in cc-router’s main UI to verify Claude Code’s requests are routed correctly
  • Need a provider that isn’t built in? See the “Adding a new provider” section in the README. If you use Claude Code, run the bundled new-provider skill to generate the provider config automatically.