Skip to content
LUNAROUTEDocs

Codex

Codex CLI takes its provider configuration as command-line overrides (-c key=value), so LunaRoute can be attached two ways: for a single session with no files touched, or as a permanent named profile that keeps your ~/.codex/config.toml untouched.

1. Try it for one session

Section titled “1. Try it for one session”

Install the CLI (CLI setup) and sign in once:

Terminal window
npm install -g @lunaroute/cli
lunaroute login
lunaroute run codex

run launches Codex with LunaRoute as the provider for that session only. It passes the provider on the command line — -c model_provider="lunaroute", -c model_providers.lunaroute={base_url, model_catalog_url, env_key, wire_api="responses"}, -c model=…, -c features.api_key_model_discovery=true, and an optional -c model_context_window=… from the catalog — puts the key in the child process environment, and writes no file. Quit, and your normal Codex setup is what you get next time.

  • lunaroute run codex --model <id> starts on a specific model (default: the first chat model in your catalog).
  • Everything after -- goes to Codex: lunaroute run codex -- --resume.
  • It uses your stored login — run lunaroute login first (an env LUNAROUTE_API_KEY is not enough for run; it errors with Not logged in).
  • Codex must already be installed; run only launches it.

2. Set it up permanently

Section titled “2. Set it up permanently”
Terminal window
lunaroute setup codex
codex --profile lunaroute

setup writes one file: $CODEX_HOME/lunaroute.config.toml (default ~/.codex/lunaroute.config.toml). It holds the named provider, the model, and Codex’s model-discovery settings:

model_provider = "lunaroute"
model = "…"                      # from your catalog at setup time


[model_providers.lunaroute]
base_url = "https://gw.lunaroute.com/v1"
model_catalog_url = "https://gw.lunaroute.com/v1/codex/models"
env_key = "LUNAROUTE_API_KEY"
wire_api = "responses"


[features]
api_key_model_discovery = true

model_catalog_url is what fills Codex’s /model picker with every LunaRoute chat model: Codex decodes its own catalog shape from that path, so discovery works without pinning a single model. The api_key_model_discovery flag enables it on older Codex builds; on current Codex it is already on.

Two things follow from that shape:

  • The key is not in the file. env_key = "LUNAROUTE_API_KEY" means Codex reads the credential from the environment, so export it: export LUNAROUTE_API_KEY=lr_… on Linux/macOS, or on Windows (PowerShell, 5.1-safe) the persistent user variable the CLI prints — then open a new window, because user-scope variables do not reach shells that are already running.
  • ~/.codex/config.toml is untouched. The profile is a separate file selected with --profile, so your existing Codex configuration stays exactly as it was.

Picking a model: run /model in a session (the picker lists the catalog), pass codex --profile lunaroute --model <id> for one run, or edit model = "…" in the profile file. Model ids come from the live catalog — never hardcode a list.

3. Where it wrote, and how to undo

Section titled “3. Where it wrote, and how to undo”
  • lunaroute run codex wrote nothing — exit and you are done.
  • lunaroute setup codex wrote exactly one Codex file: $CODEX_HOME/lunaroute.config.toml. Delete it (and drop the LUNAROUTE_API_KEY export if you added it) and Codex is back to its previous behaviour; your config.toml never changed.
  • The CLI keeps its own credential separately, outside Codex: lunaroute login (or setup --key) stores your lr_… key in ~/.config/lunaroute/. If you want that gone too, run lunaroute logout. Nothing else on the machine was written.
  • There is no --remove for this harness — lunaroute setup codex --remove reports that only claude-desktop has a reverse. Removing one file by hand is the whole undo.

4. Verify without starting Codex

Section titled “4. Verify without starting Codex”
Terminal window
curl https://gw.lunaroute.com/v1/models \
  -H "Authorization: Bearer $LUNAROUTE_API_KEY"

On Windows (PowerShell, 5.1-safe) — never the bare name curl, which PowerShell 5.1 aliases to Invoke-WebRequest (curl.exe is fine and ships with Windows 10 1803+):

Terminal window
Invoke-RestMethod -Uri https://gw.lunaroute.com/v1/models `
  -Headers @{ Authorization = "Bearer $env:LUNAROUTE_API_KEY" }

Codex uses the Responses API (wire_api = "responses"), which LunaRoute serves at /v1/responses; the catalog request above is the quickest proof that the key and the URL are right before you start a session.

Platforms and WSL

Section titled “Platforms and WSL”

The CLI, run and setup codex are verified on Linux; the Windows forms above are the ones the CLI itself prints. WSL is a separate environment — Windows user variables do not cross into a distribution (WSLENV is the bridge), the npm/Node install is separate per side, and a lunaroute login on one side is invisible on the other. Install, log in and run again inside the distribution; CLI setup covers the details, including the npx failure modes on Windows.

Section titled “Related”
  • CLI — install, run, setup, and the Windows/WSL notes.
  • Harness setup — the other harnesses.
  • Responses API — the endpoint wire_api = "responses" targets.
LunaRoute documentation