Last updated August 7, 2026

Install Codex Router on Windows (Codex App & CLI)

This page covers installing Codex Router on Windows for the Codex App or CLI, the PowerShell command wrapper, the WSL edge case where Codex Desktop and the shell live in different environments, and how to verify the per-user service.

Requirements on Windows

The Codex App or the Codex 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.

Guided install

Open PowerShell and run:

$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 wizard toggles providers by number, shows a live status per provider, and prompts invisibly for any API key you select. It installs a per-user background service through Task Scheduler and never makes a paid test request unless you opt in with the smoke test.

The codex-router.ps1 wrapper

After installation, all router commands go through the PowerShell wrapper:

./codex-router.ps1 codex doctor
./codex-router.ps1 codex providers
./codex-router.ps1 codex provider-key deepseek set
./codex-router.ps1 codex update
./codex-router.ps1 codex uninstall

API keys are entered through hidden prompts. Never put a credential in a chat, a command argument, shell history, or a tracked file.

WSL and the Codex Desktop configuration

When Codex Desktop runs on Windows while commands execute through WSL, there can be two different Codex home directories: C:\Users\<WindowsUser>\.codex and /home/<LinuxUser>/.codex. Router commands use the Codex home selected by CODEX_HOME, so running them inside WSL without overriding that variable may update the Linux CLI configuration instead of the one used by Windows Codex Desktop.

To target the Windows Desktop configuration from WSL:

export CODEX_HOME=/mnt/c/Users/<WindowsUser>/.codex
export CODEX_ROUTER_STATE_DIR="$CODEX_HOME/codex-router"

Also make sure the model_catalog_json path in the Windows config.toml is readable from WSL — use /mnt/c/Users/<WindowsUser>/.codex/codex-router/merged-models.json rather than a C:\... path. If setup appears successful but the Desktop picker does not change, check which Codex home was modified before rerunning setup.

Verify the install

Run ./codex-router.ps1 codex doctor and resolve any FAIL line.
Confirm the provider reports SHOW and ready.
Fully quit Codex (use the app’s Quit command, or end it from the tray if present), reopen it, and create a new task.
Open the model picker.

Check the scheduled task:

Get-ScheduledTask -TaskName "Codex Router"

If a layer is unhealthy, ./codex-router.ps1 codex doctor --fix rebuilds the managed config and service.

Windows-specific gotcha: Grok OAuth

Smart App Control can block the official Grok CLI on Windows, which prevents Grok OAuth from completing login or refreshing its session. If grok --version reports spawn UNKNOWN, “An Application Control policy has blocked this file,” or a Smart App Control notification, use the grok-api provider with an xAI API key instead. See Windows blocks the Grok OAuth CLI for details.

Uninstall

./codex-router.ps1 codex uninstall

Uninstall removes the active integration and service but retains the checkout, logs, backups and credentials by design. Inspect %LOCALAPPDATA%\codex-router and the state directory manually before deleting anything.