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 recommended installer now includes guided provider setup, the Electron Control Center, the tray/menu-bar app and the macOS desktop widget. The Codex App is supported on macOS and Windows; the Codex CLI is supported on all three platforms.

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.
• On Windows, Windows PowerShell must run in FullLanguage mode and local application-control policy must permit Add-Type; the installer checks this and does not weaken the policy.

Choose your install path

Choose the path that matches how much of the desktop experience you want:

• Recommended full install — guided provider setup plus the Control Center, tray/menu-bar app and macOS desktop widget. 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.
• Homebrew CLI-only install — installs the router and command line without building the desktop frontends.
• 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 four methods are described below. If you already know your provider, jump straight to the model guides.

Recommended full install

macOS or Linux:

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

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 -WithTray

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.

When it finishes, fully quit and reopen Codex, create a new task, choose a routed model, and open Codex Router for the Control Center. On macOS the app is available from Spotlight or ~/Applications; closing the window leaves its menu-bar host running. The desktop widget is included and can be enabled under Settings → Dynamic Island → Desktop. macOS has no public .dmg yet, so this command builds the app locally and requires the full Xcode app for its SwiftUI macro and WidgetKit targets.

Homebrew CLI-only install

Codex Router is not in homebrew/core yet. Add the upstream repository as a tap once, then install the formula:

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

Homebrew installs the router and CLI but deliberately omits the Electron Control Center, tray/menu-bar app and desktop widget. Use brew upgrade codex-router for updates. Before removing the formula, run codex-router uninstall, then brew uninstall codex-router.

Credential-free install and the browser panel

You can install the router idle — no provider selected, no credential prompts, nothing touched on your keychains, other CLIs’ sessions or Codex’s auth.json:

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

In this mode Codex traffic gets a local 503 router_idle_no_provider instead of provider or native forwarding, doctor reports the idle state at warn and exits 0, and a new stop subcommand completes the install → start → status → doctor → stop → uninstall loop. Re-running setup without the flags leaves idle mode.

Once installed, the browser panel opens with bin/panel (Windows: codex-router.ps1 panel). It is the same application as the tray — every command runs through the same table — and the URL is redacted in output because it carries the local caller capability.

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 the recognized GitHub origin and a checkout with no edits to tracked files — untracked files never block it, and --force (./bin/update --force, ./bin/rollback --force) discards tracked edits when you need it. It 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.