Codex App Account Router

Standalone local account router for using your authorized ChatGPT accounts with the Codex app.

This tool is intended for personal or team accounts you are allowed to use. It keeps OAuth tokens on your machine and routes Codex app requests through a local OpenAI-compatible endpoint.

This is an unofficial local integration that talks to ChatGPT/Codex web endpoints with your own OAuth session. Review your account terms and only use accounts you control or are explicitly allowed to use.

Easiest install

Install globally, then run setup:

npm install -g codex-app-account-router
cma setup

The short alias is what you use day to day:

cma setup

If another global package already owns cma, use codex-ma instead; both commands point to the same CLI.

That command will:

1. open the standalone ChatGPT OAuth login flow
2. write accounts to ~/.codex/multi-auth/openai-accounts.json
3. patch ~/.codex/config.toml for the router provider
4. install a startup service for your OS
5. print account status

Avoid one-shot npx ... setup for persistent startup services. npx runs from a temporary cache path, which is not a good target for LaunchAgent/systemd/Scheduled Task startup.

For the latest unreleased version from GitHub, install without manually cloning:

npm install -g github:mohammednuruddin/codex-app-account-router
cma setup

Manual/local setup

1. Install and log in accounts:

   npm run login

2. Confirm accounts exist at ~/.codex/multi-auth/openai-accounts.json:

   npm run status

Login is standalone: it opens the OpenAI OAuth browser flow, handles the local callback, and writes directly to Codex-owned storage under ~/.codex/multi-auth/.

Run

npm install
npm run build
npm start

The proxy listens on http://127.0.0.1:8787/v1 by default.

Keep this process running while Codex is open. In another terminal, verify it with:

curl http://127.0.0.1:8787/health

If Codex says stream disconnected before completion, first check that this health endpoint responds.

Commands

If installed globally, use the short alias cma:

| Command | Purpose | | --- | --- | | cma setup | Full install/login/configure/startup flow | | cma login | Add or refresh one ChatGPT account | | cma configure | Patch ~/.codex/config.toml only | | cma sync-accounts | Optional migration: copy existing OpenCode multi-auth accounts into Codex-owned storage | | cma start | Start the proxy in the current terminal | | cma status | Show safe account metadata without tokens | | cma doctor | Diagnose config, accounts, startup service, and proxy health | | cma accounts | List saved accounts | | cma remove <target> | Remove one account by index, email, account id, or user id | | cma logout | Remove all saved accounts | | cma install-startup | Install/start startup service for macOS, Linux, or Windows | | cma uninstall-startup | Stop/remove startup service | | cma smoke | Run the local end-to-end proxy smoke test |

Long aliases also work: codex-ma, codex-app-account-router, and codex-app-multi-accounts.

From a local checkout, use npm scripts:

cd codex-app-account-router

| Command | Purpose | | --- | --- | | npm run setup | Full install/login/configure/startup flow | | npm run login | Standalone browser login/add-account flow; writes directly into ~/.codex/multi-auth/ | | npm run configure-codex | Patch ~/.codex/config.toml for the proxy provider | | npm run sync-accounts | Optional migration: copy existing OpenCode multi-auth accounts into Codex-owned storage | | npm run status | Show safe account metadata without printing tokens | | npm start | Start the proxy in the current terminal | | npm run doctor | Diagnose config, accounts, startup service, and proxy health | | npm run accounts | List saved accounts | | npm run remove-account -- <target> | Remove one saved account | | npm run logout | Remove all saved accounts | | npm run install-startup | Install and start startup service for this OS | | npm run uninstall-startup | Stop/remove startup service | | npm run smoke | Run local end-to-end proxy smoke test | | npm run smoke:publish | Pack the npm artifact, install it into a temporary global prefix, and verify the public CLI bins and key commands | | npm test | Run unit/integration tests | | npm run typecheck | Run TypeScript typecheck |

Common flow:

cma setup
./scripts/check-proxy.sh

Start on login

Install the startup service:

npm run install-startup

Check it:

curl http://127.0.0.1:8787/health

Logs live at:

macOS: ~/Library/Logs/codex-app-account-router/
Linux: journalctl --user -u codex-app-account-router.service
Windows: Task Scheduler task CodexAppAccountRouter

Remove startup service:

npm run uninstall-startup

Codex config

Prefer a custom provider so Codex uses the Responses wire API and does not try WebSocket transport.

Default localhost-only proxy:

model = "gpt-5.5"
model_provider = "multi-auth-proxy"

[model_providers.multi-auth-proxy]
name = "Codex App Account Router"
base_url = "http://127.0.0.1:8787/v1"
wire_api = "responses"
supports_websockets = false

Authenticated proxy:

model = "gpt-5.5"
model_provider = "multi-auth-proxy"

[model_providers.multi-auth-proxy]
name = "Codex App Account Router"
base_url = "http://127.0.0.1:8787/v1"
wire_api = "responses"
supports_websockets = false
env_key = "CODEX_PROXY_TOKEN"

If you set env_key = "CODEX_PROXY_TOKEN" in Codex, set the same variable when starting the proxy. If you leave proxy auth unset, omit env_key from Codex config. Binding to a non-loopback host requires CODEX_PROXY_TOKEN.

Do not set requires_openai_auth = true for this custom provider. The router handles ChatGPT OAuth upstream; Codex only needs to talk to the local endpoint.

Environment

| Variable | Default | Purpose | | --- | --- | --- | | CODEX_PROXY_HOST | 127.0.0.1 | Listen host | | CODEX_PROXY_PORT | 8787 | Listen port | | CODEX_PROXY_ACCOUNTS_FILE | ~/.codex/multi-auth/openai-accounts.json | Multi-auth account pool | | CODEX_PROXY_BINDINGS_FILE | ~/.codex/multi-auth/session-bindings.json | prompt_cache_key to account binding | | CODEX_PROXY_UPSTREAM_MODELS_URL | https://chatgpt.com/backend-api/codex/models | Live Codex model metadata endpoint | | CODEX_PROXY_ALLOW_CUSTOM_UPSTREAM | unset | Set to 1 only if you intentionally use custom upstream URLs | | CODEX_PROXY_STRATEGY | sticky | sticky, round-robin, or hybrid | | CODEX_PROXY_TOKEN | unset | Optional bearer token required by the proxy | | CODEX_PROXY_DEBUG | unset | Print stack traces for request failures |

Implemented endpoints

• POST /v1/responses → forwards unchanged JSON/SSE to https://chatgpt.com/backend-api/codex/responses.
• POST /v1/responses/compact → forwards unchanged JSON/SSE to the Codex compaction endpoint.
• GET /v1/models → proxies live Codex model metadata.
• GET /health → health check.
• GET /status → local account/router status without token values.

On 429, the proxy records the model-specific reset time and retries another available account. On success, it stores prompt_cache_key stickiness so a Codex session keeps using the same account.

Security notes

• Tokens are stored locally at ~/.codex/multi-auth/openai-accounts.json with owner-only permissions where the OS supports them.
• The default proxy binds to 127.0.0.1, so other devices cannot reach it, but other local processes on your machine can. Use CODEX_PROXY_TOKEN if you need a bearer-token gate.
• Legacy OpenCode accounts are not imported automatically. If you want to migrate an existing account file, run cma sync-accounts or npm run sync-accounts explicitly.