codex-proxy: Instructions file for Codex

Codex Proxy Context

Overview

The codex-proxy is a Python-based intermediary service for the Codex system, designed to handle API orchestration and environment-specific logic. It is container-native and relies on Docker for consistent execution.

Infrastructure: Docker

• Container Name: codex-proxy
• Port: 8765
• Mounts:
  • ${HOME}/.gemini is mounted to /home/appuser/.gemini for credential access.
  • ./src is mounted to /app/src to enable hot-reloading during development.
• Commands: Use docker-compose for direct lifecycle management if scripts are not used.

Control Script (/scripts)

The project uses a unified control script for all operations. Execute from the codex-proxy/ root directory.

./scripts/control.sh <command> [options]

Commands:

• start - Start the proxy container in detached mode
• stop - Stop and remove the proxy container
• logs - Follow the logs of the proxy container
• test - Run the pytest test suite
• run [-p|--profile <name>] -- "prompt" - Rebuild container and run codex command through proxy

Development Patterns

1. Credentials: Ensure your host machine has valid Gemini credentials at ~/.gemini.
2. Iteration: Use control.sh run to quickly test end-to-end changes.
3. Verification: Always run control.sh test after modifications to ensure that chaining and proxy logic are still functional.

Examples:

# Start the proxy
./scripts/control.sh start

# Run a test command
./scripts/control.sh run -- "hello world"

# Run with specific profile
./scripts/control.sh run -p glm -- "test prompt"

# Check logs
./scripts/control.sh logs

# Run tests
./scripts/control.sh test

# Stop the proxy
./scripts/control.sh stop

Engineering Mandate: Deep API Parity

The primary goal of codex-proxy is to ensure seamless compatibility between multiple AI providers (Gemini, Z.AI) and the OpenAI Responses API protocol used by the Codex ecosystem. The proxy normalizes different wire formats to a unified internal OpenAI-like structure.