Skip to content
Dodelidoo-LabsPublic

About

A self-hosted provider router for Codex with multi-account routing, quota-aware failover, provider catalogs, and private aggregate telemetry.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

OpenCDX Router logo

OpenCDX Router

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.

What to download

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.

Highlights

  • 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, /usage command, and telemetry hooks. See Claude Code.

Screenshots

Click any screenshot to open it at full size.

OpenCDX telemetry dashboard
Telemetry and model usage
OpenCDX OpenAI accounts dashboard
OpenAI account routing and allowances
OpenCDX provider health dashboard
Provider health and endpoints
OpenCDX model catalog
Searchable model catalog and exclusions
OpenCDX paired devices dashboard
Paired and revocable devices
OpenCDX administrator sign-in
Administrator sign-in
OpenCDX Router macOS menu
Native macOS menu-bar companion
OpenCDX Router macOS settings
Router enrollment and usage-history settings

Install OpenCDX

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.

1. Deploy the router

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/.env

Edit docker/.env with your router's DNS name and ACME email:

OPENCODEX_DOMAIN=router.example.com
ACME_EMAIL=you@example.com
OPENCODEX_VERSION=latest

Use 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 ps

Open 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.

2. Install the macOS companion

  1. Open the latest GitHub Release.
  2. Download OpenCDX-Router-<version>-macOS-universal.zip. This is the Mac app, not the Docker router.
  3. Expand the ZIP and move OpenCDX Router.app to /Applications or ~/Applications.
  4. 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.

3. Pair the Mac

  1. Open OpenCDX Router Settings from the menu-bar app.
  2. Enter the router's HTTPS address and a recognizable device name.
  3. Choose Request Enrollment.
  4. Open Devices in the web dashboard and approve the pending Mac.
  5. 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.

4. Connect accounts and configure Codex

  1. Choose Add OpenAI Account… in the menu app and complete the fresh browser login. Repeat for each account you want in the routing pool.
  2. Optionally configure OpenRouter or Ollama from Providers in the dashboard.
  3. Choose Copy Codex Configuration after the first catalog sync.
  4. Paste the generated snippet into ~/.codex/config.toml and 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.

5. Optional: show Claude Code allowance and usage

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.

Updating

  • macOS companion: choose Check for Updates… in the menu. Signed updates are delivered from GitHub Releases through Sparkle.
  • Router: set OPENCODEX_VERSION to the desired tag, then run the production Compose pull and up -d commands 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.

Privacy and security

  • 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.

Documentation

The documentation index separates operator, advanced-user, contributor, verification, security, and release-maintainer guides.

About

A self-hosted provider router for Codex with multi-account routing, quota-aware failover, provider catalogs, and private aggregate telemetry.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages