MCPInstall

codex2api-reverse-proxy

by reason-machinesAI & Agents

Codex2API is a production-ready reverse proxy that converts Codex account pools into OpenAI/Anthropic-compatible API gateways with account management, scheduling, and admin dashboard.

Installs
256
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/codex-skills --skill codex2api-reverse-proxy
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads codex2api-reverse-proxy automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Codex2API Reverse Proxy

Skill by ara.so — Codex Skills collection.

Codex2API is a Go + Gin + React production gateway that transforms a pool of Codex accounts into observable, schedulable OpenAI/Anthropic-compatible API endpoints. It manages Refresh Token/Access Token lifecycles, health scoring, dynamic concurrency, rate-limit recovery, usage tracking, and admin operations through a built-in dashboard.

What It Does

  • Unified Gateway: Exposes /v1/chat/completions, /v1/responses, /v1/messages, /v1/images/generations, /v1/images/edits, and /v1/models endpoints
  • Account Pool Management: Handles Refresh Tokens and Access Tokens with automatic health scoring and cooldown recovery
  • Dynamic Scheduling: Selects accounts based on health tier, concurrency limits, rate limits, and recent usage
  • Admin Dashboard: React/Vite UI for account import, API key management, proxy pools, image studio, prompt filtering, usage analytics
  • Flexible Storage: Production mode (PostgreSQL + Redis) or lightweight mode (SQLite + in-memory cache)

Installation

Standard Production Deployment (PostgreSQL + Redis)

git clone https://github.com/james-6-23/codex2api.git
cd codex2api
cp .env.example .env
# Edit .env with your DATABASE_* and REDIS_* settings
docker compose pull
docker compose up -d
docker compose logs -f codex2api

Lightweight SQLite Deployment

git clone https://github.com/james-6-23/codex2api.git
cd codex2api
cp .env.sqlite.example .env
# Edit .env if needed
docker compose -f docker-compose.sqlite.yml pull
docker compose -f docker-compose.sqlite.yml up -d
docker compose -f docker-compose.sqlite.yml logs -f codex2api

Local Development

cp .env.example .env
# Start PostgreSQL and Redis containers or configure local instances
cd frontend && npm ci && npm run build && cd ..
go run .

Frontend dev server:

cd frontend && npm ci && npm run dev
# Frontend runs at http://localhost:5173/admin/

Configuration

Environment Variables (.env)

Server:

CODEX_PORT=8080
ADMIN_SECRET=your-secure-admin-password
TZ=Asia/Shanghai

PostgreSQL Mode:

DATABASE_DRIVER=postgres
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=codex2api
DATABASE_PASSWORD=secure-db-password
DATABASE_NAME=codex2api
DATABASE_SSLMODE=disable

CACHE_DRIVER=redis
REDIS_ADDR=localhost:6379
REDIS_PASSWORD=secure-redis-password
REDIS_DB=0

SQLite Mode:

DATABASE_DRIVER=sqlite
DATABASE_PATH=/data/codex2api.db
CACHE_DRIVER=memory

Redis TLS (Aiven, Upstash, etc.):

# Prefer rediss:// URL format
REDIS_ADDR=rediss://default:password@host:port/0

# OR for host:port format
REDIS_ADDR=host:port
REDIS_TLS=true
REDIS_INSECURE_SKIP_VERIFY=false  # Set true only for self-signed certs
REDIS_USERNAME=default
REDIS_PASSWORD=your-password

Runtime Settings (Database)

After first startup, configure via admin dashboard at /admin/settings:

  • MaxConcurrency: Global concurrent request limit
  • GlobalRPM: Global requests per minute
  • TestModel: Model for account health checks
  • TestConcurrency: Test request concurrency
  • ProxyURL: Global proxy (e.g., http://proxy:port)
  • PgMaxConns: PostgreSQL connection pool size
  • RedisPoolSize: Redis connection pool size
  • Auto-cleanup settings for logs and usage records

API Usage

OpenAI Chat Completions

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/sashabaranov/go-openai"
)

func main() {
	config := openai.DefaultConfig(os.Getenv("CODEX2API_KEY"))
	config.BaseURL = "http://localhost:8080/v1"
	client := openai.NewClientWithConfig(config)

	resp, err := client.CreateChatCompletion(
		context.Background(),
		openai.ChatCompletionRequest{
			Model: "claude-code",
			Messages: []openai.ChatCompletionMessage{
				{
					Role:    openai.ChatMessageRoleUser,
					Content: "Explain how Codex2API account scheduling works",
				},
			},
		},
	)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Println(resp.Choices[0].Message.Content)
}

