The public image does not require a registry login:

$ docker pull ghcr.io/hotchpotch/openai-api-server-via-codex:latest
$ docker run --rm -p 127.0.0.1:18080:18080 \
    -v ~/.codex:/home/app/.codex \
    ghcr.io/hotchpotch/openai-api-server-via-codex:latest

The auth directory is mounted read-write so refreshed tokens can be saved. See the Docker guide for Windows, permissions, Compose, and login instructions.

$env:OPENAI_BASE_URL = "http://127.0.0.1:18080/v1"
$env:OPENAI_API_KEY = "dummy-not-a-real-openai-api-key"
uv run --with openai python example.py

Published wheels contain the Go executable for:

• Linux x86_64 and ARM64
• macOS Intel and Apple silicon
• Windows x86_64 and ARM64

Run without a permanent installation:

$ uvx openai-api-server-via-codex

Or install it on your user tool path:

$ uv tool install openai-api-server-via-codex
$ openai-api-server-via-codex --version

There is no Python server fallback and no generic source distribution. Build the Go executable directly on an unsupported platform.

Each GitHub Release includes versioned archives for Linux, macOS, and Windows on x86_64 and ARM64, together with checksums.txt. Unix archives use .tar.gz; Windows archives use .zip.

For example, on an Apple silicon Mac:

$ curl -LO https://github.com/hotchpotch/openai-api-server-via-codex/releases/download/v0.2.2/openai-api-server-via-codex_0.2.2_darwin_arm64.tar.gz
$ curl -LO https://github.com/hotchpotch/openai-api-server-via-codex/releases/download/v0.2.2/checksums.txt
$ grep 'darwin_arm64.tar.gz' checksums.txt | shasum -a 256 --check
$ tar -xzf openai-api-server-via-codex_0.2.2_darwin_arm64.tar.gz
$ ./openai-api-server-via-codex --version

The stable archive URLs and SHA-256 checksums are suitable for Homebrew Formulae. Installing a historical version through Homebrew requires a tap to retain a versioned Formula such as openai-api-server-via-codex@0.2.2.

Stable Linux x86_64 and ARM64 images are published at ghcr.io/hotchpotch/openai-api-server-via-codex. latest tracks the newest stable release. Exact tags such as v0.2.2 provide reproducible deployments; prereleases publish only their exact version tag.

The final Alpine image contains the Go server and CA certificates, but no Python runtime or Go toolchain. On amd64, local measurements show about 7 MB of compressed registry layers, a 21 MB local image, and roughly 4–7 MiB of idle memory. Exact values depend on the release, architecture, and container runtime.

$ docker pull ghcr.io/hotchpotch/openai-api-server-via-codex:latest
$ docker run --rm -p 127.0.0.1:18080:18080 \
    -v ~/.codex:/home/app/.codex \
    ghcr.io/hotchpotch/openai-api-server-via-codex:latest

Or build from this checkout:

$ docker compose run --rm --service-ports codex-login  # only if auth.json is missing
$ docker compose up --build -d
$ curl http://127.0.0.1:18080/healthz

The container runs as a non-root user. See the Docker guide for complete usage and troubleshooting.

Go can download and install the command from its public module path:

$ go install github.com/hotchpotch/openai-api-server-via-codex/cmd/openai-api-server-via-codex@latest
$ "$(go env GOPATH)/bin/openai-api-server-via-codex" --version

The executable is installed under GOBIN, or under $(go env GOPATH)/bin when GOBIN is unset.

To build from a checkout:

$ go build -trimpath -o ./bin/openai-api-server-via-codex ./cmd/openai-api-server-via-codex
$ ./bin/openai-api-server-via-codex --version
$ ./bin/openai-api-server-via-codex serve

This path does not require Python or uv. See Building the Go binary from source for version stamping, installation, Windows commands, static builds, and cross-compilation.

from openai import OpenAI

client = OpenAI()
chat = client.chat.completions.create(
    model="gpt-6-luna",
    messages=[{"role": "user", "content": "Hello"}],
    reasoning_effort="low",
)
print(chat.choices[0].message.content)

Responses:

stream = client.responses.create(
    model="gpt-6-luna",
    input="Stream a short reply.",
    stream=True,
    reasoning={"effort": "low"},
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")

Chat Completions:

stream = client.chat.completions.create(
    model="gpt-6-luna",
    messages=[{"role": "user", "content": "Stream a short reply."}],
    stream=True,
    reasoning_effort="low",
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Image input:

response = client.responses.create(
    model="gpt-6-luna",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Describe this image."},
                {
                    "type": "input_image",
                    "image_url": "data:image/png;base64,...",
                },
            ],
        }
    ],
)

Image generation:

import base64

image = client.images.generate(
    model="gpt-image-2",
    prompt="A cozy pixel art bowl of ramen, no text.",
    size="1024x1024",
    quality="medium",
    output_format="png",
)

with open("ramen.png", "wb") as file:
    file.write(base64.b64decode(image.data[0].b64_json))

Image generation returns data[].b64_json. URL results, image editing, and streamed partial images are not implemented.

