Installation

opencodex ships as a single CLI, ocx. It runs as a small local HTTP server (built on Bun) and never sends your traffic anywhere except the provider you configure.

Prerequisites

Requirement	Why
Bun ≥ 1.1 (recommended) or Node ≥ 20	ocx runs on the Bun runtime; the service runner invokes bun.
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

# With npm (recommended)
npm install -g @bitkyc08/opencodex

# With Bun
bun install -g @bitkyc08/opencodex

Verify the binary is on your PATH:

ocx --help

Run from source

To hack on opencodex itself:

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

The web dashboard lives in gui/ and runs separately:

cd gui && bun install && bun dev

What gets created

Path	Purpose
~/.opencodex/config.json	Your providers, default provider, port, and options.
~/.opencodex/ocx.pid	PID of the running proxy (single-instance guard).
~/.opencodex/auth.json	Stored OAuth credentials (when you ocx login).
~/.opencodex/catalog-backup.json	Pristine Codex model catalog, backed up before any edit.
$CODEX_HOME/config.toml	opencodex appends a [model_providers.opencodex] table here on ocx init (defaults to ~/.codex/config.toml).

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.