opencodex-connect

🔗 Connect Codex CLI, App, and IDE to a remote OpenCodex server

opencodex-connect configures a local Codex installation to use an existing remote OpenCodex server. It does not install, run, patch, or otherwise manage the server.

It safely updates the Codex home, keeps resumable session history visible after the provider changes, and can restore the original native Codex configuration later.

Unofficial companion tool. Not affiliated with the OpenCodex project.

What it does

• Verifies the remote OpenCodex server and admission token.
• Adds an authenticated opencodex provider to Codex config.toml.
• Migrates resumable Codex session metadata to the new provider.
• Restores the original configuration and history metadata on request.
• Leaves OpenCodex installation and deployment entirely to the server operator.

Requirements

• Node.js 24.x or 26.x and newer (Node 25 is not supported)
• Codex CLI, App, or IDE extension
• An OpenCodex base URL exposing /healthz, /v1/models, and /v1/responses
• The server's x-opencodex-api-key admission token

Install

npm install --global opencodex-connect

You can also run setup without installing the package:

npx opencodex-connect setup https://opencodex.example.com --token YOUR_TOKEN

Usage

ocx-connect setup https://opencodex.example.com --token YOUR_TOKEN
ocx-connect status
ocx-connect sync
ocx-connect restore

Without --token, interactive setup prompts for it. The token is stored directly in config.toml; no .env, shell profile, system environment, catalog sidecar, or local models_cache.json management is involved.

Setup injects this shape while preserving all unrelated TOML bytes:

model_provider = "opencodex"

[model_providers.opencodex]
name = "OpenCodex Proxy"
base_url = "https://opencodex.example.com/v1"
wire_api = "responses"
requires_openai_auth = true
http_headers = { "x-opencodex-api-key" = "YOUR_TOKEN" }

Codex obtains the model picker data from the server's /v1/models endpoint and maintains its own cache. opencodex-connect does not download or modify a model catalog.

Session history

Changing model_provider changes which threads Codex lists and resumes. Setup and sync therefore migrate resumable openai threads to opencodex in both:

• $CODEX_HOME/state_5.sqlite
• rollout JSONL session_meta records

The original provider, source, and user-event fields are recorded in a private manifest inside $CODEX_HOME. Restore replays that manifest before removing the provider config. If Codex holds the SQLite writer lock, the command fails with instructions to close the Codex App or IDE and retry. It never switches routing back while history is still tagged for OpenCodex.

Commands

• setup <url> — probe the server, inject the provider, and migrate history
• sync — probe the configured server and retry pending history migration
• status — verify provider, token, server reachability, and migration state
• restore — restore native routing and original history tags

Use --codex-home <path> to override Codex home detection. Cleartext HTTP to a remote host is refused unless --insecure is explicitly supplied; loopback HTTP is allowed.

--print-only redacts the token and does not mutate configuration or history.