codex-multi-auth Documentation

Overview

codex-multi-auth is a multi-account OAuth manager designed specifically for the official Codex CLI (@openai/codex). It provides a workflow for managing multiple accounts, switching between them, and performing health checks.

Key Features

• Multi-account OAuth Management: Use the codex-multi-auth ... workflow to manage multiple sessions.
• Account Switching: Explicitly switch between different Codex accounts.
• Health & Diagnostics: Built-in health checks, diagnostics, and recovery tooling.
• Runtime Rotation: A default-on runtime Responses rotation proxy for forwarded official @openai/codex CLI/app sessions.
• Account Visibility: Provides visible local account state and quota-aware forecasts.
• Scoped Accounts: Support for optional project-scoped account pools.

Target Audience

• Use this if: You are an individual developer using the Codex CLI who needs visible local account state, explicit switching, health checks, and live runtime rotation.
• Do NOT use this if: You are looking for a commercial multi-user service, a generic API user, or a team looking for a hosted authentication layer.

The codex-multi-auth project is a structured CLI tool for multi-account OAuth. Its architecture is divided into several core functional modules:

• lib/auth/: Handles OAuth, PKCE, and callback logic. It includes a refresh-guardian taxonomy and mechanisms for auth storage corruption recovery and refresh-queue race prevention.
• lib/accounts.ts & lib/accounts/: Manages per-account rate-limit tracking, health scoring, and account selection.
• lib/codex-manager/: Acts as the command dispatcher and settings hub.
• lib/codex-cli/: Manages CLI state, synchronization, and observability.
• lib/request/: Implements a 7-step fetch pipeline with structured failure policies, backoff, and burst cooldown.
• lib/storage/: Handles V1-to-V3 migrations, worktree resolution, and provides robust WAL (Write-Ahead Logging) and backups.
• lib/recovery/: Manages conversation state persistence with defensive measures against partial writes.
• lib/ui/: Provides CLI UI components including themes, ANSI handling, and selection menus.

Runtime rotation is enabled by default and operates locally via a loopback provider named codex-multi-auth-runtime-proxy. It routes official Codex Responses/model traffic through this proxy to enable per-request account rotation.

• Rotation Behavior: The proxy moves to another managed account upon encountering quota limits, auth refreshes, network issues, or server failures before streaming response bytes.
• Policy Enforcement: The evaluateRuntimePolicy gate applies pause/drain, budgets, routing profiles, and capability checks before selection.
• Manual Overrides:
  • To force a specific account for a single ephemeral session (fail-hard, does not touch the persisted switch pin), use the wrapper: codex-multi-auth-codex --account <index|email|id>.
• Desktop & App Integration:
  • codex-multi-auth rotation bind-app allows the packaged Codex app to use the local router without patching official files.
  • codex-multi-auth-app-launcher helps retarget user-level app shortcuts or creates a managed macOS wrapper app.
• Monitoring: Use codex-multi-auth rotation status to view setting state, app helper state, account waits, cooldowns, and proxy metadata.

The codex-multi-auth system is designed with several strict security constraints to protect user credentials and PII:

• Loopback Binding: The runtime rotation proxy, app router, and local bridge only bind to loopback hosts (127.0.0.1, localhost, or ::1). Non-loopback bases are rejected.
• Local Authentication: The runtime proxy uses a per-process client API key. The local bridge uses operator-managed bearer tokens stored as SHA-256 hashes.
• PII Protection: Proxy responses do not include account emails, auth tokens, or stale decoded content-encoding metadata.
• OAuth Isolation: OAuth callbacks bind to port 1455 on loopback. PKCE tokens are stored locally under the multi-auth root.
• Keychain Safety: The system never touches the system keychain. It only reconciles a top-level cli_auth_credentials_store assignment in ~/.codex/config.toml. Existing credentials saved by the official codex login are left unread once the store is pinned to "file".
• Ephemeral Pins: Using --account or setting CODEX_MULTI_AUTH_FORCE_ACCOUNT creates an ephemeral pin that does not mutate persisted settings and fails if the proxy is unavailable.

The codexRuntimeRotationProxy is a localhost-only Responses proxy that enables multi-account rotation for the official Codex CLI, codex app-server, and codex app launches.

When enabled, the codex-multi-auth-codex wrapper creates a temporary shadow CODEX_HOME/config.toml that uses a custom provider named codex-multi-auth-runtime-proxy. This allows the official Codex surface to run against the rotation provider without modifying your permanent configuration.

Key behaviors:

• Account Pinning: You can pin a single run to one account using codex-multi-auth-codex --account <selector> or the CODEX_MULTI_AUTH_FORCE_ACCOUNT environment variable. This pin is per-invocation and does not affect your persisted switch pin.
• Request Handling: The proxy preserves request bodies and streaming responses while replacing outbound auth headers with the selected managed account. It automatically rotates accounts upon encountering rate limits, server errors, network failures, or refresh failures.
• Anti-Abuse Mitigations:
  • Token-invalidation detection: If an OAuth revocation is detected, the proxy returns the error directly to the client and puts the account on a 5-minute cooldown (tokenInvalidationCooldownMs, default 300000).
  • Rotation-rate throttle: To prevent rapid switching, the proxy biases selection toward the last-served account for a configurable window (minRotationIntervalMs, default 60s).

# Enable the proxy via environment variable
export CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=1

# Pin a specific account for a single invocation
codex-multi-auth-codex --account <selector>

The project provides four global binaries. It is important to note that this package does not replace the official codex binary; it works alongside it.

Usage Tip: Use codex-multi-auth-codex ... or mcodex ... only when you intentionally want to use the package's forwarding wrapper for Codex sessions.

The codex-multi-auth project acts as a wrapper and management layer for the official Codex CLI. It provides multi-account OAuth management, automatic account rotation via a local proxy, and local governance (budgets, usage tracking, and policies).

Core Components

• Standalone CLI (codex-multi-auth): The primary entrypoint for managing accounts, settings, and dashboard actions.
• Convenience Launcher (mcodex): An optional cross-platform binary that forwards commands to the Codex wrapper, with optional monitoring and tmux support.
• Forwarding Wrapper (codex-multi-auth-codex): A local wrapper that discovers the official Codex binary and injects auth credentials or routes requests through the runtime rotation proxy.
• Runtime Rotation Proxy: A local loopback proxy (lib/runtime-rotation-proxy.ts) that intercepts requests to rotate accounts based on rate limits, failures, or policies (budget, tags, model allow/deny).
• Local Bridge: An optional OpenAI-compatible loopback server (lib/local-bridge.ts) that forwards requests to the runtime proxy.
• Governance & Policy: File-backed systems for managing usage ledgers, budgets, account policies (tags, weights), and routing profiles.

Terminal user
  | 
  | codex-multi-auth ...
  v
scripts/codex-multi-auth.js
  |- normalizes bare manager subcommands to auth subcommands
  |- handles account-manager subcommands through lib/codex-manager.ts
  |- runs first-run setup once (app bind / launcher self-heal)
  |- writes/reads ~/.codex/multi-auth/*
  |- syncs active account to official Codex CLI files