Codex Router Installation Guide — macOS, Windows, Linux

This guide covers every way to install Codex Router on macOS, Windows and Linux, what each method does, how to choose between OAuth and API-key authentication, and how to verify, update and remove the integration. The Codex App is supported on macOS and Windows; the Codex CLI is supported on macOS, Windows and Linux.

Requirements

Before you start, make sure the following are installed from their official sources. The installer will not silently install a package manager or runtime for you.

• The Codex App or CLI.
• Node.js 22.19 or newer. Node.js 24 LTS is recommended.
• uv, or Python 3.10+ with venv.
• Git, for the managed one-command checkout and rollback.
• At least one Kimi OAuth, Kimi API, or DeepSeek API credential — though you can select a different provider during guided setup.

Choose your install path

There are three supported ways to install, and they all end with the same verified per-user background service:

• Guided terminal install — a numbered wizard that walks you through provider selection, credential onboarding and verification. Best for most people.
• AI-agent installation — paste one instruction into a Codex task and let an agent follow the repository’s AGENTS.md procedure. Best when you want a second pair of hands or a reproducible install.
• Clone-and-review install — clone the repository, inspect it, then run the installer from the checkout. Best if you prefer to review the code before running anything.

All three methods are described below. If you already know your provider, jump straight to the model guides.

Guided terminal install

macOS or Linux:

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

Windows PowerShell:

$installer = Join-Path $env:TEMP "codex-router-install.ps1"
Invoke-WebRequest https://raw.githubusercontent.com/duolahypercho/codex-router/main/install.ps1 -OutFile $installer
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $installer -Target codex -Guided

The guided wizard walks through numbered steps: a provider list you toggle by number (a selects all, n clears, Enter continues) with a live ready/needs-key/needs-sign-in status per provider, credential onboarding for anything you selected that is not connected yet, and a review summary before any change is made.

On macOS and Linux, guided setup also offers to build and launch the desktop companion (the macOS menu-bar app or the Windows/Linux tray). --with-tray installs it without asking, --no-tray never offers it, and automatic mode skips it.

Clone-and-review install

If you prefer to inspect the repository first:

git clone https://github.com/duolahypercho/codex-router.git
cd codex-router
./install.sh --target codex --guided

git clone https://github.com/duolahypercho/codex-router.git
Set-Location codex-router
./install.ps1 -Target codex -Guided

Authentication choices

Codex Router supports two authentication styles, and they are separate account and billing systems:

API keys are entered only through hidden terminal prompts (or the desktop tray’s replace/remove actions). Never paste a token or API key into chat, a command argument, shell history, or a tracked file.

For a detailed comparison, see OAuth vs API key in the FAQ, and the per-model pages (DeepSeek, Kimi, GLM, Grok, Claude).

Verify the install

model_catalog_json is loaded at Codex startup, so after setup you must fully quit the app, reopen it, and create a new task. Then check:

./bin/model-router codex doctor
./bin/model-router codex providers
codex debug models

The doctor reports OK for every healthy layer and gives a targeted fix for every FAIL. The intended provider must say both SHOW and ready.

Update, rollback, disable and uninstall

./bin/model-router codex update
./bin/model-router codex rollback
./bin/model-router codex disable
./bin/model-router codex enable
./bin/model-router codex uninstall

update requires a clean main checkout on the recognized GitHub origin and keeps the previous revision as a rollback ref. disable removes only the Codex integration and its current service. uninstall intentionally retains the checkout, logs, backups and provider credentials so a routine removal cannot destroy authentication or recovery data.

See installation on macOS, installation on Windows, and agent installation for platform-specific details, or the troubleshooting overview if something goes wrong.