OpenAI-compatible proxy for using your ChatGPT Plus/Pro subscription in Cursor. OAuth 2.0 + PKCE against auth.openai.com, forwarding to chatgpt.com/backend-api/codex.
Not affiliated with OpenAI. The backend may change at any time.
git clone https://github.com/EvickaStudio/codex-proxy && cd codex-proxy
uv sync
codex-proxy loginCopy .env.example to .env and set CODEX_PROXY_API_KEY (required when exposing via tunnel).
codex-proxy serve --tunnel # proxy + Cloudflare tunnel, one terminal
codex-proxy serve # proxy only (127.0.0.1:8088)
codex-proxy serve --session-log logs/sessions
codex-proxy tunnel # tunnel only (separate terminal)
codex-proxy login / logout / statusCursor: this proxy is tuned for Cursor's OpenAI-compatible custom base URL flow. Paste the printed Cursor base URL into Settings → Models → Override OpenAI Base URL. Use CODEX_PROXY_API_KEY as the API key. Requires cloudflared on PATH (for Windows: winget install Cloudflare.cloudflared).
Use gpt-6(can be set to something else via .env) as a custom Model in Cursor instead of GPT-5.5 native from Cursor Model selection. Cursor may send Responses API-shaped requests for gpt-5.5 through its OpenAI-compatible Chat Completions flow, which can surface as a misleading rate-limit error. The proxy exposes gpt-6 as an alias route for that backend compatibility path. If the issue persists, use gpt-5.4 instead.
The proxy also preserves conversation/session IDs as prompt_cache_key and continuation headers so older context can be reused instead of being treated as an entirely new request. This is important for longer plan-mode sessions because cached input tokens can receive the upstream cache discount/ sub rate limit doesnt vanish.
Reasoning is requested from the Codex backend and captured in session logs. The proxy forwards Cursor's reasoning object when Cursor sends a Responses-shaped body; for classic Chat Completions requests it maps reasoning_effort to reasoning.effort and defaults GPT-5 models to medium with summary: auto. Cursor's custom base URL / BYOK flow does not render these reasoning summaries in the UI, but they are still present in CODEX_PROXY_SESSION_LOG files under records[*].upstream_events[*] as response.reasoning_summary_text.delta events. Encrypted reasoning blobs are also requested via include: ["reasoning.encrypted_content"].
Session logs can be converted into JSONL examples for fine-tuning or distillation. The exporter reconstructs the assistant response from streamed Chat Completions chunks, attaches readable reasoning summaries when present, keeps tool calls/tool responses, and can render each example through a chat template.
python scripts/export_session_finetune.py logs/sessions/<session-id>.json \
--template assets/chat_template.jinja \
--out logs/finetune/<session-id>.jsonlEach JSONL row contains messages, tools, reasoning_summary, and, when --template is used, rendered text. Use --no-reasoning to omit reasoning summaries from assistant messages.
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/chat/completions |
Chat Completions (streaming + sync) |
| POST | /v1/responses |
Responses API passthrough |
| GET | /v1/models |
Model list |
| GET | /healthz |
Health check |
Set in .env (loaded automatically). See .env.example for all options.
| Variable | Default | Notes |
|---|---|---|
CODEX_PROXY_API_KEY |
unset | Clients must send as Bearer. Unset = open access. |
CODEX_PROXY_HOME |
~/.codex-proxy |
Where auth.json is stored. |
CODEX_PROXY_BASE_URL |
https://chatgpt.com/backend-api/codex |
Backend override. |
CODEX_PROXY_MODELS |
built-in list | Comma-separated, reported by /v1/models. |
CODEX_PROXY_MODEL_ALIASES |
gpt-6:gpt-5.5 |
Comma-separated alias:upstream routes. Aliases are also reported by /v1/models. |
CODEX_PROXY_DEFAULT_INSTRUCTIONS |
You are a helpful assistant. |
Fallback system prompt. |
CODEX_PROXY_SESSION_LOG |
unset | Write one JSON file per session for fine-tuning or distillation. Contains prompts/tools. |
Port 1455 in use — stop the conflicting process (Codex CLI?). The OAuth redirect port is fixed.
401 from backend — codex-proxy logout && codex-proxy login.
403 / model not supported — subscription tier doesn't include that model; try gpt-5.4-mini.
Streaming hangs — SSE blocked by a corporate proxy; set CODEX_PROXY_BASE_URL to an alternative.
Cursor BYOK + gpt-5.5 shows "rate limit exceeded" — known Cursor regression (May 2026); proxy handles it automatically, but fall back to gpt-5.4 if it persists.
Apache-2.0