Codex-Wrapper - OpenAI-Compatible API Wrapper for Codex CLI

Codex-Wrapper is a “FastAPI server that wraps Codex CLI behind a minimal OpenAI-compatible API.” It exposes /v1/chat/completions and /v1/models, supports SSE streaming, and is MIT licensed. The appeal is obvious: point any OpenAI-compatible client at it and you are driving Codex through your existing subscription.

Two things about it need stating before anything else — one a date, one a default.

The date

The most recent commit on the default branch is from 12 December 2025. At the time of writing that is roughly ten months without a change.

For most software, ten months is unremarkable. For this software it is the central risk, because of what it is: a wrapper that shells out to the codex CLI and parses what comes back. Its correctness depends entirely on the CLI’s flags, output format and authentication behaviour staying where they were — and the Codex CLI is actively developed, with its own release cadence.

A subprocess wrapper is the most fragile possible integration shape. The project is honest about the coupling; the README names submodules/codex pointing at openai/codex as a reference submodule, so the dependency is explicit rather than hidden. But a reference pinned in December 2025 tells you which version it was written against, not which version you have installed.

The practical implication: before investing any time in this, install it and make one request. If the CLI’s interface has moved, you will find out in two minutes rather than after building something on it. And if it works, pin your @openai/codex version, because an upgrade of the CLI is the thing most likely to break the wrapper.

The default

From the environment documentation:

“PROXY_API_KEY: Bearer token required by this proxy (optional if you run without auth).”

And from the README’s own run instruction:

uvicorn app.main:app --host 0.0.0.0 --port 8000

Read those together. 0.0.0.0 binds to every interface. PROXY_API_KEY is optional. Follow the quick start on a machine with a public IP and no firewall, and you have published an unauthenticated endpoint that executes Codex using your credentials — stored, as the README explains, in ~/.codex/auth.json after codex login.

That is not a vulnerability in the project; it is a documented configuration with an obvious wrong setting. It is worth spelling out because the sequence of instructions makes it easy to arrive at by accident: you log in, you start the server on all interfaces because that is the command in the README, and the auth token is a separate optional variable further down in a different document.

So: set PROXY_API_KEY, and bind to localhost unless you have deliberately decided otherwise. The Docker path is better behaved here — the README notes the containerised server “binds to localhost:8000 by default.”

One design detail that is genuinely good

Also from the configuration documentation:

“Any provider with a non-local base_url (not localhost/127.0.0.1/[::1]/unix) is rejected with HTTP 400.”

That is an egress guard. A request cannot talk the wrapper into forwarding to an arbitrary remote provider — non-local base URLs are refused outright, with an explicit flag controlling the behaviour. For a proxy that holds your credentials, refusing to be pointed at someone else’s endpoint is exactly the right restriction, and it is the kind of thing that only gets implemented by someone who thought about the abuse case.

It is a small signal that the security thinking here was real, which makes the optional-auth default more surprising rather than less.

How authentication actually works

Worth understanding because it is the whole point of the project:

“Authentication happens in the Codex CLI, not in this API wrapper.”

You run codex login as the same OS user that runs the server, complete an OAuth sign-in, and credentials land in $CODEX_HOME/auth.json. The wrapper never sees your password; it inherits a logged-in CLI.

For headless machines the README documents both routes — an SSH port-forward (ssh -L 1455:localhost:1455) so the browser flow can complete, or logging in locally and copying auth.json across. The Docker setup bind-mounts $HOME/.codex and uses HOST_UID/HOST_GID to match the host user so the container can read it.

An API-key mode exists as the alternative, where the CLI reads OPENAI_API_KEY — metered, and consumed by Codex rather than by the proxy.

The subscription-reuse model is the same instinct behind ductor and Happy: wrap the official tooling instead of reselling an API. It is the right approach, and the thing all three share is that the thin wrapper must keep pace with the tool it wraps.

Documentation, in two languages and one direction

The project maintains English and Japanese documentation, with a stated sync policy in CONTRIBUTING.md. Two files are Japanese-only by design: the implementation plan and the Responses API plan.

That is fine for using it and relevant if you want to contribute or to understand where it was heading, since the roadmap documents are the ones not translated.

Who should try this

Someone who wants Codex available to a tool that only speaks the OpenAI API — a local client, a script, an editor plugin, an evaluation harness — and who is running it on their own machine for their own use.

It is not infrastructure. A ten-month-old subprocess wrapper around a moving CLI, with optional authentication, is a personal convenience rather than something to put in front of a team.

The finding: test it before you plan around it, because the last commit predates ten months of Codex CLI development and the integration is a subprocess parse. Then set PROXY_API_KEY and bind to localhost — the README’s quick start uses 0.0.0.0 and the auth token is documented as optional, which is a combination that publishes your logged-in Codex session to anyone who can reach the port.