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.

The default local route is plug-and-play with an existing ChatGPT/Codex login. It does not require an OpenAI API key or any other provider API key.

Prerequisites

Requirement	Why
Node ≥ 18	ocx runs on the Bun runtime, but the runtime is bundled automatically on npm 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 ChatGPT/Codex login	The default built-in openai route forwards the account session created by codex login or the Codex app. This is not an API key.
An upstream provider account or API key (optional)	Needed only when you deliberately add Anthropic, xAI, Kimi, Ollama Cloud, OpenRouter, another hosted provider, or a custom authenticated endpoint.

Install

npm install -g @bitkyc08/opencodex

On Windows, the repository installer scripts/install.ps1 obtains the exact npm global prefix from npm.cmd prefix -g, adds that directory to the current user’s PATH idempotently, and refreshes the current PowerShell process when possible. It never changes the machine PATH or requires elevation. If the current shell cannot be refreshed, the installer says to open a new PowerShell window and rerun ocx --version.

If you are installing from a package download rather than a repository checkout, use the manual check below instead.

If you install manually and ocx is not recognized, inspect the prefix and shim first. On Windows, use the prefix itself as the global npm bin directory — do not append \bin:

$npmGlobalBin = (& npm.cmd prefix -g).Trim()
$npmGlobalBin
Test-Path -LiteralPath (Join-Path $npmGlobalBin "ocx.cmd")
$env:Path -split ";" | Where-Object { $_.Trim().TrimEnd("\") -ieq $npmGlobalBin.Trim().TrimEnd("\") }
Get-Command ocx.cmd -ErrorAction SilentlyContinue

If the shim exists but the PATH query is empty, rerun scripts/install.ps1. It adds the prefix to the current user’s PATH idempotently, preserves unrelated entries, avoids the machine PATH, and refreshes the current PowerShell process when possible. If the process cannot be refreshed, it reports that a new PowerShell window is required. Do not use setx PATH, which can rewrite or truncate unrelated PATH entries.

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1

Open a new PowerShell window if the installer explicitly tells you to do so.

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. Reinstall allowing bun’s script — and always include the package name (npm’s abbreviated suggestion omits it, which would reinstall the current directory instead):

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

On Windows, the repository’s PowerShell installer also repairs the current user’s npm global PATH entry when npm installs successfully but ocx is not yet resolvable. It updates the running PowerShell process and the user’s environment only, preserves unrelated entries, avoids machine-wide mutation or setx, and verifies ocx.cmd/ocx with help before reporting success:

From a checkout of the repository, run the script from its root:

.\scripts\install.ps1

If npm reports an empty or invalid prefix, or Windows refuses the user PATH write, the installer fails with that reason instead of claiming that ocx is ready. A new PowerShell opened later will inherit the persisted user PATH.

Verify both command aliases are on your PATH:

ocx --version
opencodex --version

Start the default local route immediately:

ocx start

Keep that terminal running, then use ocx codex from another terminal. If Codex has not been signed in before, run codex login once. ocx gui opens the dashboard on the live proxy port and starts the proxy automatically when needed.

Local startup does not need an API key

An upstream provider API key pays for/authenticates an optional provider. An OpenCodex admission key protects /v1/* only when you expose the proxy beyond loopback. Neither is required for the default localhost + ChatGPT/Codex-login path. See the Quickstart credential table.

Get-Command ocx.cmd
Get-Command ocx

The installer does not require administrator privileges. If the npm global prefix itself is protected or npm was installed for all users, use a user-owned Node/npm installation rather than granting the installer machine-wide access.

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 automatically selected fallback port.
$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 run the keyless local default, or read How It Works for the architecture.