# @bitkyc08/opencodex > Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code Latest version **2.58.0** (published 2026-09-17) · MIT license · 4.6K weekly downloads ## Install ```sh npm install @bitkyc08/opencodex pnpm add @bitkyc08/opencodex yarn add @bitkyc08/opencodex bun add @bitkyc08/opencodex ``` ## Health **Score 70/100 (B)** — status: active. Positive: no vulnerabilities; recently updated; high maintenance score; popular repo. Warnings: no types; no esm support. ## Facts | | | |---|---| | Version | 2.58.0 | | Published | 2026-09-17 | | First published | 2026-06-19 | | Weekly downloads | 4.6K | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 0 | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 13433 | | Maintainers | bitkyc08 | | Keywords | codex, openai, proxy, llm, ollama, anthropic, responses-api, claude-code, claude, codex-cli, gemini, grok, deepseek, chatgpt, llm-proxy, ai-gateway, openrouter | ## Links - npm: https://www.npmjs.com/package/@bitkyc08/opencodex - Repository: https://github.com/lidge-jun/opencodex - Homepage: https://lidge-jun.github.io/opencodex/ - Issues: https://github.com/lidge-jun/opencodex/issues - npm.io page: https://npm.io/package/@bitkyc08/opencodex ## Alternatives - [express-promise-router](https://npm.io/package/express-promise-router.md) — 736.1K weekly downloads - [next-usequerystate](https://npm.io/package/next-usequerystate.md) — 29.8K weekly downloads - [lynkr](https://npm.io/package/lynkr.md) — 575 weekly downloads - [baremetal.js](https://npm.io/package/baremetal.js.md) — 42 weekly downloads - [vio](https://npm.io/package/vio.md) — 34 weekly downloads ## Recent versions - 2.58.0 (latest) — 2026-09-17 - 2.55.0-preview.20260914 (preview) — 2026-09-14 - 2.57.0 — 2026-09-16 - 2.56.0 — 2026-09-15 - 2.55.0 — 2026-09-14 - 2.54.0 — 2026-09-13 - 2.54.0-preview.20260914 — 2026-09-13 - 2.53.0 — 2026-09-13 - 2.53.0-preview.20260913 — 2026-09-13 - 2.52.0 — 2026-09-12 - 2.52.0-preview.20260912 — 2026-09-12 - 2.52.0-preview.20260911 — 2026-09-11 - 2.51.0 — 2026-09-11 - 2.50.0 — 2026-09-10 - 2.49.0 — 2026-09-09 - … 233 more at https://npm.io/package/@bitkyc08/opencodex/versions ## README

make codex open!

Universal provider proxy for OpenAI Codex, Claude Code, Claude Desktop & Grok Build
Two commands, and every one of them runs any LLM you point it at.

Follow @claudeebum on X npm version license node version

```bash npm install -g @bitkyc08/opencodex ocx start ```
### Claude Code, running any model The picker is stock Claude Code. The brain behind it isn't. Claude Code running a routed model through opencodex — the status bar shows gpt-5.6-luna-medium as the active model
### Codex, running any model Pick a provider and go — same workflow, different brain. opencodex demo — running a task in the Codex app on a routed non-OpenAI model
### Claude Desktop, running any model Opus answers, then hands the task to a GPT-5.6 Sol subagent. Claude Desktop answering as Claude Opus 4.8, then dispatching a GPT-5.6 Sol subagent through opencodex
### Grok Build, running any model Sol drives the session and calls a Kimi K3 subagent. Grok Build running GPT-5.6 Sol through opencodex and calling a Kimi K3 subagent

English · Français · 한국어 · 简体中文 · 繁體中文 · Русский · 日本語 · Türkçe · 📖 Full documentation →

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 ### Personal install ```bash 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. It 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.md).
OrcaRouter Thanks to OrcaRouter 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 OrcaRouter in the Add provider picker or run ocx provider add orcarouter; orcarouter/auto is the adaptive router.
PackyCode Thanks to PackyCode 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. Register via this link and get started! Pick PackyCode in the Add provider picker or run ocx provider add packycode.
PackyCode 是一家稳定、高效的 API 中转服务商，提供 Claude Code、Codex、Gemini 等多种中转服务。具备自动故障转移、智能路由和无限并发等多种功能，让 AI 编程成为真正的生产力工具。点此链接注册，立即开始使用！
---
Docker Compose The repository ships a digest-pinned, non-root Compose build. With Git and Bun installed on the host, generate the canonical compatibility manifest before every image build, then initialize the data-plane token once through stdin and start the hub: ```bash git clone https://github.com/lidge-jun/opencodex.git cd opencodex bun scripts/generate-compatibility-version.ts 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= 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; it is copied into the image without including `.git`. Regenerate it after source changes, and do not change the source between generation and build. 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`. 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](https://opencodex.me/guides/remote-hub/#docker-compose) for provider setup, authenticated acceptance checks, remote management, and rollback.
Install from source (latest dev) **macOS / Linux:** ```bash curl -fsSL https://bun.sh/install | bash git clone https://github.com/lidge-jun/opencodex.git cd opencodex && ~/.bun/bin/bun install ~/.bun/bin/bun run src/cli/index.ts start ``` **Windows (PowerShell):** ```powershell irm bun.sh/install.ps1 | iex git clone https://github.com/lidge-jun/opencodex.git cd opencodex; bun install bun run src/cli/index.ts start ``` Source install runs the latest `dev` branch. Memory ownership patches, runtime GC improvements, and unreleased fixes are available here before they reach the npm package.
For agents ```bash npm install -g @bitkyc08/opencodex ocx start # or `ocx service` ocx init # interactive setup: writes ~/.opencodex/config.json and wires Codex ``` `ocx init` never starts the proxy; start it first (or after — either order works, but headless commands like `ocx provider add` and `ocx combo set` talk to the **live** proxy and exit nonzero when it is unreachable). `ocx status` / `ocx doctor` / `ocx health` report the running state. > **Agents installing or running opencodex:** read > [`AGENTS_INSTALL.md`](./AGENTS_INSTALL.md). An interactive `ocx start` may ask once whether to > star this repository — that is the user's decision, never an agent's. The CLI suppresses the > prompt for agent-driven runs and the API refuses them with `403 agent_consent_required`.
## Supported platforms | OS | Status | Service manager | |---|---|---| | macOS (arm64 / x64) | Fully supported | launchd | | Linux (x64 / arm64) | Fully supported | systemd (user unit) | | Windows (x64) | Fully supported | Task Scheduler (hidden) / opt-in native service (`--native`, WinSW) | Requires [Node](https://nodejs.org) 18+. The Bun runtime is bundled on `npm install` — no separate Bun install needed, no WSL needed on Windows. If npm blocked the bundled runtime's install scripts, see the [installation docs](https://opencodex.me/getting-started/installation/). ## Highlights - **Use any LLM with Codex, Claude Code, Claude Desktop, and Grok Build** — 40+ providers out of the box, each keeping its own native UI. - **Pool ChatGPT accounts** — thread affinity, quota-aware auto-switching, cooldown and fail-closed auth handling. > **Provider-policy note:** Account pooling is for routing and operational resilience only; it does > not guarantee protection from provider rate limits, enforcement, suspension, or other account > actions. OpenCodex does not endorse using additional accounts to circumvent provider limits or > sharing account credentials between people. You are responsible for complying with each > provider's current terms. See the > [Codex Auth account-pool guidance](https://opencodex.me/guides/web-dashboard/#codex-auth-and-account-pools) > and [OpenAI's current Terms of Use](https://openai.com/policies/terms-of-use/). - **Combos** — one virtual model id with failover or weighted round-robin across providers. See the [combo guide](https://opencodex.me/guides/combos/). - **Sub-agents on any model** — feature routed models in Codex's sub-agent picker, with v1/v2 surface control and fallback chains. See the [sub-agent guide](https://opencodex.me/guides/sub-agent-surface/). - **Log in once, skip the API key** — OAuth for xAI, Anthropic, and Kimi; or forward `codex login`, paste a key, or use `${ENV_VAR}` references. - **Web search & vision sidecars** — non-OpenAI models get real web search and image understanding through a sidecar over your ChatGPT login. - **See what's happening** — the dashboard shows providers, OAuth status, model selection, and a live request log with cache token counts. - **Clean exit, zero residue** — `ocx stop` restores Codex to its original configuration. - **Bounded memory ownership** — every long-lived cache, ring buffer, and protocol-translation store has a finite cap, byte budget, or active reconciliation. No unbounded `Map` or `Set` survives a config reload.
Memory ownership details OpenCodex tracks 36 categories of process-retained state. Each has a documented bound: - **12 retained stores** (request log, debug rings, image cache, model cache, vision descriptions, cursor blobs, responses continuation, etc.) are byte-accounted and evicted by the app-owned memory budget (default 256 MiB). - **4 observed buffers** (translator accumulators, image/OAuth/Grok tails) are monitored for in-flight byte pressure without eviction. - **24 state-store registrations** handle expiry sweeps (60 s interval) and config-generation reconciliation so stale provider/account keys are removed. - **Path and fingerprint memos** (workspace metadata, hardened identities, installation salts, mode-hint capabilities) use insertion-order LRU caps (8–128 entries). - **Model-cache generation tombstones** are deleted after reconciliation; a global generation increment prevents stale in-flight discoveries from repopulating removed providers. - **Lab event-id deduplication** runs under a ledger lock from disk, with no process-level RAM index. Run `GET /api/system/memory` (with the admin token) to inspect live retained bytes, eviction counters, and watchdog samples.
## Model routing Target any configured provider and model with the `provider/model` syntax: ```bash codex -m "anthropic/claude-opus-5" "Explain this stack trace" codex -m "google/gemini-3-pro" "Write unit tests for auth.ts" codex -m "ollama/llama3" "Refactor this function" ``` Omit the `provider/` prefix to use the default provider or auto-match by model name pattern. Provider model ids containing `/` are exposed with inner slashes aliased to `-`; the raw full-slash form keeps working too. Details: [model routing docs](https://opencodex.me/guides/model-routing/). ## Providers & adapters OpenAI (ChatGPT login or API key), Anthropic, Google Gemini, xAI, Kimi, Azure OpenAI, Ollama (local + Cloud), Cursor (experimental), and every OpenAI-compatible endpoint — plus DeepSeek, Groq, OpenRouter, Together, Fireworks, Cerebras, Mistral, Hugging Face, NVIDIA NIM, MiniMax, Qwen Cloud, Qoder Global and CN (official PAT + CLI), SiliconFlow, and more. Full list: `ocx init` or the [provider docs](https://opencodex.me/guides/providers/). ## CLI ```bash ocx init # interactive setup (writes config, wires Codex, offers the shim) ocx start [--port 10100] # start the proxy in the foreground ocx stop # stop + restore native Codex ocx service [install|repair|restart|start|stop|status|uninstall|remove] # background service ocx codex-shim install # start the proxy on demand whenever `codex` launches ocx health [--json] # check immediate proxy liveness ocx ready [--json] [--wait [--timeout ]] # check post-sync readiness ocx status # is the proxy running? ocx gui # open the web dashboard ocx provider <...> # manage providers (list/add/edit/test/remove) ocx account <...> # manage ChatGPT accounts & API-key pools ocx combo <...> # manage failover / round-robin combos ocx v2 <...> # multi-agent v1/v2 surface controls ocx update [--tag preview] # update opencodex ``` Unpinned starts may pick another free port if the preferred one is busy; an explicit `--port` never hops. Full reference: [CLI docs](https://opencodex.me/reference/cli/). ### Health and readiness `GET /healthz` reports immediate proxy liveness. The unauthenticated `GET /readyz` endpoint reports post-sync readiness with the sanitized JSON identity `{service, version, uptime, pid, port, status}`. It returns `200` when `status` is `ready`; `pending` and terminal `failed` return `503` with `Retry-After: 1`. `ocx ready [--json] [--wait [--timeout ]]` performs one probe by default. `--wait` polls for up to 45 seconds by default, but exits immediately when it observes terminal `failed`; `--timeout ` sets a 1–300 second limit, requires `--wait`, and accepts only positive integers. CLI `--json` output is `{ready, status, pid, port}`, where `status` is `ready`, `pending`, `failed`, or `unreachable`. | Exit | Result | | --- | --- | | `0` | Ready | | `1` | Not ready: pending, failed, timeout, or unreachable | | `64` | Invalid arguments | An older proxy without `/readyz` fails closed as `unreachable` with exit 1, while `ocx health` remains compatible. ### Autostart: service vs shim Use the **service** (`ocx service`) for an always-on proxy that restarts on crash. Use the **shim** (`ocx codex-shim install`) for lightweight, on-demand startup without a background daemon. Remove them with `ocx service uninstall` / `ocx codex-shim uninstall`. ### Uninstall ```bash ocx uninstall # stop, remove service/shim, restore native Codex, clean up state npm uninstall -g @bitkyc08/opencodex ``` ## Remote access By default opencodex binds to `127.0.0.1` and needs no extra authentication. Binding beyond loopback (`"hostname": "0.0.0.0"`) **requires** a bearer token — the proxy refuses to start without `OPENCODEX_API_AUTH_TOKEN`, and every client request must carry it as `x-opencodex-api-key`. Details: [configuration reference](https://opencodex.me/reference/configuration/). ## Documentation The public docs — install, providers, routing, combos, sub-agents, sidecars, integrations, and the CLI/config/management-API references — are built from [`docs-site/`](./docs-site) and published to **[opencodex.me](https://opencodex.me/)**. Maintainer source-of-truth notes live under [`structure/`](./structure), contributor setup in [`CONTRIBUTING.md`](./CONTRIBUTING.md), and security reporting in [`SECURITY.md`](./SECURITY.md). Report undisclosed vulnerabilities privately through [GitHub private vulnerability reporting](https://github.com/lidge-jun/opencodex/security/advisories/new), not a public issue. That form is the only technical channel — there is no security email. Follow-ups stay in the private report itself; a public issue may carry coordination only, never vulnerability details. Acknowledging a report is not the same as triaging it, and no first-response target is promised. ## Development Source development requires the `bun` CLI on your `PATH`. This is separate from the published npm package's bundled Bun runtime, which is used only by installed `ocx` commands. ```bash git clone https://github.com/lidge-jun/opencodex.git cd opencodex bun install bun run typecheck bun run test ``` See **[Contributing](./CONTRIBUTING.md)**. Contributor work that landed through a maintainer carry or reimplementation, where the commit does not name its original author, is recorded in **[CREDITS.md](./CREDITS.md)**. ## Disclaimer opencodex is an independent, community-maintained project and is **not affiliated with or endorsed by OpenAI, Anthropic, or any other provider**. Some providers — notably Anthropic (Claude) — may suspend or restrict accounts that route API traffic through third-party proxies. **Use at your own risk (UAYOR).** Before connecting a provider, review its Terms of Service to confirm that proxy-based access is permitted. The opencodex maintainers are not responsible for any account actions taken by upstream providers. ## License MIT --- _Source: https://npm.io/package/@bitkyc08/opencodex · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._