codexpass

Use your Codex login anywhere. The Codex CLI stores a working OpenAI credential on your machine after you log in. codexpass reads that credential and lets your other tools use it — print shell export lines, grab the raw token, or run a local OpenAI-compatible server for editors, SDKs, and scripts. No separate API key to set up.

How it works

After codex login, the Codex CLI saves a credential in ~/.codex/auth.json. codexpass reads that file. If the token has expired, it refreshes it with the stored refresh token and writes the new token back safely with 0600 file permissions. Then it hands you the credential in the shape you need.

Install

Download a prebuilt binary for Linux, macOS, or Windows from the latest release:

Or install with Go:

go install github.com/hdprajwal/codexpass@latest

Or build from source:

git clone https://github.com/hdprajwal/codexpass
cd codexpass
make build   # produces ./codexpass

Usage

Load the credential into your current shell session:

eval "$(codexpass export)"

Now OPENAI_API_KEY (and, in ChatGPT mode, OPENAI_BASE_URL) are set for every tool you run in that session.

# bare token for a script
KEY=$(codexpass token)

# key only, without the base-URL override
eval "$(codexpass export --no-base-url)"

# check your local Codex login
codexpass doctor
codexpass doctor --json
codexpass doctor --live   # also checks the upstream models endpoint

Local OpenAI-compatible proxy

codexpass serve runs a local OpenAI-compatible server and forwards requests to the Codex backend. It supports /v1/chat/completions, /v1/responses, /v1/models, /healthz, and optional /metrics.

codexpass serve --port 8080
codexpass serve --port 8080 --token local-secret
codexpass serve --metrics --log-format json \
  --stats-path ~/.cache/codexpass/usage.jsonl

Point any OpenAI-compatible editor or SDK at http://localhost:8080/v1. When the client asks for an API key, enter the --token value, or any placeholder if you did not set one. The real Codex credential stays inside the proxy.

A few caveats. Requests count against your ChatGPT subscription quota. The Codex backend does not serve embeddings, images, or audio; those endpoints return 501 unless you configure a fallback backend. The proxy is meant for personal, local use — keep it bound to loopback (the default) and do not expose it to others.

Zed

In Zed settings.json:

{
  "language_models": {
    "openai_compatible": {
      "Codex": {
        "api_url": "http://localhost:8080/v1",
        "available_models": [
          { "name": "gpt-5.6", "display_name": "GPT-5.6 Sol (Codex)", "max_tokens": 272000 },
          { "name": "gpt-5.6-terra", "display_name": "GPT-5.6 Terra (Codex)", "max_tokens": 272000 },
          { "name": "gpt-5.6-luna", "display_name": "GPT-5.6 Luna (Codex)", "max_tokens": 272000 }
        ]
      }
    }
  }
}

Models

GPT-5.6 has three tiers: gpt-5.6-sol for frontier capability, gpt-5.6-terra for a balance of intelligence and cost, and gpt-5.6-luna for efficient high-volume work. When Sol is available, codexpass also exposes the official gpt-5.6 alias. List what your credential can reach:

codexpass models list

You can also define model aliases, so a client asks for a local name while codexpass sends the real Codex model name upstream:

{
  "models": {
    "cache_ttl_seconds": 300,
    "aliases": { "gpt-codex": "gpt-5.6-sol" }
  }
}

Client tokens and policy

For one local secret, use --token. For multiple local clients, generate a config snippet with codexpass token create NAME. Client policy can restrict endpoints, models, request size, fallback use, and per-minute rate limits. /healthz stays public; when any token or client policy is configured, all other endpoints require a matching bearer token.

Observability

Verbose logging records request metadata only — route, status, latency, client. Never prompts, completions, tool arguments, or any token or key. Enable Prometheus-style metrics with --metrics, or write redacted usage events and summarize them later:

codexpass serve --stats-path ~/.cache/codexpass/usage.jsonl
codexpass stats --path ~/.cache/codexpass/usage.jsonl

Background service

Install codexpass as a user-level background service (systemd user unit on Linux, launchd plist on macOS). Installation refuses non-loopback hosts unless you pass --allow-network.

codexpass service install --config ~/.config/codexpass/config.json
codexpass service status
codexpass service uninstall

What kind of key you get

• chatgpt mode — you logged in with a ChatGPT subscription. The borrowed value is a ChatGPT OAuth access token, not a normal sk-... key. It only works against the Codex backend, so codexpass export also sets OPENAI_BASE_URL=https://chatgpt.com/backend-api/codex, and you use Codex model names (gpt-5.x).
• apikey mode — you logged in with an API key. The borrowed value is a real OpenAI API key that works against api.openai.com. codexpass exports just OPENAI_API_KEY and leaves the base URL alone.

Commands

Configuration

CODEX_HOME overrides the Codex home directory (default ~/.codex). CODEXPASS_CONFIG overrides the codexpass config path (default ~/.config/codexpass/config.json). If the file does not exist, codexpass uses its defaults; codexpass serve flags override config-file server values.

{
  "server": { "host": "127.0.0.1", "port": 8080, "metrics": true },
  "models": {
    "aliases": { "gpt-codex": "gpt-5.6-sol" }
  },
  "fallback": {
    "enabled": false,
    "base_url": "https://api.openai.com/v1",
    "api_key_env": "OPENAI_API_KEY"
  }
}

Credits

The credential-borrowing and token-refresh logic is ported from Simon Willison's llm-openai-via-codex.