opencodex

<p align="center"> <img src="assets/banner.png" alt="opencodex — universal provider proxy for Codex, Claude Code, Claude Desktop and Grok Build" width="100%"> </p> <h3 align="center">make codex open!</h3> <p align="center"><b>Universal provider proxy for OpenAI Codex, Claude Code, Claude Desktop &amp; Grok Build</b><br> Two commands, and every one of them runs any LLM you point it at.</p> <p align="center"> <a href="https://x.com/claudeebum"><img src="https://img.shields.io/badge/%40claudeebum-000000?logo=x&logoColor=white" alt="Follow @claudeebum on X"></a> <a href="https://github.com/lidge-jun/opencodex/releases/latest"><img src="https://img.shields.io/github/v/release/lidge-jun/opencodex?label=desktop&logo=github&color=24292f" alt="Latest desktop release"></a> <a href="https://www.npmjs.com/package/@bitkyc08/opencodex"><img src="https://img.shields.io/npm/v/@bitkyc08/opencodex?color=cb3837&label=npm&logo=npm" alt="npm version"></a> <a href="https://github.com/lidge-jun/opencodex/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@bitkyc08/opencodex?color=blue" alt="license"></a> <img src="https://img.shields.io/node/v/@bitkyc08/opencodex?logo=node.js&label=node" alt="node version"> </p> <p align="center"> <a href="https://github.com/lidge-jun/opencodex/releases/latest"><img src="assets/download-macos.svg" alt="Download OpenCodex for macOS" width="220"></a> <a href="https://github.com/lidge-jun/opencodex/releases/latest"><img src="assets/download-windows.svg" alt="Download OpenCodex for Windows" width="220"></a> <a href="https://github.com/lidge-jun/opencodex/releases/latest"><img src="assets/download-linux.svg" alt="Download OpenCodex for Linux" width="220"></a> </p> <p align="center">_{Desktop app (beta): macOS universal <code>.dmg</code> · Windows x64 <code>.msi</code> · Linux x86_64 <code>.AppImage</code> / <code>.deb</code>. Prefer the terminal? Install the CLI:}</p>

npm install -g @bitkyc08/opencodex
ocx start

<table> <tr> <td width="50%" valign="middle">

Claude Code, running any model

The picker is stock Claude Code. The brain behind it isn't.

</td> <td width="50%"> <img src="assets/claude-code-models.gif" alt="Claude Code running a routed model through opencodex — the status bar shows gpt-5.6-luna-medium as the active model" width="100%"> </td> </tr> <tr> <td width="50%" valign="middle">

Codex, running any model

Pick a provider and go — same workflow, different brain.

</td> <td width="50%"> <img src="https://raw.githubusercontent.com/lidge-jun/opencodex/main/assets/demo.gif" alt="opencodex demo — running a task in the Codex app on a routed non-OpenAI model" width="100%"> </td> </tr> <tr> <td width="50%" valign="middle">

Claude Desktop, running any model

Opus answers, then hands the task to a GPT-5.6 Sol subagent.

</td> <td width="50%"> <img src="https://raw.githubusercontent.com/lidge-jun/opencodex/main/assets/claude-desktop-subagent.gif" alt="Claude Desktop answering as Claude Opus 4.8, then dispatching a GPT-5.6 Sol subagent through opencodex" width="100%"> </td> </tr> <tr> <td width="50%" valign="middle">

Grok Build, running any model

Sol drives the session and calls a Kimi K3 subagent.

</td> <td width="50%"> <img src="https://raw.githubusercontent.com/lidge-jun/opencodex/main/assets/grok-build-subagent.gif" alt="Grok Build running GPT-5.6 Sol through opencodex and calling a Kimi K3 subagent" width="100%"> </td> </tr> </table> <p align="center"> <a href="README.md">English</a> · <a href="readme/README.fr.md">Français</a> · <a href="readme/README.ko.md">한국어</a> · <a href="readme/README.zh-CN.md">简体中文</a> · <a href="readme/README.zh-TW.md">繁體中文</a> · <a href="readme/README.ru.md">Русский</a> · <a href="readme/README.ja.md">日本語</a> · <a href="readme/README.tr.md">Türkçe</a> · 📖 <a href="https://opencodex.me/"><b>Full documentation →</b></a> </p>

