GPT Codex Router: Multi-Account Rotation and Failover for Codex Desktop

OpenAI Codex powers sophisticated developer workflows, from codebase reasoning to automated refactoring and test suite generation. The official Codex Desktop application and CLI integrate tightly with local filesystems to provide a powerful developer experience.

However, developers running sustained agent loops frequently hit a frustrating operational wall: ChatGPT subscription usage limits (Rate Limit / Quota).

When an agent is deep into a multi-step refactor or executing an extensive verification plan, a 429 usage_limit_reached error immediately stalls work until the quota reset window (often several hours later). Even if a developer has multiple paid ChatGPT subscriptions (such as a personal Plus plan and a company Team plan), Codex Desktop natively binds to only a single account at a time, requiring tedious manual sign-outs, browser re-authentications, and session disruptions.

The open-source project codex-account-pool (GPT Codex Router) solves this problem as a local-first Docker routing proxy.

Why This Exists

Previous attempts to handle multiple Codex accounts suffered from major drawbacks:

• Unofficial session extraction: Copying tokens from browser cookies is fragile, insecure, and fails when tokens expire.
• Binary patching: Modifying the Codex Desktop app or MSIX package risks breakage whenever official updates roll out.
• Manual intervention: Stopping in the middle of a task loses execution context and interrupts momentum.

GPT Codex Router works by leveraging Codex's native configuration points: chatgpt_base_url and openai_base_url. It leaves official app binaries completely untouched, acting strictly as a lightweight loopback proxy.

Architecture and Core Design

GPT Codex Router sits between your local tools and ChatGPT backend services:

준비

1. 1subgraph
2. 2CD
3. 3QC
4. 4end

반복 실행

1. 1GW
2. 2V1

실패 시 다시 실행 단계로 돌아갑니다.

정리

1. 1PROF
2. 2A1
3. 3A2
4. 4AN
5. 5CGW

1. Isolated Profiles via Official codex login

The router does not invent proprietary authentication mechanisms. It calls the official codex login CLI command, guiding you through standard browser authentication for each account.

Credentials remain isolated in platform-standard state paths:

• Windows: %APPDATA%\GPTCodexRouter\profiles\codex\<profile>\auth.json
• macOS: ~/Library/Application Support/GPTCodexRouter/profiles/codex/<profile>/auth.json

Isolated Profile Directory
%APPDATA% or ~/Library

profiles/codex/personal/auth.json

profiles/codex/work/auth.json

profiles/codex/backup/auth.json

Docker bind-mounts this state directory directly. Credentials are never written to the source code repository or packaged into container build layers.

2. Reactive Usage-Limit Failover

Account rotation operates strictly on confirmed upstream signals. During normal execution, all traffic routes through the active profile (e.g. account-1). If ChatGPT returns an explicit 429 usage_limit_reached:

1. The router suppresses the exhausted account until the reset timestamp indicated by ChatGPT.
2. It selects the next available registered account from the pool.
3. It replays the original failed request with the new account's credentials.

subgraph

Codex Agent Request

GPT Codex Router
(localhost:8317)

Active Account 1
(Injects auth.json Token)

OpenAI ChatGPT Upstream

429 usage_limit_reached

end

429 Quota Exhaustion Detected

Cooldown Account 1
(Suppressed until upstream reset)

Select Next Available Account 2

Replay Original In-flight Request

Standby Account 2
(Injects Fresh Token)

OpenAI ChatGPT Upstream

200 OK Streaming

Stream Clean Response to Codex
(Zero Disruption)

3. OpenAI-Compatible /v1 Endpoints

In addition to routing Codex backend traffic, the container exposes standard /v1 endpoints:

• /v1/responses
• /v1/chat/completions
• /v1/models

This enables third-party open-source coding tools (such as Qwen Code) and local scripts to use the same account pool and automated failover benefits.

4. Context Observability

The router maintains strict privacy: prompts, responses, source code, and tool outputs are never logged or stored. Instead, it emits structured JSONL telemetry tracking runtime metadata:

• Wire Size & Decoded Context Size: Monitors payload compression and real context expansion (including zstd decoding observers).
• Composition Ratios: Tracks tool outputs versus system instructions and reasoning bytes.
• Token Counters & Reuse Ratios: Measures structural context reuse across turns.

Quick Start

GPT Codex Router runs on Windows 10/11 and macOS 12+ with Docker Desktop. No host Go installation is required.

Prerequisites

• Windows 10/11 or macOS 12+
• Docker Desktop with Compose v2
• Official codex CLI in your system PATH

Step 1: Clone and Run Setup

On Windows:

Copy1git clone https://github.com/munlucky/codex-account-pool.git gpt-codex-router2cd gpt-codex-router3.\setup.cmd

On macOS:

Copy1git clone https://github.com/munlucky/codex-account-pool.git gpt-codex-router2cd gpt-codex-router3./setup.sh

Step 2: Interactive Browser Sign-in

The script launches the interactive codex login flow for each profile:

Copy1account-1 -> official codex login -> browser ChatGPT sign-in2          -> sign in to another account? y3account-2 -> official codex login -> browser ChatGPT sign-in4          -> sign in to another account? n5          -> Docker build + start + health check

Once sign-ins are complete, the script automatically:

• Registers local profiles
• Generates router /v1 client keys
• Builds and starts the Docker container
• Validates localhost:8317/healthz
• Backs up and configures ~/.codex/config.toml

Step 3: Restart Codex Desktop

Fully restart Codex Desktop to apply the configuration. All subsequent agent operations route through the local proxy with automatic failover enabled.

Common Operations

1. Listing Registered Profiles

Copy1docker compose exec gpt-codex-router gpt-codex-router auth list

2. Selecting a Specific Active Profile

Copy1docker compose exec gpt-codex-router gpt-codex-router auth use codex personal

3. Monitoring Live Logs

Copy1docker compose logs -f --tail=50 gpt-codex-router

4. Generating Context Observability Reports

Copy1docker compose exec gpt-codex-router gpt-codex-router report --since 3h --timezone Asia/Seoul

5. Stopping and Restoring Configuration

Copy1docker compose down

To restore your original Codex Desktop configuration, replace config.toml with the generated config.toml.gpt-codex-router.bak file.

Security Principles

• Loopback Binding Only: Listens strictly on 127.0.0.1:8317 on the host machine to prevent LAN or public network exposure.
• Header Sanitization: Inbound authorization and cookie headers are stripped before attaching authorized upstream credentials.
• No Quota Bypassing: The project does not crack, combine, or bypass provider limits. It merely switches between accounts authorized by the user.

Summary

GPT Codex Router eliminates the friction of subscription usage limits for developers working with Codex. By coupling official authentication with reactive failover and local Docker orchestration, it provides seamless continuity during long agent coding sessions.

Check out the repository on GitHub at github.com/munlucky/codex-account-pool to set up your own failover router.