Installation

opencodex installs two equivalent command names, ocx and opencodex. Both launch the same small local HTTP server (built on Bun). Model requests go to the provider selected by routing; optional vision and web-search sidecars can also use your ChatGPT login when a routed model needs them.

Desktop terminal command

A stable OpenCodex Desktop install configures ocx for new terminals when the app starts. Open a new terminal and run ocx status or ocx doctor to inspect the first executable on PATH. On macOS and Linux deb installs, a managed block at the end of zsh, bash and fish startup files puts ~/.opencodex-desktop/bin first on PATH and uses the Desktop-owned shim. Windows puts the bundled ocx.exe install directory first in the user Path. Existing terminals, aliases, shell caches and later PATH changes can still select another command; a conflicting Windows system PATH entry can also win. Use the app’s Terminal command settings to repair, disable or remove this configuration. AppImage is excluded.

On macOS and Linux, a current npm/pnpm package launcher that still runs delegates eligible commands to the Desktop CLI when its record is enabled and passes ownership, permission and file-safety checks. Windows has no package-launcher handoff: new terminals select the Desktop ocx.exe through user Path order. A record-unsafe error means the record or its directory failed a safety check. Open OpenCodex Desktop to repair the terminal command, or use OCX_NO_DESKTOP_HANDOFF=1 for a package invocation on macOS/Linux. Package update/removal and internal inspection keep their existing path. OCX_NO_DESKTOP_HANDOFF=1 suppresses that package handoff for one invocation; it does not change a direct Desktop shim or PATH configuration.

Prerequisites

Requirement	Why
Node ≥ 18	ocx runs on the Bun runtime, but the runtime is bundled automatically by the npm or pnpm install — you do not need to install Bun yourself.
OpenAI Codex (CLI, App, or SDK)	The client opencodex sits in front of. opencodex writes to $CODEX_HOME/config.toml (default ~/.codex/config.toml).
A provider account or API key	Anthropic, xAI, Kimi, Ollama Cloud, OpenRouter, an OpenAI-compatible endpoint, or your ChatGPT login.

Install

npm install -g @bitkyc08/opencodex

With pnpm 10.4 or later:

pnpm add -g --allow-build=bun @bitkyc08/opencodex

npm blocked the bun postinstall?

Recent npm versions may block bun’s postinstall script (npm warn install-scripts ... blocked because they are not covered by allowScripts), which leaves the bundled Bun runtime unprepared. After trying permitted bundled-runtime recovery, the launcher can use an executable Bun from an absolute PATH directory if its stable version has the pinned major and a minor at least the pinned minor. With the current 1.4.2 dependency, that means 1.4.0 or newer within major 1. Bounded version-policy and identity checks require bun --version to match bun -e’s Bun.version. On POSIX, the launcher checks the whole candidate path, including ancestor directories and components reached through symlinks. Each traversed directory and symlink, and the resolved executable, must be owned by root or the launcher’s effective user. Directories and the resolved executable must not be group- or world-writable; symlink permission bits are not used. Shared writable ancestors such as /tmp are rejected even with the sticky bit, so protecting only the executable and its immediate parent is insufficient. A one-line stderr notice names the selected Bun version. Bun is still bundled; installing it yourself is optional.

If no runtime works, the error still includes “the bun dependency is not installed” when the dependency is missing. On macOS, it also names an executable Desktop CLI found at /Applications/OpenCodex.app/Contents/MacOS/ocx or ~/Applications/OpenCodex.app/Contents/MacOS/ocx. You can invoke that path explicitly; the package launcher does not delegate automatically or install a PATH shim.

To repair the bundled runtime, reinstall allowing bun’s script. Always include the package name: npm’s abbreviated suggestion omits it and would reinstall the current directory:

npm install -g --allow-scripts=bun @bitkyc08/opencodex

# if the original install used sudo, keep using sudo:
sudo npm install -g --allow-scripts=bun @bitkyc08/opencodex

Verify both command aliases are on your PATH:

ocx --version
opencodex --version

Before start, stop, restart, service, or an update handled by the Bun CLI, a brief stderr notice can identify a CLI/proxy version mismatch. It is advisory and preserves the command’s exit code; JSON and help output do not trigger it. npm/pnpm updates handled by the Node launcher before the Bun CLI starts do not emit this notice. ocx status, ocx doctor, and ocx resolve already report version skew through their diagnostics.

If you install the background service from a shell using fnm, nvm, mise, asdf, or volta, OpenCodex leaves shell-local multishell directories out of the service PATH. On Linux it selects a durable ocx launcher when available; otherwise it uses the package’s Bun runtime. Run ocx service repair after an older service was installed from a temporary multishell directory. On macOS, repair reloads launchd when it changes the saved plist.

Standalone binary (no npm)

Release downloads also include a standalone ocx binary for supported macOS, Linux, and Windows targets. It includes the Bun runtime and dashboard, so npm, Node, and a separate Bun installation are not required. Download the archive for your platform, extract it, and run:

./ocx --version
./ocx start

The extracted gui/dist and keyring directories must stay beside the binary. The first serves the dashboard; the second carries the platform-native OS credential-store binding.

On Windows, Windows Code Signing explains how ocx.exe is signed and how to verify it.

Release channels

The stable latest channel already includes GPT-5.6 Sol/Terra/Luna catalog support for ChatGPT, OpenAI API-key, OpenRouter, and experimental Cursor routes. Upstream access is still account-gated; the catalog entries do not grant access by themselves. Use the preview channel only to test unreleased opencodex builds:

npm install -g @bitkyc08/opencodex@preview
ocx update --tag preview

Run from source

To hack on opencodex itself:

git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
bun install
bun run dev:proxy   # starts the proxy API in dev mode (src/cli/index.ts start)
bun run dev:gui     # starts the dashboard dev server (another terminal)

bun run dev remains an alias for bun run dev:proxy. The proxy API exposes /healthz, /v1/responses, and /api/*; GET / serves the packaged dashboard only after bun run build:gui has produced gui/dist. While hacking on the dashboard, run the frontend separately with bun run dev:gui.

What gets created

opencodex state lives under $OPENCODEX_HOME (default ~/.opencodex). Codex integration files live under $CODEX_HOME (default ~/.codex).

Path	Purpose
$OPENCODEX_HOME/config.json	Your providers, default provider, port, and options.
$OPENCODEX_HOME/ocx.pid	PID of the running proxy (single-instance guard).
$OPENCODEX_HOME/runtime-port.json	The live PID, hostname, and port — including an OS-assigned port when config.port is 0.
$OPENCODEX_HOME/auth.json	Stored OAuth credentials (when you ocx login).
$OPENCODEX_HOME/catalog-backup*.json	Codex model catalog backups made before opencodex edits it.
$CODEX_HOME/config.toml	On loopback, opencodex adds a marker-owned root openai_base_url; non-loopback binds use model_provider = "opencodex" plus [model_providers.opencodex] so Codex can send the API-auth header.
$CODEX_HOME/opencodex.config.toml	Fallback/reference profile written alongside the main Codex config.
$CODEX_HOME/opencodex-catalog.json	Synced native and routed model catalog used by Codex.

Note

opencodex never deletes your Codex config. Every injection is reversible — ocx stop, ocx restore, or ocx eject strip exactly the lines opencodex added and restore native Codex.

Next

Continue to the Quickstart to configure your first provider, or read How It Works for the architecture.