Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.codezero.io/llms.txt

Use this file to discover all available pages before exploring further.

Cordon integrates with OpenAI Codex so your AI agent can make authenticated API calls without holding real credentials.
Current limitations: Cordon injects API keys for Codex, not ChatGPT/OAuth session credentials. Codex works best with Cordon in non-sandboxed sessions; --dangerously-bypass-approvals-and-sandbox is inherently riskier because model-generated commands run without Codex’s normal sandbox boundary.
To run Codex outside its command sandbox, launch it with: 
codex --dangerously-bypass-approvals-and-sandbox
For non-interactive runs, use the same flag with exec: 
codex exec --dangerously-bypass-approvals-and-sandbox "your prompt here"

​
Scope

Codex setup defaults to project scope: cordon.toml lives in $CWD, proxy env vars are written to $CWD/.codex/.env, and a Codex config block is written to $CWD/.codex/config.toml. For full startup-time coverage, Codex must load the project-local .env, so point CODEX_HOME at the project directory at runtime: 
export CODEX_HOME="$PWD/.codex"
codex --dangerously-bypass-approvals-and-sandbox
Add this export to your shell profile or a project .envrc (e.g. direnv) to automate it. To use a single cordon config across all projects, override to user scope: 
cordon setup codex --scope user
User scope writes env vars to $CODEX_HOME/.env (or $HOME/.codex/.env if CODEX_HOME is not set), writes shell command env policy to $CODEX_HOME/config.toml, and stores config at $XDG_CONFIG_HOME/cordon/cordon.toml. See Scopes for path details and trade-offs.

​
Automated setup

The fastest way to get started: 
cordon setup codex
This:
  1. Generates CA certificates (if not already present)
  2. Creates a scaffold cordon.toml
  3. Writes the standard proxy and CA env vars from cordon env to Codex’s .env and [shell_environment_policy.set] in Codex’s config.toml
Your existing .env is backed up to .env.cordon.bak before any changes are made. To run cordon as a background service, run cordon service install after setup (add --scope user if you set up Codex with --scope user).

​
Remove the setup

cordon integration disable codex

​
API key setup

Codex needs to be configured to use API key authentication (rather than OAuth) so traffic routes through cordon. Run codex login, select the API key option (option 3), and enter a dummy value: 
codex login
# Select: API key
# Enter: dummy-replaced-by-cordon
Cordon strips this dummy key and injects the real one from your secret store at the network layer.

​
Adding routes

The cordon route, cordon start, and cordon service commands below default to project scope. If you set up Codex with --scope user, append --scope user to each of these commands so they target ~/.config/cordon/cordon.toml instead of ./cordon.toml.
After setup, add a route for OpenAI: 
cordon route add --name openai --host api.openai.com \
  --auth-type header --header-name Authorization --scheme Bearer --source keyring --account openai
If you chose keyring as the secret source, store the secret: 
cordon secret set openai
See Routes for provider auth types, dummy-key behavior, and route change restart guidance.

​
Manual setup

Prefer cordon setup codex for Codex configuration. It writes the proxy and CA settings to the right files, updates the shell environment policy, and backs up existing files before changing them. If setup cannot cover your environment, copy the values from cordon env to the appropriate Codex .env file. 
HTTPS_PROXY="http://127.0.0.1:<PORT>"
SSL_CERT_FILE="/path/to/combined-ca.pem"
Codex filters out CODEX_* prefixed variables from its .env file as a security measure, so you must use SSL_CERT_FILE instead of CODEX_CA_CERTIFICATE. If you need to set CODEX_CA_CERTIFICATE, it must be in your shell environment (e.g., ~/.zshrc), not in the .env file.
The CODEX_HOME env var can override the default ~/.codex/ path if Codex is installed in a non-standard location. For shell commands and tools launched by Codex, set the same values in config.toml: 
[shell_environment_policy.set]
HTTPS_PROXY = "http://127.0.0.1:<PORT>"
SSL_CERT_FILE = "/path/to/combined-ca.pem"
Project-local .codex/config.toml can help trusted projects without setting CODEX_HOME, but .codex/.env is still the full startup-time path for Codex’s own network traffic. See Any tool (generic) for the full env-var contract.

​
How it works

Codex is a Rust CLI that uses reqwest for HTTP and rustls for TLS. It loads $CODEX_HOME/.env via dotenvy at startup (before any threads are created), so proxy env vars are picked up automatically. It also applies shell_environment_policy.set from config.toml to shell commands and tools it launches later. For Cordon’s matched-route TLS behavior and certificate troubleshooting, see TLS.

​
WebSocket fallback

Codex prefers WebSocket connections (wss://) for the OpenAI realtime API. WebSocket connections through cordon’s MITM currently fail with a TLS handshake error — Codex gracefully detects this and falls back to HTTP/SSE for the remainder of the session. The credential injection works identically on both transports; only the connection upgrade fails. WebSocket support is tracked in a future release.

​
Workflow

Once configured, the workflow is:
  1. Start cordon: cordon start (or use the background service)
  2. Start Codex as usual
  3. When Codex makes API calls to api.openai.com, cordon transparently injects credentials
  4. Codex never sees or logs real API keys
Use cordon doctor to diagnose any setup issues. It checks config validity, cert paths, trust store status, and port availability.

​
Troubleshooting

If Codex is connecting to chatgpt.com or ab.chatgpt.com instead of api.openai.com, it’s using the OAuth path. Run codex login, select option 3 (API key), and enter a dummy value. Check cordon’s logs — you should see MITM: injecting credentials route=openai for api.openai.com requests.
Verify the active Codex .env includes the CA bundle values from cordon env, then follow TLS troubleshooting.
Verify the env vars are in the active Codex .env:
cat "$CODEX_HOME/.env"
If the file exists but Codex isn’t routing through the proxy, use the shared proxy not running checks.
Codex silently filters out all CODEX_* prefixed variables from its .env file. Use SSL_CERT_FILE instead, or set CODEX_CA_CERTIFICATE in your shell profile (~/.zshrc or ~/.bashrc).
Restart Cordon after adding or editing route definitions. See Routes: route changes and secret rotation.
  1. Verify the secret is stored: cordon secret set openai
  2. Check the route auth config — OpenAI uses type: header, header_name: Authorization, and scheme: Bearer
  3. HTTP route secrets are fetched per-request — if you changed a secret, the next request picks it up automatically