opencodex is a lightweight local proxy that translates Codex's Responses API into whatever your provider speaks — streaming, tool calls, reasoning tokens, images, in both directions. Use Claude, Gemini, Grok, GLM, DeepSeek, Kimi, Qwen, Ollama, or any other LLM with Codex, Claude Code, Claude Desktop, and Grok Build. It can also manage a ChatGPT account pool for Codex auth: add accounts, refresh their quotas in the dashboard, and let new sessions auto-route to the lowest-usage healthy account while existing threads stay pinned to the account that started them.

Quick start

Desktop app (beta)

The desktop app is the same proxy and dashboard in a native window, with a tray and bundled ocx. It attaches to a proxy that is already running, or starts its bundled one, and the dashboard stays on the proxy port (http://localhost:10100 unless you configured another). Pick the file for your platform from the latest release:

| Platform | File | Notes | |---|---|---| | macOS 13+ (Apple Silicon and Intel) | OpenCodex-<version>-macos.dmg | Universal build, signed with a Developer ID and notarized | | Windows (x64) | OpenCodex-<version>-windows-x64.msi | Not code-signed yet: SmartScreen asks once, choose More info → Run anyway | | Linux (x86_64) | OpenCodex-<version>-linux-x86_64.AppImage or -linux-amd64.deb | The tray needs an AppIndicator-capable desktop |

Every file has a .sha256 next to it on the release page. On macOS 14+ the app also ships a WidgetKit extension that shows proxy status, today's usage and provider quotas; the snapshot model it renders lives in app/ (MenuBarCore). To build the app yourself, run bun install && bun run build:gui at the repository root, then in desktop/ run bun install && bun run prepare-sidecar && bun run prepare-widget && bun run build:local on macOS, or bun install && bun run prepare-sidecar && bun run build:local on Windows and Linux (the widget step needs macOS). The Desktop App guide and the macOS Menu Bar App guide cover first launch, and AGENTS_INSTALL.md lists everything written to disk.

Personal install (CLI)

npm install -g @bitkyc08/opencodex   # Node 18+; the Bun runtime is bundled automatically
ocx start                         # proxy + dashboard on localhost:10100

Use ocx service to run it in the background.

Open http://localhost:10100 and configure everything in the web dashboard — add providers (40+ built-ins, or any OpenAI-compatible endpoint), pick models, manage accounts. ocx gui re-opens the dashboard at any time.

ChatGPT account pool

opencodex can also manage a ChatGPT account pool for Codex auth. Add multiple ChatGPT / Codex accounts, refresh their 5h / weekly / 30d quota in the dashboard. Under quota routing, new sessions can use the lowest-usage healthy account; round-robin and fill-first use their own policies. Existing Codex threads normally retain affinity to the account that started them, so long SSH, tmux, or mobile-connected sessions do not jump accounts mid-conversation — but quota re-evaluation, failover, account exclusion, affinity expiry, or 401/403 and 429 recovery can rebind them. Give the accounts a selection order when one of them — usually your Codex Desktop login — should only be reached for once the others are drained.

Sponsors

Sponsors keep opencodex maintained across every upstream protocol change. Interested? See SPONSORS.md.

<!-- sponsors:main — one banner, model developers only; empty until a Main sponsor signs --> <!-- sponsors:standard — one row per sponsor, in order of signing --> <table> <tbody> <tr> <td width="180"><a href="https://www.orcarouter.ai/?utm_source=opencodex&utm_medium=readme"><img src="assets/sponsors/orcarouter.png" alt="OrcaRouter" width="150"></a></td> <td>Thanks to <a href="https://www.orcarouter.ai/?utm_source=opencodex&utm_medium=readme">OrcaRouter</a> for sponsoring this project! OrcaRouter is one OpenAI-compatible AI gateway for production AI: adaptive routing that grades every prompt and sends it to the model that clears your bar, automatic failover, routing rules as code, zero-markup provider pricing with prompt caching, and guardrails, an agent firewall, and request logs on every call across 200+ models. Pick <code>OrcaRouter</code> in the Add provider picker or run <code>ocx provider add orcarouter</code>; <code>orcarouter/auto</code> is the adaptive router.</td> </tr> <tr> <td width="180"><a href="https://www.packyapi.com/register?aff=k5KT"><img src="assets/sponsors/packycode.png" alt="PackyCode" width="150"></a></td> <td>Thanks to <a href="https://www.packyapi.com/register?aff=k5KT">PackyCode</a> for sponsoring this project! PackyCode is a stable, high-performance API relay provider, offering relay services for Claude Code, Codex, Gemini, and more. With automatic failover, smart routing, and unlimited concurrency, it turns AI into a real productivity tool. <a href="https://www.packyapi.com/register?aff=k5KT">Register via this link</a> and get started! Pick <code>PackyCode</code> in the Add provider picker or run <code>ocx provider add packycode</code>.<br>_{PackyCode 是一家稳定、高效的 API 中转服务商，提供 Claude Code、Codex、Gemini 等多种中转服务。具备自动故障转移、智能路由和无限并发等多种功能，让 AI 编程成为真正的生产力工具。<a href="https://www.packyapi.com/register?aff=k5KT">点此链接注册</a>，立即开始使用！}</td> </tr> </tbody> </table>

---

<details> <summary>Docker Compose</summary>

The repository ships a digest-pinned, non-root Compose build. The build generates and verifies the canonical compatibility manifest from the selected Git snapshot. A local clone needs Git and Docker Compose; a remote Git context needs Docker Compose. Neither path needs host Bun or a preparation step. Initialize the data-plane token once through stdin and start the hub:

git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
docker compose build
openssl rand -hex 32 | docker compose run --rm -T hub bun run docker/bootstrap-token.ts
docker compose up -d
curl --fail --silent http://127.0.0.1:10100/healthz
curl --fail --silent http://127.0.0.1:10100/readyz

The default host binding is 127.0.0.1:10100. Remote exposure requires explicit OPENCODEX_BIND_ADDRESS=<LAN-or-Tailscale-IP> docker compose up -d; 0.0.0.0 opts into all host interfaces. Restrict access with a firewall and an authenticated TLS/tailnet frontend. The generated JSON stays untracked. The build context admits only .git/index and .git/HEAD — the inventory git ls-files reads, about 1 MB rather than the full object store — and they are visible only to the build-only manifest stage through a read-only mount, so no COPY includes .git. An existing host-generated manifest is still accepted only after validation; otherwise the build generates one itself. The build rejects stale manifests, missing or mismatched files, extra source files, and symlinks. It checks every recorded SHA-256 against the build context and copied runtime files, including package.json, bun.lock, and the specifically included scripts/model-metadata.source.json.

A remote Git context needs BuildKit to retain Git metadata. This Compose build fragment selects the remote snapshot and passes the required built-in argument:

services:
  hub:
    pull_policy: build
    build:
      context: https://github.com/lidge-jun/opencodex.git#main
      dockerfile: Dockerfile
      target: runtime
      args:
        BUILDKIT_CONTEXT_KEEP_GIT_DIR: "1"

The token and mutable state stay in the ocx-state named volume; no credential is placed in the image, Compose file, environment, or shell arguments. See the Remote Hub deployment guide for provider setup, authenticated acceptance checks, remote management, and rollback.

</details> <details> <summary>Install from source (latest dev)</su