CCR is a local gateway that fails over behind your back, and its image ships without npm

The quick start downloads v3.1.0 while the current version is 3.1.1

The recommended install path is a desktop app for macOS, Windows, or Linux, and the four download links all point at release assets under v3.1.0: an .exe for Windows, an .AppImage for Linux, a macOS disk image for Apple Silicon, and a separate macOS disk image for Intel. The package manifest meanwhile declares version 3.1.1, and 3.1.1 is the newest tagged release, dated 2026-09-16, ahead of 3.1.0 on 2026-09-10 and 3.0.22 on 2026-08-24. So a newcomer following the quick start gets a build one patch behind the current release, and there is no statement in the file explaining the lag. The two macOS assets are the other trap: they are separate per-chip downloads, so on an Intel machine the arm64 image will not run, and nothing in the download table tells you which one to pick beyond the filename.

services:
  ccr:
    build:
      context: .
      dockerfile: Dockerfile
    image: claude-code-router:local
    ports:
      # Publish only Nginx. Internal web/gateway listeners stay inside the container.
      - "3458:8080"
    volumes:
      - ccr-data:/data
    restart: unless-stopped

volumes:
  ccr-data:

Four of the ten agents are CLI only and three are apps only

The supported agent table is more specific than the headline list suggests, because each entry carries a form factor. Three are marked for both the CLI and the app: Claude Code, Codex, and OpenCode. Four are CLI only, namely Grok CLI, Kimi CLI, Kilo Code, and Pi. Three are app only, namely ZCode, Claude Design, and WorkBuddy. The headline sentence flattens all ten into one sentence about connecting them, which hides the distinction that matters when you are configuring. If your agent is a desktop app, three of the ten can reach CCR at all, and the other seven are irrelevant to you however well the routing works. If it is a terminal agent, seven are in scope. The practical effect is that switching agents does not mean swapping one client for another behind the same endpoint, because the form factor decides whether there is a configuration file to point at the local address in the first place.

The Compose file publishes one port and keeps the gateway inside

The container path publishes exactly one port. The service is named ccr, the image is built locally, and the single mapping is 3458 to 8080, with a comment stating the reasoning plainly: only Nginx is published, and the internal web and gateway listeners stay inside the container. The runtime stage confirms the split through environment variables. The gateway binds to 127.0.0.1 on port 3456 and the web interface binds to 127.0.0.1 on port 3459, while 8080 is the Nginx port and 3458 is the public port. So if you were expecting to point a client at the gateway port directly from the host, that address does not exist outside the container, and everything has to arrive through the published Nginx listener. Data survives restarts through a named volume called ccr-data mounted at the data directory, which is also the value of the data directory variable in the image.

FROM ${RUNTIME_NODE_IMAGE} AS runtime
ENV NODE_ENV=production \
    CCR_DATA_DIR=/data \
    CCR_WEB_HOST=127.0.0.1 \
    CCR_WEB_PORT=3459 \
    CCR_NGINX_PORT=8080 \
    CCR_GATEWAY_HOST=127.0.0.1 \
    CCR_GATEWAY_PORT=3456 \
    CCR_PUBLIC_HOST=127.0.0.1 \
    CCR_PUBLIC_PORT=3458

The runtime image deletes npm, npx, yarn, and corepack on purpose

The runtime stage is built to be unchangeable after the fact. It installs ca-certificates, the C++ runtime library, and nginx, removes the default nginx site and configuration, and then deletes a list of paths that includes the yarn directories, the corepack binary, the npm, npx, and yarn executables from the binary directory, the npm and corepack module directories, and the documentation, manual, and C header trees. The result is an image with a Node runtime and no way to add a package to it. That is a sound hardening decision, and it has a direct operational consequence: you cannot install a missing dependency into a running container, you cannot patch a vulnerable transitive dependency without rebuilding the image, and any extension you add to the running system has to be baked into a new image first. The base is the same slim Debian bookworm Node image used for the build, with the base image and runtime image both exposed as build arguments so you can move them independently.

A tarball in docker/local-ai-gateway changes the build without touching the lockfile

The build stage contains a conditional that is easy to miss. After copying the sources, it checks whether any tarballs exist under a directory named docker/local-ai-gateway, and if the glob matches, it installs those tarballs with the no-save flag before running the docker build script. No-save is the important part: the package is installed into the image, but nothing is written to the manifest, so a build performed on a machine that happens to have a tarball in that folder produces a different image from a clean checkout, and the difference is invisible in the lockfile. On a developer machine where such a file has been left behind, your image contains something nobody else's does. The dependency layer above it is otherwise careful, copying the four workspace manifests and running a clean install, then repeating it in the production dependency stage with dev dependencies omitted and scoped to a single workspace package, which is what keeps the runtime image small.

Two lockfiles sit at the root for two different package managers

The root of the repository holds both a package-lock.json and a pnpm-lock.yaml, alongside an .npmrc, which means two package managers have a claim on the same tree. The manifest itself is npm-shaped: it declares workspaces as packages with a wildcard, its main entry points into the built Electron output, and its scripts all run through npm run. The engine floor is Node 22 or newer, which is a hard constraint on your machine and on any container image you build, since the build arguments for both the build and runtime stages default to the Node 22 slim bookworm image. The four workspace packages named in the container build are cli, core, electron, and ui, and the production dependency stage installs only the core workspace, which tells you the other three have to be bundled during the build rather than resolved at runtime.

The sponsored block comes before the project name and its links carry affiliate tags

The first substantial content in the file is a sponsor panel, above the heading, thanking Kimi and describing K3 as Moonshot AI's most capable model and the first open 3T-class model, with 2.8 trillion parameters, native vision, and a 1 million token context window. Those are the sponsor's own figures and its own claim, placed where a reader sees them before anything about the project. The links carry an affiliate parameter: the code plan, the API platform, and both the Chinese and global variants all append a tracking tag to their addresses. The integration itself is described as a built-in provider preset where the subscription endpoint passes through natively without protocol conversion, API endpoints are adapted automatically, and balance and subscription usage appear in the dashboard. Useful, and worth reading with the placement in mind.

Retries, credential pools, and ordered fallbacks decide who answered

The reliability features are the ones with real consequences for how you reason about a session. The project lists retries, credential pools, key rotation, and ordered fallback models as the mechanisms that keep requests running, and separately promises observability through request logs, resolved routes, latency, token usage, cost estimates, and account status. Put together, those mean a request that fails on one key can be retried on another from the pool, and a request that fails on a model can be retried on the next model in the ordered list. The model that produced a given turn in a coding agent is therefore not necessarily the one at the top of your routing table, and the only place you find out is the log, after the fact. That is the right design for an agent that must not stall, and it is a bad fit for any workflow where you need to attribute a specific answer to a specific model.

Editorial conclusion

Claude Code Router is a reasonable pick if you run more than one coding agent against more than one model provider and are tired of editing each client's configuration separately. It is also a local proxy, and that is the trade: every request passes through a process you run, with retries, credential pools, and ordered fallback models deciding which key and which model actually answered a given turn, with the resolved route visible only afterwards in the logs. Before you depend on it, check whether your agent is a CLI, an app, or both, since four of the ten are one and three are the other, and expect the container to be immutable, because the runtime image has its package managers deleted.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes