Codex Router: running external models inside the Codex App and CLI

The gap Codex Router fills for people who already live in Codex

Codex ships with its own model picker. If you want a Kimi or DeepSeek model in that picker, there is no supported path in the base tool, and the usual workaround is a separate client with its own login. Codex Router takes the other approach: it runs a local service on your machine and registers routed models so they appear as choices inside the Codex App and CLI, with provider credentials staying on your computer.

The audience is narrow and specific. This is for an individual developer who already uses Codex as their main agent surface, wants to try an external provider without abandoning their existing Codex models, profiles, settings and ChatGPT login, and is willing to run a background service to get that. The README is explicit that the project is an independent community effort and is not affiliated with or endorsed by OpenAI, GitHub, Anthropic, Moonshot AI, DeepSeek, OpenRouter, opencode, Google, or the referenced opencodex project. That disclaimer matters more than usual here, because the whole product depends on other vendors' authentication flows.

How the routing actually works, and where the credentials sit

The router is a local process that Codex talks to, and it fans requests out to whichever provider you selected during setup. The repository is JavaScript with a small dependency set: package.json lists only proper-lockfile and undici at runtime, plus playwright as a dev dependency. Node.js >=22.19.0 is the declared engine. That is a deliberately thin footprint for something that sits between an editor and several model APIs.

The part worth reading closely is the subscription agent bridge section, which the README labels experimental. Three optional client-owned sessions are detected: Claude Code, Cursor Agent and Gemini CLI. They are kept separate from the codex_router/... model catalog rather than being folded into it. Claude runs through the installed official claude process and its existing Claude.ai login. Cursor Agent runs through its official ACP stdio server via agent acp, and Gemini CLI through gemini --acp. The router states that it never reads or copies those clients' OAuth tokens. It stores only bounded metadata for bridge sessions: client, session ID, workspace path and timestamps. Prompts and transcripts stay out of the bridge index.

There are two constraints in that design that a reader should not skim past. File-system and terminal capabilities are not advertised yet, and permission requests are rejected by default until the Control Center has a foreground approval surface. So the bridge is useful for asking a question and getting an answer, and not yet useful for agentic work that needs to touch your files. The README also draws a boundary against a different class of tool: this is not an OpenAI-compatible subscription proxy, it does not implement CLIProxyAPI's token-to-model-endpoint behavior, and it does not add fake Claude, Cursor or Gemini subscription models to another client's picker. On Gemini specifically, the README says direct reuse of Gemini CLI OAuth tokens in third-party software is not implemented, because Google's published Gemini CLI terms prohibit that access pattern.

Installing Codex Router and running a first routed prompt

The recommended install is a single piped script. On macOS or Linux the README gives this command, which sets the target to codex, runs the guided provider selection and installs the tray app:

curl -fsSL https://raw.githubusercontent.com/duolahypercho/codex-router/main/install.sh \
  | sh -s -- --target codex --guided --with-tray

The guided step asks which providers you want and keeps credential entry in private local prompts. When it finishes, the README says to fully quit and reopen Codex, start a new task, and choose a routed model. On Windows the equivalent is a PowerShell script downloaded to a temp path and run with -Target codex -Guided -WithTray.

If you only want the router and CLI, Homebrew is the lighter route. The project is not in homebrew/core yet, so brew install codex-router by itself does not work. Add the tap once, then install and run setup:

brew tap duolahypercho/codex-router https://github.com/duolahypercho/codex-router
brew install codex-router
codex-router setup --guided

Homebrew installs the formula's Node.js, Python and build dependencies. It deliberately does not build or download the Electron Control Center, the tray app or the macOS desktop widget. Upgrade later with brew upgrade codex-router.

Before spending any model quota, you can inspect the optional bridges. These commands, taken from the README, do not issue a model request:

./bin/model-router codex agents status
./bin/model-router codex agents probe anthropic
./bin/model-router codex agents probe cursor
./bin/model-router codex agents probe gemini

When you do intend to spend the owning client's quota, prompt text is read from stdin so it stays out of the process list:

printf '%s' 'Explain this repository.' |
  ./bin/model-router codex agents prompt anthropic --cwd "$PWD"

A Homebrew install puts a single codex-router command on your PATH instead of the repository's bin/ directory, so the README notes that ./bin/model-router codex <command> forms need adjusting for that install type.

The macOS build is the sharpest edge in the setup

There is no public .dmg. The recommended command builds and installs the macOS app locally, and that build requires the full Xcode app rather than the standalone Command Line Tools, because it contains SwiftUI macro and WidgetKit targets. The installer honors DEVELOPER_DIR or the Xcode selected under Xcode → Settings → Locations → Command Line Tools. If that selection still points at the standalone tools, it uses /Applications/Xcode.app or /Applications/Xcode-beta.app for this build only, without changing your global selection.

If Xcode lives somewhere else, the README gives a retry that points the companion at a specific developer directory:

env DEVELOPER_DIR="/path/to/Xcode.app/Contents/Developer" \
  ~/.local/share/codex-router/bin/model-router-tray

This is a real cost, not a footnote. A developer on a Mac who has never installed full Xcode is looking at a multi-gigabyte download before the tray icon appears. The Homebrew path avoids all of it by not shipping the GUI at all, which is the right trade for a server or a headless Linux box. The desktop widget has its own quirk: it is enabled from the menu-bar app under Settings → Dynamic Island → Desktop, and it is a movable Codex Router panel rather than an entry in macOS's Edit Widgets gallery. Anyone expecting to find it in the standard widget picker will conclude the install failed.

When Codex Router is the wrong tool

The clearest failure mode is a team that wants one shared endpoint. This routes on your machine, with credentials on your machine, and the setup is interactive and guided by design. There is no documented server mode for multiple users, and the README's emphasis on private local prompts and on never pasting a token into chat is the opposite of a shared-gateway posture.

The second case is agentic work over the subscription bridges. Because file-system and terminal capabilities are not advertised and permission requests are rejected by default, a workflow that expects Claude Code or Cursor Agent to edit files through the router will not get there yet. The README states the approval surface does not exist in the Control Center, so this is a known gap rather than a misconfiguration.

The third case is entitlement. The README notes that a successful claude auth status proves login only, and that the account must separately be entitled to use non-interactive or SDK turns. The bridge reports Anthropic's refusal verbatim when it is not. A user whose plan does not cover that will see a refusal, and no amount of router configuration changes it. Similarly, anyone hoping this replaces a subscription proxy for another client is reading against the README's explicit statement that it does not do that.

How it differs from a generic OpenAI-compatible proxy

The obvious alternative is an OpenAI-compatible proxy such as LiteLLM, which the repository lists as a topic. The difference is where the work happens. A generic proxy presents one OpenAI-shaped endpoint and expects clients to be pointed at it; the value is uniformity, and the client is usually unaware of which upstream served the request. Codex Router goes the other way. It integrates with one client, Codex, and makes external models appear as first-class entries in that client's own picker, alongside the models you already had. It also treats the subscription bridges as a separate, explicitly non-proxy category, with its own status and probe commands and a rule against copying OAuth tokens.

That choice buys tighter integration and costs portability. A LiteLLM-style proxy can serve any OpenAI-compatible client you point at it. Codex Router's catalog is built for Codex, and while the README says one local installation can also serve DeepSeek Harness, Gemini CLI, Cursor Agent and Cursor App, Claude Code and OpenClaw, that is a list of supported surfaces rather than a general-purpose endpoint. If your requirement is one URL that everything in your stack can call, the generic proxy is the better fit. If your requirement is a routed model in the Codex picker without disturbing your existing Codex setup, this is the narrower and more direct answer.

Licence, maintenance and what an upgrade costs

The project is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are retained. The repository also carries a NOTICE.md and a SECURITY.md at the top level, so attribution obligations may extend beyond the LICENSE file itself; read both before redistributing a modified build. Nothing here is legal advice, and the practical question for most users is simpler: if you fork and ship the Electron app, keep the notices intact.

Maintenance signals are current. The last push to main was on 2026-09-17, and v0.6.0 was released on 2026-09-15, following v0.5.1 on 2026-08-28 and v0.5.0 on 2026-08-26. The release cadence over that window is roughly weekly to fortnightly, and the repository is not archived. The declared engine floor of Node.js >=22.19.0 is the constraint most likely to bite on an older machine, and it is checked at install time rather than at runtime.

Upgrade cost splits by install method. Homebrew users run brew upgrade codex-router and get the router and CLI without rebuilding any GUI. Users of the recommended installer are rebuilding the macOS app, which means the Xcode requirement applies again on every upgrade that touches the SwiftUI or WidgetKit targets. The README's agent prompt asks an agent to preserve existing Codex models, profiles, settings and ChatGPT login, to safely migrate only recognized older versions, and to run the Codex doctor. The phrase "recognized older versions" is doing a lot of work there: the README does not document rollback or what happens when your installed version falls outside that recognized set, so back up your Codex configuration before running setup on a machine you care about.

Editorial conclusion

Adopt it if you already use Codex daily and want Kimi, DeepSeek or Anthropic models selectable in the same picker without moving credentials off your machine. Do not adopt it if you need a stable drop-in proxy for a team, because the subscription agent bridges are marked experimental, permission requests are rejected by default, and the macOS app is built locally rather than shipped as a .dmg. Before installing, check that Node.js meets the >=22.19.0 engine requirement in package.json and that Xcode is the full app if you want the tray and desktop widget.

Frequently asked questions

Official sources

1. duolahypercho/codex-router on GitHub
2. Issues
3. License: MIT
4. README
5. Releases