codex

OpenAI Codex CLI

The new agentic terminal tool from OpenAI (Rust, npm install -g @openai/codex). FreeRide makes it work without a paid OpenAI plan — the gateway translates Codex's Responses-API wire protocol to free upstream providers.

TL;DR

curl -sSL https://api.free-ride.xyz/install.sh | sh
npm install -g @openai/codex
freeride run codex

You're in a Codex session, routed through free providers. No OPENAI_API_KEY or CODEX_API_KEY needed. You don't have to sign in to OpenAI.

---

How it works

Codex speaks only the OpenAI Responses API (POST /v1/responses) — wire_api = "chat" is explicitly rejected on its side. The gateway hosts a Responses-shape endpoint that:

1. Accepts the typed-item input array (messages, function_call, function_call_output, reasoning items)
2. Unwraps the flat tools[] (Responses uses {type, name, parameters}, Chat Completions uses {type, function: {…}})
3. Translates to OpenAI Chat Completions
4. Routes through the same failover machinery /v1/messages and /v1/chat/completions use
5. Translates the response back to Responses shape (with output[] array of typed items, status field, no choices)
6. Re-frames streaming chunks into Responses SSE event protocol with explicit framing events (response.output_item.added → response.content_part.added → response.output_text.delta → … → response.completed)

The Codex CLI parses every event natively; from its perspective the gateway is OpenAI.

Model field on the request (gpt-5-codex, gpt-5, etc.) is rewritten to auto before dispatch — we don't host OpenAI's proprietary models, so the smart-router picks a free model. The originally-requested id is echoed back on the response so the CLI's UI stays coherent.

What the wrapper does

freeride run codex does three things before invoking codex:

1. Injects -c openai_base_url=http://localhost:11343/v1 into argv right after the codex binary name. Codex reads its base URL from ~/.codex/config.toml (not an env var); the -c flag is the per-invocation override that doesn't mutate the user's config file.
2. Sets CODEX_API_KEY=sk-freeride-no-auth (a sentinel) if the parent env has none. Codex's auth gate refuses to make any HTTP request without this — the sentinel satisfies the local check; the gateway recognizes it via has_inbound_auth() and demotes it to "no auth" for routing decisions.
3. Writes ~/.codex/auth.json with {"OPENAI_API_KEY": "sk-freeride-no-auth"} on first run if the file doesn't exist, so Codex's "configure authentication" picker doesn't fire.