# codex-proxy

**Repository Path**: sqm2050/codex-proxy

## Basic Information

- **Project Name**: codex-proxy
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# codex-cursor

Local OpenAI-compatible HTTP proxy that lets Cursor, or anything else that
speaks the OpenAI Chat Completions API, consume your **ChatGPT/Codex
subscription** instead of a metered OpenAI API key.

This Go implementation reuses the access tokens that the `codex` CLI stores in
`~/.codex/auth.json` and translates Cursor's `/v1/chat/completions` traffic to
the ChatGPT backend's Responses API.

> Calls a private ChatGPT/Codex backend with the same credentials and limits as
> the `codex` CLI. Personal use only.

## Prerequisites

1. Go 1.22 or newer.
2. The `codex` CLI installed and signed in (`codex login`), so
   `~/.codex/auth.json` exists.

## Build

```bash
go build -o codex-cursor ./cmd/codex-cursor
```

## Run It

```bash
./codex-cursor --api-key "$(openssl rand -hex 16)"
```

Or use the Makefile. `run-proxy` defaults to an upstream proxy at
`http://127.0.0.1:7990`:

```bash
make
make help
NO_COLOR=1 make help
make run-proxy API_KEY="$(openssl rand -hex 16)"
```

Flags / env vars:

| Flag                     | Env var                       | Default               |
| ------------------------ | ----------------------------- | --------------------- |
| `--host <addr>`          | `CODEX_SUB_HOST`              | `127.0.0.1`           |
| `--port <n>`             | `CODEX_SUB_PORT`              | `4141`                |
| `--api-key <secret>`     | `CODEX_SUB_API_KEY`           | _no auth required_    |
| `--auth-path <path>`     | `CODEX_SUB_AUTH_PATH`         | `~/.codex/auth.json`  |
| `--reasoning-effort lvl` | `CODEX_SUB_REASONING_EFFORT`  | `xhigh` (`minimal`, `low`, `medium`, `high`, `xhigh`) |
| `--quiet` / `--verbose` / `--log-level lvl` | `CODEX_SUB_LOG_LEVEL` | `info` (`quiet`, `info`, `verbose`) |

Always set `--api-key` when exposing the proxy via a tunnel. Without it, the
public URL can consume your Codex subscription.

## Expose It To Cursor

Cursor's chat runs on Cursor's cloud backend, which calls your custom base URL.
It refuses private addresses, so `http://127.0.0.1:4141/v1` will fail with
`Access to private networks is forbidden`.

Use a Cloudflare quick tunnel:

```bash
brew install cloudflared

# terminal A:
./codex-cursor --api-key "$(openssl rand -hex 16)"

# terminal B:
cloudflared tunnel --url http://127.0.0.1:4141
```

`cloudflared` prints a `https://random-words.trycloudflare.com` URL.

## Point Cursor At It

1. Cursor -> Settings -> Models -> "OpenAI API Key" panel.
2. Toggle **Override OpenAI Base URL** and set:
   - **Base URL:** `https://<your-tunnel>.trycloudflare.com/v1`
   - **API Key:** the hex string you passed to `--api-key`.
3. Click **Verify**.
4. In the model picker, add a custom model. Working slugs:
   `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex`,
   `gpt-5.3-codex-spark`. The exact list is returned by `GET /v1/models`.

## Endpoints

- `GET /health` and `GET /v1/health`
- `GET /v1/models`
- `POST /v1/chat/completions`
- `POST /v1/responses`

`/v1/chat/completions` accepts either OpenAI Responses-API-shaped request
bodies with an `input` array or standard Chat Completions request bodies with a
`messages` array. Chat Completions requests are converted to a sanitized
Responses request upstream, then upstream SSE text and tool-call events are
translated back into Chat Completions chunks for Cursor.

`/v1/responses` accepts OpenAI Responses API request bodies directly. For
`stream: true`, it forwards upstream Responses SSE events back as Responses SSE
events. For non-streaming calls, it returns the final completed response object.

## Caveats

- The proxy issues stateless single-turn calls; Cursor's full history is sent
  every time.
- Upstream prompt-cache/thread grouping follows the downstream session when the
  request includes `prompt_cache_key`, common session/thread headers, or
  `session_id`/`conversation_id`/`thread_id` metadata. Otherwise, it falls back
  to a process-local proxy session.
- If `codex logout` invalidates your refresh token, the proxy fails with
  `refresh_token_expired` until you `codex login` again.
- The old TypeScript/Bun implementation is still present in `src/` as a
  reference, but the maintained entrypoint is `cmd/codex-cursor`.