A self-hosted provider router for Codex with multi-account routing, quota-aware failover, provider catalogs, and private aggregate telemetry.
Download the macOS app · Get the router container · Documentation
OpenCDX gives Codex one local endpoint while a central router manages OpenAI accounts, provider credentials, model catalogs, quotas, and routing. Each Mac uses a native menu-bar app and a bundled loopback helper to reach the router securely.
Codex → local helper → HTTPS → OpenCDX Router → OpenAI / OpenRouter / Ollama
OpenCDX does not replace Codex or reuse an existing Codex, ChatGPT, or browser login. Each OpenAI account is connected through a fresh browser sign-in, and OpenCDX never edits ~/.codex/config.toml for you.
OpenCDX has two separately distributed parts:
| Component | Download location | What it contains |
|---|---|---|
| Router service | GitHub Packages | The multi-architecture Docker image at ghcr.io/dodelidoo-labs/open-cdx |
| macOS companion | GitHub Releases | The signed and notarized universal macOS app, including its bundled helper |
GitHub Releases do not contain the Docker image. The runnable release download is the macOS companion app; Docker pulls the router from GitHub Packages. Release pages also carry checksum and update-feed metadata for the Mac app.
- Route across multiple OpenAI accounts with an operator-selected primary account, sticky sessions, quota tracking, and automatic fallback.
- Add compatible OpenRouter and Ollama models without losing the native OpenAI catalog.
- Inspect model availability, exclusions, provider health, devices, account allowances, and reset windows from the web dashboard.
- See router health and account quota at a glance from the macOS menu bar.
- Keep OpenAI and provider credentials in encrypted router storage; paired Macs receive only revocable device credentials.
- Track daily request and token totals without storing prompts or responses.
- Track changes to Codex catalog instructions with instruction history, unread updates, and per-field diffs.
- Inspect per-request errors, model settings, token usage, timing, and routing attempts in Logs, with portable backup and restore.
- Reconcile aggregate usage from an existing local Codex history without sending conversation content to the router.
- See your Claude plan allowance in the menu bar and Claude Code usage on the dashboard, observed through Claude Code's own status line,
/usagecommand, and telemetry hooks. See Claude Code.
Click any screenshot to open it at full size.
You need:
- A host with Docker Engine and Docker Compose v2 for the router.
- A DNS name for that host, with ports 80 and 443 reachable so the included Caddy service can provide HTTPS.
- A Mac running macOS 13 or newer for the companion app. Both Apple silicon and Intel Macs are supported.
- Codex installed separately on the Mac.
Clone this repository to the Docker host and create the production configuration:
git clone https://github.com/Dodelidoo-Labs/open-cdx.git
cd open-cdx
cp docker/.env.example docker/.envEdit docker/.env with your router's DNS name and ACME email:
OPENCODEX_DOMAIN=router.example.com
ACME_EMAIL=you@example.com
OPENCODEX_VERSION=latestUse latest to follow the newest stable container, or pin OPENCODEX_VERSION to a published version from GitHub Packages.
Generate the router secrets and start the HTTPS stack:
./scripts/generate-docker-secrets.sh
docker compose --env-file docker/.env -f docker/compose.production.yml pull
docker compose --env-file docker/.env -f docker/compose.production.yml up -d
docker compose --env-file docker/.env -f docker/compose.production.yml psOpen https://router.example.com/admin and sign in with the administrator token from docker/secrets/admin_token.
Keep docker/secrets/master_key backed up separately from the Docker data volume. The database cannot recover encrypted provider credentials without that key. See the deployment guide for DNS, firewall, backup, Tailscale, verification, and upgrade details.
- Open the latest GitHub Release.
- Download
OpenCDX-Router-<version>-macOS-universal.zip. This is the Mac app, not the Docker router. - Expand the ZIP and move OpenCDX Router.app to
/Applicationsor~/Applications. - Launch the app. It is Developer ID signed and notarized by Apple.
The app includes the correct helper binary for both Apple silicon and Intel Macs; there is no separate helper download.
- Open OpenCDX Router Settings from the menu-bar app.
- Enter the router's HTTPS address and a recognizable device name.
- Choose Request Enrollment.
- Open Devices in the web dashboard and approve the pending Mac.
- Wait for the menu to show Router — Responding and Catalog — Synchronized.
Each paired Mac has its own revocable device credential. Removing a device in the dashboard immediately ends that Mac's router access.
- Choose Add OpenAI Account… in the menu app and complete the fresh browser login. Repeat for each account you want in the routing pool.
- Optionally configure OpenRouter or Ollama from Providers in the dashboard.
- Choose Copy Codex Configuration after the first catalog sync.
- Paste the generated snippet into
~/.codex/config.tomland restart Codex.
The configuration points Codex at the local helper. Codex receives a short-lived local credential; it never receives the router's stored OpenAI refresh tokens or provider API keys.
For the new ChatGPT desktop app (Chat, Work, and dots), quit ChatGPT and choose Launch ChatGPT from the OpenCDX menu each time you start it. The app uses its own native configuration and sign-in, while CLI and IDE clients keep routing. See ChatGPT app bypass for the separate local history and first-use sign-in.
See Helper and Codex setup for advanced pairing, custom Codex homes, usage reconciliation, reset behavior, helper commands, and uninstall steps.
Choose Connect Claude Code… in the menu app and review the proposed changes to ~/.claude/settings.json. OpenCDX wraps your existing status line and exports Claude Code's per-request token counts to the local helper. Claude Code keeps its own login and talks to Anthropic directly; OpenCDX never routes it or handles Claude credentials. See Claude Code.
- macOS companion: choose Check for Updates… in the menu. Signed updates are delivered from GitHub Releases through Sparkle.
- Router: set
OPENCODEX_VERSIONto the desired tag, then run the production Composepullandup -dcommands again. Router images come from GitHub Packages.
Back up the router database volume and docker/secrets/master_key together before an upgrade. Full instructions are in Deployment.
- OpenAI access and refresh tokens and provider API keys exist only in encrypted router storage and transient router memory.
- The helper binds only to the Mac's loopback interface and keeps its device credential in Keychain.
- Prompts and responses are streamed and are not logged or stored by OpenCDX.
- Claude Code integration observes only allowance percentages and token counts; Claude credentials never reach OpenCDX.
- Telemetry contains aggregate request and token counts. Request logs retain selected metadata and bounded provider diagnostics, excluding conversation bodies.
- Production Mac-to-router traffic must use HTTPS. Plain HTTP on a LAN is available only through an explicit development override.
Read the complete security model for credential ownership, network boundaries, header filtering, retry rules, backup, and revocation.
The documentation index separates operator, advanced-user, contributor, verification, security, and release-maintainer guides.








