ccNexus puts a local proxy between a coding CLI and the model you pay for

One local address, several upstream endpoints

ccNexus is described as an API gateway for Claude Code and the Codex CLI, and the first feature in the list is multi-endpoint rotation with automatic failover, where one endpoint failing moves the request to the next. The practical value of that is obvious once you have watched a coding session stop because a provider returned a 500, and the implementation detail that matters is how the endpoints are ordered and what happens when every one of them is exhausted. The second feature is API format conversion, with support for converting between the Claude format, the OpenAI chat format, the OpenAI responses format and the Gemini format, which is what lets one coding CLI talk to providers that do not speak its native protocol. The rest of the list is operational tooling: a model list endpoint at `/v1/models` with caching and on-demand refresh, filtering of endpoints by type, availability and enabled state, a clone action that copies an existing endpoint configuration so a similar one does not have to be typed out, and WebDAV synchronisation of configuration and data between devices. The storage for all of this is SQLite, through the pure Go driver in the dependency list, and the app itself is built with Wails v2, so the interface is a web view hosted by the Go process.

The model override rule is one line of configuration

Adding an endpoint is a dialog with three meaningful fields, the API address, the key, and the converter to use, and the choices for the converter are Claude, OpenAI Chat, OpenAI Responses and Gemini. The fourth field is the one that changes behaviour rather than just configuration. If the endpoint has a model set, that model overrides the model the client asked for, and if the endpoint has no model, the client's requested model passes through untouched. That single rule resolves a practical problem, because a proxy that sits between a client and a provider is the only place where the two can be forced to agree. A client configured for a Claude model can be pointed at an endpoint that only speaks a Gemini model, and the proxy substitutes it, and the same endpoint with no model configured serves whatever the client asked for. It is also a place where mistakes hide, since a model that is silently overridden is a model the user did not ask for, and the log is where you find out.

The token pool rotates, refreshes and isolates

The Codex token pool is the feature that distinguishes this from a simple reverse proxy, and it works on account tokens rather than on API keys. You import a batch of token JSON files, each with an `access_token` and a `refresh_token`, and the system takes over the lifecycle. It rotates between them, it refreshes when it receives a 401, and it keeps a state per credential, with the documented states being active, expiring, need refresh and invalid. That last part is the useful design decision, because a token pool where one dead credential takes down the pool is not a pool, and quarantining the invalid ones is what keeps the remaining ones serving. The pool also has its own statistics, counting requests, errors and tokens per credential, with a quick view, and the wider statistics are described as event driven with zero delay updates, with quick switching between today, yesterday, this week and this month. One caveat belongs in any honest reading: pooling subscription tokens across requests and users is a practice that provider terms may not permit, and the tool is neutral about it while the decision is yours.

Pointing the coding CLIs at the proxy

The configuration for the Codex CLI is a provider block in `~/.codex/config.toml`, and it is short:

model_provider = "ccNexus"
model = "gpt-5-codex"
preferred_auth_method = "apikey"

[model_providers.ccNexus]
name = "ccNexus"
base_url = "http://localhost:3000/v1"
wire_api = "responses"  # or "chat"

The `wire_api` line is where the conversion is chosen from the client side, either the responses protocol or the chat protocol, and the base URL points at the proxy on its default port. The documentation notes that `~/.codex/auth.json` can be ignored in this arrangement. For Claude Code the equivalent is the `env` block in `~/.claude/settings.json`, with `ANTHROPIC_BASE_URL` pointing at the same local proxy and `ANTHROPIC_AUTH_TOKEN` set to an arbitrary value, since the real credential is held by the gateway, plus a `CLAUDE_CODE_MAX_OUTPUT_TOKENS` value of 64000 with a note that some models do not support that ceiling. The result is that the coding CLI holds no meaningful secret at all, which is the cleanest argument for running a gateway in front of them.

A desktop app and a headless service from the same code

The project ships in two shapes. The desktop build is a Wails application, so the Go binary hosts a web view on the platforms Wails supports, which the documentation lists as Windows, macOS and Linux, and the dependencies show what that costs: a system tray library, a desktop notification library, a toast library for macOS, an icon encoder for the application icon, and the Windows-specific winloader package and the dbus bindings behind Linux notifications. The second shape is a headless mode, a pure backend HTTP service, which the documentation also offers as a containerised run with its own Docker page. The application is a single executable with a graphical front end when you want one and a service when you do not, and the CLI flags and environment variables are how you choose, since the port is settable with a `-port` flag or with the `CCNEXUS_PORT` environment variable, and the default is 3000. The headless mode also supports server side authentication with Basic Auth, and the behaviour on first start is worth knowing, because if Basic Auth is enabled and no password has been set, the application generates a random one and prints it to the log.

The operational notes are the security notes

Four notes in the running section carry most of the operational weight. The first is the port, 3000 by default, overridable by flag or environment variable, which matters because a proxy that listens on the loopback interface is a different proposition from one that listens on every interface. The second is the Basic Auth behaviour described above, where the credential is written to a log file on first start, which is a place to look before you paste a log into an issue tracker. The third is the model list, where `/v1/models` is served from a cache by default and can be forced to refresh, so a client that enumerates models may see a stale list until you ask for a refresh. The fourth is the warning about headless mode, which says it should be used only on a trusted internal network, or placed behind a reverse proxy that adds TLS and access control. That is the correct advice and it is worth taking literally, because a gateway holds every API key and every pooled token you have configured, and the local network is often not as trusted as the person running the gateway assumes.

Documentation, licence and the state of the project

The repository is compact, with a `cmd/` directory for the entry points, an `internal/` directory for the implementation, a `docs/` directory with a configuration guide, a development guide, a frequently asked questions page, a Docker page and an English readme, and a `CLAUDE.md` at the root for coding agents working on the tree. The module is `github.com/lich0821/ccNexus`, built with Go 1.24 and the 1.24.3 toolchain, and the dependencies describe the feature list rather precisely, since the WebDAV client accounts for the synchronisation feature, the SQLite driver for the local store, the systray and notification libraries for the desktop build, and the WebSocket and HTTP server packages for the gateway side. The licence is MIT. On versions, the releases are v5.3.0 on 2026-06-01, with v5.2.0 and v5.1.0 both on 2026-03-11, and the last push to the repository was on 2026-10-20, so the major version moves quickly, which is worth keeping in mind before you pin a version in a workflow that runs unattended.

Editorial conclusion

ccNexus suits a developer who wants one stable local address in front of several model endpoints, so that a failing provider is a switch rather than an outage, and who wants to use the same coding CLI against providers that speak different request formats. It is a poor fit if you want a hosted service, since it is a program that runs on your own machine or your own server, and it is a poor fit if you are not prepared to think about where API keys and account tokens are stored, since the tool holds both and the documentation is explicit that headless mode should sit behind TLS on a trusted network. Before you deploy it, check three things: how the endpoints are ordered and what happens when all of them fail, since the failover logic is the core of the product, whether the headless server is reachable from anywhere but your own network, since Basic Auth is the only barrier the documentation mentions, and the version you pin, with v5.3.0 published on 2026-06-01 and the last push to the repository on 2026-10-20.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. lich0821/ccNexus on GitHub
4. README
5. Releases