Anthropic Messages (Compatible Endpoint)

import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ.get("CODEX2API_KEY"),
    base_url="http://localhost:8080/v1"
)

message = client.messages.create(
    model="claude-code",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain dynamic concurrency in Codex2API"}
    ]
)

print(message.content[0].text)

Native Codex Responses

curl -X POST http://localhost:8080/v1/responses \
  -H "Authorization: Bearer $CODEX2API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-code",
    "messages": [
      {
        "role": "user",
        "content": "Write a hello world in Go"
      }
    ],
    "stream": false
  }'

Image Generation

curl -X POST http://localhost:8080/v1/images/generations \
  -H "Authorization: Bearer $CODEX2API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene mountain landscape at sunset",
    "model": "gemini-2.0-flash-exp-image",
    "n": 1,
    "size": "1024x1024"
  }'

Image Editing

curl -X POST http://localhost:8080/v1/images/edits \
  -H "Authorization: Bearer $CODEX2API_KEY" \
  -F "image=@original.png" \
  -F "prompt=Add a rainbow in the sky" \
  -F "model=gemini-2.0-flash-exp-image" \
  -F "n=1"

List Models

curl http://localhost:8080/v1/models \
  -H "Authorization: Bearer $CODEX2API_KEY"

Account Management API

Upload Refresh Tokens

curl -X POST http://localhost:8080/api/admin/accounts/upload \
  -H "X-Admin-Key: $ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "tokens": [
      "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
      "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
    ]
  }'

Upload Access Tokens

curl -X POST http://localhost:8080/api/admin/accounts/upload \
  -H "X-Admin-Key: $ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "tokens": [
      "sess-abc123...",
      "sess-def456..."
    ],
    "type": "access_token"
  }'

Test Account Health

# Test all accounts
curl -X POST http://localhost:8080/api/admin/accounts/test \
  -H "X-Admin-Key: $ADMIN_SECRET"

# Test specific account
curl -X POST http://localhost:8080/api/admin/accounts/test \
  -H "X-Admin-Key: $ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "550e8400-e29b-41d4-a716-446655440000"}'

List Accounts

curl http://localhost:8080/api/admin/accounts \
  -H "X-Admin-Key: $ADMIN_SECRET"

Delete Account

curl -X DELETE http://localhost:8080/api/admin/accounts/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-Admin-Key: $ADMIN_SECRET"

API Key Management

Create API Key

curl -X POST http://localhost:8080/api/admin/apikeys \
  -H "X-Admin-Key: $ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Client",
    "key": "sk-custom-key-123",
    "max_rpm": 100,
    "max_tpm": 50000
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production Client",
  "key": "sk-custom-key-123",
  "max_rpm": 100,
  "max_tpm": 50000,
  "enabled": true,
  "created_at": "2026-05-16T10:30:00Z"
}

List API Keys

curl http://localhost:8080/api/admin/apikeys \
  -H "X-Admin-Key: $ADMIN_SECRET"

Disable/Enable API Key

curl -X PATCH http://localhost:8080/api/admin/apikeys/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-Admin-Key: $ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Common Patterns

Account Scheduler Logic

The scheduler selects accounts based on:

  1. Health Tier: Active (healthy) > Cooldown (recovering) > Inactive (failed)
  2. Concurrency: Current concurrent requests < account's max concurrency
  3. Rate Limits: RPM (requests per minute) and TPM (tokens per minute) not exceeded
  4. Score: Weighted by success rate, recent failures, and last success time
  5. Cooldown Recovery: Accounts in cooldown automatically transition to Active after configured interval
// Scheduler picks account with highest score among eligible candidates
// Example internal scoring (simplified):
score := (successRate * 0.5) + 
         (1.0 - recentFailureRate * 0.3) + 
         (timeSinceLastSuccess * 0.2)

Health Check Workflow

# Accounts are tested with TestModel (configured in settings)
# Default: claude-code
# Test sends minimal completion request and validates response

# Health states:
# - Active: Last test succeeded, ready for requests
# - Cooldown: Recent failure, waiting for recovery
# - Inactive: Multiple consecutive failures, excluded from scheduling

Proxy Configuration

Set per-account proxy:

curl -X PATCH http://localhost:8080/api/admin/accounts/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-Admin-Key: $ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"proxy_url": "http://proxy.example.com:8080"}'

Global proxy via settings page or environment:

# .env
PROXY_URL=http://global-proxy:8080