response = client.responses.create(
    model="gpt-6-luna",
    input="What is the weather in Tokyo?",
    tools=[
        {
            "type": "function",
            "name": "get_weather",
            "description": "Get the weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
                "additionalProperties": False,
            },
            "strict": True,
        }
    ],
)

• sync and async openai-python clients
• non-streaming and streaming Responses and Chat Completions
• Responses WebSocket relay with upstream conversation state, async tools, and mid-turn steering (usage and Codex limitations)
• previous_response_id backed by bounded local context
• stored Chat list/retrieve/update/delete/messages APIs
• Responses retrieve streaming, delete, cancel, and input-token count
• function/tool calling and streamed tool arguments
• JSON mode and structured outputs
• URL and data-URL image input
• hosted image generation translated through a Codex Responses tool
• optional incoming API-key authentication
• bounded request concurrency and in-memory stores

At the Codex HTTP boundary, requests are normalized to stream=true, store=false, low text verbosity by default, Codex-compatible tool defaults, and encrypted reasoning content. Public storage compatibility is implemented in the server's bounded in-memory stores.

Model listing is best-effort. A model can sometimes accept direct requests even when it is absent from the upstream catalog returned by /v1/models.

WebSocket responses stay on the upstream connection and are not registered with the local HTTP retrieve/cancel helpers. Codex currently rejects Background mode and named WebSocket streams (stream_id); these features are not emulated.

Unknown /v1/... requests use a best-effort fallback proxy. The server forwards the method, path, query, safe OpenAI-style headers, and body with its own Codex credentials. Upstream support determines whether an unknown endpoint returns 2xx, 400, 403, or 404.

Generate a configuration file:

$ openai-api-server-via-codex config-generate
$ openai-api-server-via-codex config-generate --stdout

The default path is $XDG_CONFIG_HOME/openai-api-server-via-codex/config.toml, falling back to ~/.config/openai-api-server-via-codex/config.toml.

Settings resolve in this order:

CLI flag -> environment variable -> config file -> default

Example configuration using gpt-6-luna:

[server]
host = "127.0.0.1"
port = 18080
default_model = "gpt-6-luna"
timeout = 300.0
verbose = false
max_stored_items = 1000
max_concurrent_requests = 10
# api_key = "change-me"

[codex]
auth_json = "~/.codex/auth.json"
backend_base_url = "https://chatgpt.com/backend-api/codex"
client_version = "1.0.0"

[compat]
drop_params = []

[daemon]
state_dir = "~/.config/openai-api-server-via-codex/run"
stop_timeout = 10.0

Examples:

$ openai-api-server-via-codex --port 19090 --verbose
$ OPENAI_VIA_CODEX_MAX_CONCURRENT_REQUESTS=20 openai-api-server-via-codex
$ openai-api-server-via-codex --config ./config.toml

Use drop_params only for parameters known to be rejected by Codex:

[compat]
drop_params = ["temperature", "top_p"]

prompt_cache_breakpoint on input content parts is always removed because Codex rejects it; prompt_cache_key is still forwarded.

The Go executable implements foreground and daemon lifecycle commands:

$ openai-api-server-via-codex start
$ openai-api-server-via-codex status
$ openai-api-server-via-codex stop

PID and log files default to:

~/.config/openai-api-server-via-codex/run/

On Linux and macOS, stop drains in-flight HTTP requests up to --stop-timeout. Windows terminates the daemon process tree on a best-effort basis, so an active stream may be interrupted.

Docker should run serve in the foreground and let the container runtime manage restarts; do not use start inside a container.

Normal operation logs one completion line per API request with its method, redacted path, status, response size, and duration. Routine /healthz probes stay quiet.

Verbose logs additionally include request starts and redacted query strings, resolved settings, endpoint summaries, and Codex stream/auth activity. Raw credentials and token-like values are redacted.

The HTTP server, backend integration, auth, configuration, stores, daemon, and redaction logic are implemented in Go under cmd/ and internal/. Python is used only for the uvx launcher, the official openai-python consumer contract, and release tooling.

Requirements:

• Go 1.23 or newer
• Python 3.10 or newer
• uv

Run the complete deterministic validation suite:

$ uv run tox

Focused Go validation:

$ go test ./internal/app
$ go test ./test/e2e -v
$ go test ./...
$ go vet ./...
$ go test -race ./...

OpenAI SDK consumer compatibility:

$ uv run python -m pytest tests/test_openai_client_contract.py -q

Real Codex tests are opt-in because they use the current login, network, model allowance, and image quota:

$ RUN_CODEX_LIVE_TESTS=1 uv run python -m pytest tests/test_live_astra_websocket.py -q -s
$ RUN_CODEX_LIVE_TESTS=1 go test ./test/live -v -count=1 -timeout=20m
$ RUN_CODEX_LIVE_TESTS=1 uv run python -m pytest tests/test_live_integration.py -q -s
$ RUN_CODEX_LIVE_TESTS=1 uv run python -m pytest tests/test_live_codex_http_compatibility.py -q -s

Releases are prepared on a release/vX.Y.Z branch and reviewed through a PR. Merging the PR does not publish artifacts; pushing the annotated vX.Y.Z tag on the merged commit starts the release workflow.

Further documentation:

• Building the Go binary from source
• Go runtime test policy
• Historical Go/Python performance comparison
• Release process