codex-multi-auth

codex-multi-auth is a multi-account OAuth manager for the official @openai/codex CLI. It keeps a named pool of ChatGPT sign-ins on your machine, lets you switch the active account, and — when you run Codex through its optional wrapper — rotates accounts across live requests through a loopback-only proxy. It never installs or shadows a codex binary; the official OpenAI install keeps owning that command.

Use it when one Codex account is not enough: you hit rate limits or quota windows, you split work across organizations and workspaces, you want per-project account pools, or you run unattended agents that need JSON diagnostics and safe repair commands instead of one opaque auth file.

Using OpenCode rather than the Codex CLI? The sibling project oc-codex-multi-auth is the plugin that manages the same kind of account pool there.

Refresh leases block uncoordinated OAuth refresh on lock errors or timeouts. For live re-login behavior and interrupted-refresh recovery, see the upgrade notes.

What it does

• Account pool — OAuth login for multiple ChatGPT accounts, stored locally under ~/.codex/multi-auth (files 0600, directories 0700), with per-project pools under projects/<project-key>/.
• Switching and selection — pin an account, pick the forecast-best one, follow saved account order within customized priority tiers with sequential scheduling, or let health- and quota-aware hybrid selection rotate for you.
• Runtime rotation — a default-on, loopback-only proxy that forwards Responses API, model-discovery, image, thread-goal, web search, Codex dictation/transcription, and native voice traffic through managed accounts during wrapper-launched Codex sessions.
• API regions — codex-multi-auth login --api supports Global and US endpoints per credential. Choose US (us.api.openai.com) for a US-regional project; existing credentials remain Global. Each credential stays on its chosen endpoint, and Responses failover remains within the first eligible credential’s region. Regional routes use store version 2, so older builds reject them rather than silently discard their region.
• PSP API pool — login --api offers Regular API, ZDR, and PSP (Private Safety Processing). ZDR approval and PSP project enrollment are operator-confirmed, never inferred from a key or successful discovery. Select api/<model>, zdr/<model>, or psp/<model> explicitly; failover stays within that pool and the selected region on HTTP and WebSocket connections. Global/US region selection remains separate. Choosing PSP does not enroll a project or modify provider privacy settings.
• API model metadata — login --api can attach operator-declared Daybreak Red access and reasoning efforts to a selected model when discovery omits them. These declarations enable matching routes without claiming probe verification. Reasoning declarations use store version 3, so older builds cannot silently strip them.
• API capability evidence — opted-in API/ZDR routes receive daily billable checks while the router runs; status distinguishes configured access programs from verified responses. See check behavior and controls.
• Diagnostics and repair — status, live health checks, quota forecasts, JSON reports, and fix/doctor/verify commands that recover stale or damaged local state.
• Luna Reserve fallback — treats gpt-reserve as a separately metered Luna allowance, automatically falls back after a genuine Luna quota 429, and exposes the Reserve percentage through limits --json --refresh.
• Local governance — file-backed usage ledger, budget guards, account tags/weights/pause/drain policies, routing profiles, and an optional loopback bridge with bearer tokens for local OpenAI-compatible clients.
• Desktop routing (optional) — a reversible bind of the packaged Codex app plus user-level launcher helpers; official app binaries are never patched.

The four binaries

Binary	Role
codex-multi-auth	The account manager. Runs all management subcommands locally (login, status, web, switch, forecast, rotation, fix, ...). The auth prefix is optional: codex-multi-auth login ≡ codex-multi-auth auth login.
codex-ma	Short alias for codex-multi-auth, including the local real-time web dashboard.
codex-multi-auth-codex	Opt-in wrapper. Handles auth ... locally and forwards every other command to the official Codex CLI, enabling the rotation proxy for request-bearing commands.
mcodex	Convenience launcher over the wrapper, with optional --monitor and --tmux modes. No account logic of its own.
codex-multi-auth-app-launcher	User-level OS launcher routing helper (Windows shortcut, macOS wrapper app, Linux .desktop).

Install

Requirements: Node.js >= 22.19, and the official Codex CLI on PATH (npm i -g @openai/codex, Homebrew, or a release binary).

npm i -g codex-multi-auth

Note

The legacy scoped prerelease @ndycode/codex-multi-auth is migration-only. Install codex-multi-auth for all new setups; see docs/upgrade.md to migrate.

Quick start (5 minutes)

# 1. Sign in a ChatGPT account (browser OAuth, loopback callback on localhost:1455)
codex-multi-auth login

# 2. Repeat login to add more accounts, then inspect the pool
codex-multi-auth status
codex-ma web --no-open

# 3. Probe account health and preview which account would serve next
codex-multi-auth check
codex-multi-auth forecast --live

Headless or remote shell? Use codex-multi-auth login --device-auth — no callback port needed. Blocked browser? See alternate login paths.

Run Codex through the wrapper so requests rotate across the pool:

codex-multi-auth-codex          # interactive TUI, rotation on by default
codex-multi-auth-codex exec "summarize this repo"
mcodex                          # same wrapper, shorter name

Command map

codex-multi-auth ships 31 subcommands. The full surface — every flag, hotkey, and JSON mode — is in docs/reference/commands.md.

Group	Commands	Purpose
Accounts	login, list, status, switch <i>, unpin, workspace	sign in, inspect the pool, pin or switch the active account, select or enable/disable workspaces
Selection	forecast, best, why-selected, check, limits, models	preview, explain, and probe which account serves the next request
Runtime	rotation status enable disable bind-app unbind-app reset-runtime reset-rate-limits	inspect and control live rotation and the app bind
Repair	fix, doctor, report, verify, verify-flagged, uninstall	diagnose and repair storage, flagged accounts, and install residue; machine-readable health report
Governance	usage, budget, account, monitor, history, resets	usage ledger, budget limits, tags/weights/pause/drain, snapshots
Local clients	bridge, integrations	bearer tokens and client snippets for the loopback bridge
Config	config explain template, init-config, debug bundle, features	effective-config report, config templates, sanitized debug bundle

Everyday examples:

codex-multi-auth switch 2                     # pin account #2
codex-multi-auth report --live --json         # full machine-readable health report
codex-multi-auth fix --live --model gpt-6.1-sol   # live repair probes with a chosen model
codex-multi-auth doctor --fix                 # diagnose and apply the safest fixes
codex-multi-auth usage --since 24h --by model # local usage ledger summary
codex-multi-auth rotation status              # is live rotation enabled?

Runtime rotation, in one paragraph

With rotation on (the default), request-bearing wrapper commands — exec, review, resume, fork, app, and the bare TUI — route through a local proxy that picks the healthiest account per request, refreshes tokens as needed, and fails over across the pool on rate limits within a bounded retry budget. The proxy listens on loopback only, authenticates its own clients with a per-process token, forwards only Responses API, model-discovery, image, thread-goal, POST /transcribe, POST /alpha/search (web search), and native voice calls (/live and /realtime/calls, plus the call's sideband WebSocket), and never writes account emails or tokens to client headers or logs. Transcription preserves the incoming multipart audio body and boundary, uses managed ChatGPT OAuth, and does not replay ambiguous audio uploads across accounts. Plain codex is never touched: rotation exists only inside codex-multi-auth-codex/mcodex sessions, or inside the packaged desktop app after an opt-in, reversible bind. Turn it off with codex-multi-auth rotation disable or CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0.

Quota cache revalidation

Local rate-limit blocks are valid for at most one hour. The next request then rechecks upstream, including for a hard-pinned account, so an out-of-band quota reset does not require a manual switch. A fresh upstream rejection starts a new bounded wait; this does not reset quota or spend reset credits.

Where state lives

What	Path
Accounts, settings, quota cache, usage ledger, policies, observability	~/.codex/multi-auth/
Per-project account pools	~/.codex/multi-auth/projects/<project-key>/
Official Codex state (kept by the official install)	~/.codex/
Override the multi-auth root	CODEX_MULTI_AUTH_DIR=<path>

Full path map: docs/reference/storage-paths.md.

Troubleshooting in 60 seconds

codex-multi-auth doctor --fix
codex-multi-auth check
codex-multi-auth forecast --live

Common symptoms — wrong active account, OAuth callback port 1455 already bound, Windows/WSL port contention, EBUSY/EPERM on Windows — are covered in docs/troubleshooting.md.

After signing in again, a running native or custom-provider router adopts the saved replacement credentials on the next authenticated request. Replacing rejected credentials clears their stale authentication block without restarting the router; account pins and independent quota limits still apply. Unchanged revoked credentials still require a new sign-in.

Documentation

Doc	What it covers
docs/index.md	Product overview — what it does at runtime and who needs it
docs/README.md	Full documentation portal and sitemap
docs/getting-started.md	Install, first login, day-1 commands
docs/features.md	Feature tour
docs/architecture.md	Components, request flow, trust boundaries
docs/configuration.md	Settings and environment overrides
docs/reference/commands.md	Every command, flag, and hotkey
docs/reference/public-api.md	Public API stability tiers and semver contract
docs/troubleshooting.md	Recovery playbooks
docs/faq.md	Common questions
docs/upgrade.md	Version and legacy-package migration
docs/privacy.md	Data handling and local storage behavior
config/README.md	Modern vs. legacy catalog templates
CHANGELOG.md	Release history (short version)

Release notes

• Current stable: v2.25.0 — npm i -g codex-multi-auth
• Earlier stable lines: v2.6.0, v2.5.0
• Full release archive: docs/README.md#release-history

Terms and license

codex-multi-auth uses OAuth account credentials and is intended for personal development use. It is an independent open-source project, not an official OpenAI product; you are responsible for your own usage and policy compliance, and for production or commercial workloads you should use the OpenAI Platform API. "ChatGPT", "Codex", and "OpenAI" are trademarks of OpenAI.

MIT license — see LICENSE.