npm install -g --allow-scripts=bun @bitkyc08/opencodex
ocx start
Claude Code, running any model
The picker is stock Claude Code. The brain behind it isn't.
Codex, running any model
Pick a provider and go — same workflow, different brain.
Claude Desktop, running any model
Opus answers, then hands the task to a GPT-5.6 Sol subagent.
Grok Build, running any model
Sol drives the session and calls a Kimi K3 subagent.
opencodex is a lightweight local gateway between your coding tools and your model providers. It
accepts the Responses, Chat Completions and Anthropic Messages APIs and translates each request into
whatever your provider speaks, carrying streaming, tool calls, reasoning and images where the client,
model and provider support them. Use Claude, Gemini, Grok, GLM, DeepSeek, Kimi, Qwen, Ollama and other
providers with Codex, Claude Code, Claude Desktop, Grok Build and the tools listed on the
client support page.
Quick start
Personal install (CLI)
npm install -g --allow-scripts=bun @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.
Connect your tool
Connect the tool you already use:
| Tool | How to connect |
|---|
| Codex | Turn on the Codex switch on the dashboard's Connect page, then run codex as usual. On a local listener this points Codex's built-in provider at the proxy. From the terminal, run ocx init before adding providers in the dashboard and accept its Codex prompt. |
| Claude Code | With the claude CLI installed, run ocx claude. It starts the proxy if needed and launches Claude Code through it. |
| Claude Desktop | Run ocx claude desktop. On a new install it sets up the gateway profile for the whole app; an existing first-party setup is kept, and ocx claude desktop apply --gateway switches explicitly. See the Claude Code guide. Fully quit and reopen Claude Desktop after a switch. |
| Grok Build | On a local listener with Grok integration enabled, ocx start registers the models when ~/.grok exists; pick an ocx-* model in Grok Build. Remote setups: see the Grok Build guide. After adding providers, restart the proxy (or run ocx ensure when Codex autostart is enabled) to refresh the list. |
| Tools with a managed integration | Use the dashboard Connect page, or ocx integration client enable --client <id>. |
| Any other tool | Set a custom OpenAI-compatible base URL of http://localhost:10100/v1, or an Anthropic base URL of http://localhost:10100. |
The client support page lists which path each tool has
and which protocol it speaks.
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 | Code signing via SignPath Foundation is rolling out (code signing policy); until a release is signed, 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.
Sponsors
Sponsors keep opencodex maintained across every upstream protocol change. Interested?
See SPONSORS.md.
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
This is the beginning of the README. Read the rest at the original. Read the full README ↗