Streaming Responses

import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ.get("CODEX2API_KEY"),
    base_url="http://localhost:8080/v1"
)

with client.messages.stream(
    model="claude-code",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Count to 10"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Prompt Filter (Block/Warn/Modify)

Configure in admin dashboard under "Prompt Filter":

{
  "enabled": true,
  "rules": [
    {
      "pattern": "(?i)nuclear",
      "action": "block",
      "message": "Content violates policy"
    },
    {
      "pattern": "(?i)medical advice",
      "action": "warn",
      "message": "Consider consulting a professional"
    }
  ]
}

Docker Commands

Standard Mode

# Start
docker compose up -d

# View logs
docker compose logs -f codex2api

# Restart
docker compose restart codex2api

# Stop
docker compose down

# Update to latest
docker compose pull && docker compose up -d

SQLite Mode

# Start
docker compose -f docker-compose.sqlite.yml up -d

# Logs
docker compose -f docker-compose.sqlite.yml logs -f codex2api

# Update
docker compose -f docker-compose.sqlite.yml pull
docker compose -f docker-compose.sqlite.yml up -d

Backup and Restore

PostgreSQL:

# Backup
docker exec codex2api-postgres pg_dump -U codex2api codex2api > backup_$(date +%Y%m%d_%H%M%S).sql

# Restore
docker exec -i codex2api-postgres psql -U codex2api codex2api < backup_20260516_103000.sql

SQLite:

# Backup (requires running container)
docker exec codex2api sqlite3 /data/codex2api.db ".backup /data/backup_$(date +%Y%m%d_%H%M%S).db"

# Or copy from host (if /data is mounted)
cp /path/to/data/codex2api.db /path/to/backup/codex2api_$(date +%Y%m%d_%H%M%S).db

Troubleshooting

No Healthy Accounts Available

Symptom: API returns 503 or "No available account"

Solutions:

  1. Check account health in admin dashboard
  2. Run account tests: POST /api/admin/accounts/test
  3. Verify Refresh Tokens are valid (not expired)
  4. Check cooldown settings and wait for recovery
  5. Review logs for authentication failures
# Check account status
curl http://localhost:8080/api/admin/accounts \
  -H "X-Admin-Key: $ADMIN_SECRET" | jq '.[] | {id, email, status, health_tier}'

# Force test all accounts
curl -X POST http://localhost:8080/api/admin/accounts/test \
  -H "X-Admin-Key: $ADMIN_SECRET"

Database Connection Failed

PostgreSQL:

# Test connection
docker exec codex2api-postgres pg_isready -U codex2api

# Check logs
docker logs codex2api-postgres

# Verify .env settings match docker-compose.yml
grep DATABASE_ .env

SQLite:

# Check file permissions
docker exec codex2api ls -la /data/codex2api.db

# Verify mount point
docker inspect codex2api | jq '.[0].Mounts'

Redis Connection Failed

# Test Redis
docker exec codex2api-redis redis-cli ping

# Check authentication
docker exec codex2api-redis redis-cli -a "$REDIS_PASSWORD" ping

# For TLS issues with cloud Redis
# Ensure REDIS_ADDR uses rediss:// or REDIS_TLS=true
# Check REDIS_INSECURE_SKIP_VERIFY if using self-signed certs

Rate Limit Exceeded

Symptom: 429 Too Many Requests

Solutions:

  1. Check API key limits in admin dashboard
  2. Increase max_rpm or max_tpm for the key
  3. Review global GlobalRPM setting
  4. Add more accounts to the pool
  5. Verify account-level rate limits
# Update API key limits
curl -X PATCH http://localhost:8080/api/admin/apikeys/YOUR_KEY_ID \
  -H "X-Admin-Key: $ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"max_rpm": 200, "max_tpm": 100000}'

High Concurrency Blocking

Symptom: Requests queue or timeout during high load

Solutions:

  1. Increase MaxConcurrency in settings
  2. Add more healthy accounts
  3. Adjust per-account concurrency limits
  4. Scale horizontally (multiple Codex2API instances with shared PostgreSQL/Redis)
# Check current concurrency
curl http://localhost:8080/api/admin/stats \
  -H "X-Admin-Key: $ADMIN_SECRET" | jq '.current_concurrency'

Image Generation Fails

Common issues:

  1. Model doesn't support images (only gemini-*-image models work)
  2. Image file format not supported (use PNG/JPEG)
  3. File size exceeds limits
  4. No accounts with image capability
# Verify image-capable models
curl http://localhost:8080/v1/models \
  -H "Authorization: Bearer $CODEX2API_KEY" | jq '.data[] | select(.id | contains("image"))'

Admin Dashboard 401 Unauthorized

Symptom: Login fails or /api/admin/* returns 401

Solutions:

  1. Verify ADMIN_SECRET in .env matches login password
  2. Check X-Admin-Key header in requests
  3. Restart after changing ADMIN_SECRET
# Check current admin secret source
docker exec codex2api env | grep ADMIN_SECRET

# Restart to apply .env changes
docker compose restart codex2api

Memory or CPU Usage High

PostgreSQL mode:

# Reduce connection pool size in settings
# Default PgMaxConns: 25, RedisPoolSize: 10

# Monitor resource usage
docker stats codex2api codex2api-postgres codex2api-redis

SQLite mode:

# SQLite is single-threaded; for high concurrency use PostgreSQL
# Check database file size
docker exec codex2api du -h /data/codex2api.db

# Run VACUUM to reclaim space
docker exec codex2api sqlite3 /data/codex2api.db "VACUUM;"

Advanced Configuration

Custom Test Model

# Update via settings API
curl -X PATCH http://localhost:8080/api/admin/settings \
  -H "X-Admin-Key: $ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"test_model": "claude-sonnet-4"}'

Auto-Cleanup Policies

Configure in admin settings:

  • AutoCleanupEnabled: Enable automatic cleanup
  • LogRetentionDays: Keep request logs for N days (default 30)
  • UsageRetentionDays: Keep usage records for N days (default 90)

Horizontal Scaling

Multiple Codex2API instances can share PostgreSQL + Redis:

# docker-compose.yml
services:
  codex2api-1:
    image: ghcr.io/james-6-23/codex2api:latest
    environment:
      - DATABASE_HOST=postgres
      - REDIS_ADDR=redis:6379
  codex2api-2:
    image: ghcr.io/james-6-23/codex2api:latest
    environment:
      - DATABASE_HOST=postgres
      - REDIS_ADDR=redis:6379

Use a load balancer (nginx, Caddy, Traefik) to distribute requests.

Health Check Endpoint

curl http://localhost:8080/health

Response:

{
  "status": "healthy",
  "database": "ok",
  "cache": "ok",
  "timestamp": "2026-05-16T10:30:00Z"
}

Use in Kubernetes liveness/readiness probes or Docker healthchecks.

Resources

FAQ

What does the codex2api-reverse-proxy skill do?

Codex2API is a production-ready reverse proxy that converts Codex account pools into OpenAI/Anthropic-compatible API gateways with account management, scheduling, and admin dashboard.

How do I install codex2api-reverse-proxy?

Run npx skills add https://github.com/reason-machines/codex-skills --skill codex2api-reverse-proxy in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/codex2api-reverse-proxy/ (personal) or .claude/skills/codex2api-reverse-proxy/ (project).

Which AI agents can use codex2api-reverse-proxy?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is codex2api-reverse-proxy safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains codex2api-reverse-proxy?

It is published by reason-machines in reason-machines/codex-skills. It has 256 recorded installs.

More from reason-machines/codex-skills

View all →

academic-research-skills-codex

reason-machines/codex-skills

Open the skill to read its SKILL.md instructions.

Productivity & Automation412 installs

codexplusplus-launcher

reason-machines/codex-skills

Open the skill to read its SKILL.md instructions.

282 installs

codex-plugin-claude-code

reason-machines/codex-skills

Open the skill to read its SKILL.md instructions.

273 installs

awesome-codex-skills-curator

reason-machines/codex-skills

Open the skill to read its SKILL.md instructions.

270 installs

codex-plusplus-tweak-system

reason-machines/codex-skills

Open the skill to read its SKILL.md instructions.

270 installs

awesome-codex-subagents

reason-machines/codex-skills

Open the skill to read its SKILL.md instructions.

AI & Agents268 installs

Popular ai & agents skills

View category →

google-agents-cli-publish

google/agents-cli

This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).

AI & Agents513.9K installs

google-agents-cli-eval

google/agents-cli

This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).

AI & Agents513.5K installs

skill-creator

anthropics/skills

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

OfficialAI & Agents416.4K installs

codex-pet

prime-skills/runcomfy-agent-skills

Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.

AI & Agents402.1K installs

full-output-enforcement

leonxlnx/taste-skill

Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.

AI & Agents401K installs

executing-plans

obra/superpowers

Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available

AI & Agents245.7K installs