Pre-release

This release is a pre-release and may not be stable for production use.

OpenAI API Server via Codex

Run an OpenAI-compatible local API server using the Codex access from your ChatGPT login. The server itself is a standalone Go executable; clients can use the standard Responses and Chat Completions APIs by changing their base URL.

[!IMPORTANT] Breaking change planned for v0.2.0: stable releases from 0.2.0 onward start the server implemented in Go. The former Python/FastAPI HTTP server and Python fallback have been removed. The Python package remains only as a small uvx launcher that selects the bundled Go executable. The 0.1.6b2 beta previews this migration before the stable 0.2.0 release.

Start the Go server with uvx, then call the OpenAI-compatible Responses API

Quick start

Make sure Codex is logged in and ~/.codex/auth.json exists, then start the Go server with either uvx or Docker.

uvx

$ uvx openai-api-server-via-codex
2026/08/12 12:34:56 openai-api-server-via-codex 0.1.6b2 (Go) listening on http://127.0.0.1:18080

Until 0.2.0 is published, select the Go beta explicitly:

$ uvx --from openai-api-server-via-codex==0.1.6b2 openai-api-server-via-codex

Docker

The public image needs no registry login. The current amd64 image is only about 21 MB, and idle memory use is a few MiB (roughly 4–7 MiB in local measurements; the exact value depends on the host and container runtime).

Until stable v0.2.0 is published, use the beta tag:

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

For stable releases, replace v0.1.6b2 with latest.

Point an OpenAI client at the local endpoint:

$ export OPENAI_BASE_URL=http://127.0.0.1:18080/v1
$ export OPENAI_API_KEY=dummy

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-5.6-luna",
    input="Reply in one sentence.",
    reasoning={"effort": "low"},
)
print(response.output_text)

OPENAI_API_KEY=dummy only satisfies the OpenAI SDK's client-side validation. The server accepts any incoming value unless you configure its --api-key.

Why use it

  • OpenAI-compatible: use existing openai-python, LangChain, LiteLLM, and other clients with a configurable base URL.
  • Codex-backed: requests use the Codex access associated with your ChatGPT login instead of OpenAI Platform API credentials.
  • Go runtime: fast startup, low resident memory, a single server executable, and no Python web stack.
  • Broad API coverage: Responses, Chat Completions, streaming, tools, structured outputs, image input, image generation, audio transcription, and locally stored compatibility objects.
  • Local by default: the server binds to 127.0.0.1, validates Codex auth before listening, and supports an incoming API key when remote access is required.
  • Portable: binary wheels cover Linux, macOS, and Windows on x86_64 and ARM64; Docker and direct Go builds are also supported.

This project does not raise or bypass Codex or ChatGPT plan limits. It is not the official OpenAI Platform API. Use it only with accounts you are authorized to use, and do not expose it publicly or resell access.

Installation and execution

Choose one of these paths:

Method Host requirements Server runtime
uvx openai-api-server-via-codex uv, Codex login Bundled Go executable
docker pull ghcr.io/hotchpotch/openai-api-server-via-codex:latest Docker, Codex login Public Go/Alpine image (~21 MB; a few MiB idle memory)
docker compose up --build -d Docker, Codex login Go on Alpine Linux
Build from source Go 1.23+, Codex login Locally built Go executable

Run with uvx

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 the launcher and bundled executable 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. On an unsupported platform, build the Go executable directly.

Run with Docker

The production image builds the server from source and copies only the static Go executable and CA certificates into a small Alpine runtime. Python and the Go toolchain are absent from the final server image.

Stable releases are published for Linux x86_64 and ARM64 at ghcr.io/hotchpotch/openai-api-server-via-codex. latest always points to the newest stable release; an exact Git tag such as v0.2.0 remains available for reproducible deployments. Prereleases publish only their exact version tag and do not move latest. The package is public, so pulls do 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

Or build the same runtime image 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 server runs as a non-root user and mounts ~/.codex read-write so refreshed tokens can be saved. See the Docker guide for login methods, permissions, configuration, and plain docker run usage.

Build your own Go binary

After v0.2.0 is published, Go can download, build, and install the command directly from its GitHub 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 instead:

$ 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.

Authentication and security

The server borrows a Codex ChatGPT login, normally from ~/.codex/auth.json. serve and start validate the file before binding the HTTP port. Invalid, missing, expired, or unrefreshable credentials fail startup with a redacted error.

The server notices external changes to auth.json without a restart. If an upstream request receives 401 Unauthorized before any streaming response has started, it discards its credential cache, reloads the file, and retries that request once. This covers Codex CLI or another process rotating the token between requests; a second 401 is returned without another retry.

Select another auth file when needed:

$ openai-api-server-via-codex --auth-json /path/to/auth.json
$ OPENAI_VIA_CODEX_AUTH_JSON=/path/to/auth.json openai-api-server-via-codex

The incoming OpenAI-compatible API key is separate from Codex authentication. Protect /v1/... routes when clients can reach the server over a network:

$ openai-api-server-via-codex \
    --host 0.0.0.0 \
    --api-key local-secret

/healthz remains unauthenticated. Incoming API keys, cookies, and Authorization headers are never forwarded to the Codex backend.

More OpenAI client examples

Chat Completions

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

Streaming Responses

stream = client.responses.create(
    model="gpt-5.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="")

Streaming Chat Completions

stream = client.chat.completions.create(
    model="gpt-5.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-5.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.

Tool calling

response = client.responses.create(
    model="gpt-5.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,
        }
    ],
)
Background daemon commands

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.

API surface and compatibility details

Implemented endpoints

Method Path
GET /healthz
GET /v1/models
POST /v1/responses
GET /v1/responses/{response_id}
DELETE /v1/responses/{response_id}
POST /v1/responses/{response_id}/cancel
POST /v1/responses/input_tokens
POST /v1/audio/transcriptions
POST /v1/images/generations
POST /v1/chat/completions
GET /v1/chat/completions
GET /v1/chat/completions/{completion_id}
POST /v1/chat/completions/{completion_id}
DELETE /v1/chat/completions/{completion_id}
GET /v1/chat/completions/{completion_id}/messages

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

Compatibility behavior

  • sync and async openai-python clients
  • non-streaming and streaming Responses and Chat Completions
  • 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 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 Go 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.

Configuration reference

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

[server]
host = "127.0.0.1"
port = 18080
default_model = "gpt-5.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

Important server settings

Setting Default Purpose
server.host 127.0.0.1 HTTP bind address
server.port 18080 HTTP port
server.default_model gpt-5.6-luna Model used when a request omits one
server.api_key unset Protect incoming /v1/... requests
server.max_stored_items 1000 Bound local Responses/Chat stores; 0 disables
server.max_concurrent_requests 10 Bound full Codex requests/streams; 0 disables
server.timeout 300.0 Codex backend timeout in seconds
server.verbose false Enable redacted Go application diagnostics
codex.auth_json ~/.codex/auth.json Codex OAuth file
compat.drop_params [] Top-level request fields removed before forwarding

CLI, environment, and config 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 the Codex backend:

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

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.

Development and test guide

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

Requirements for full repository development:

  • 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 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

See also:

Disclaimer

Use this project at your own risk. It is not the official OpenAI Platform API and is not endorsed or supported by OpenAI. It forwards requests to the Codex HTTP backend used by the Codex CLI and ChatGPT subscription flow instead of api.openai.com; that backend may change without notice.

Use the server only with accounts and subscriptions you are authorized to use. Do not evade limits, share account access, resell access, or expose the service to untrusted networks without authentication. Follow OpenAI's Terms of Use and Usage Policies.

License

Apache License 2.0. See LICENSE.

Acknowledgements

  • Simon Willison's article, A pelican for GPT-5.5 via the semi-official Codex backdoor API, and the implementation described there were the key references for this project. Without that article, this approach likely would not have been implemented here. Thank you to Simon for documenting the route clearly.
  • OpenClaw was a useful reference for understanding Codex backend integration patterns.
  • Pi Monorepo was a useful reference for Codex backend API behavior and compatibility details.

Author

Yuichi Tateno

Project links

Data verified by PyPI on Aug 12, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for hotchpotch from gravatar.com hotchpotch

Credits

Author: hotchpotch

GitHub Statistics

Data verified by PyPI on Aug 12, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.10

Tags

codex openai openai-compatible uvx golang

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

openai_api_server_via_codex-0.1.6b2-py3-none-win_arm64.whl (2.7 MB view details)

Uploaded Python 3Windows ARM64

openai_api_server_via_codex-0.1.6b2-py3-none-win_amd64.whl (3.0 MB view details)

Uploaded Python 3Windows x86-64

openai_api_server_via_codex-0.1.6b2-py3-none-manylinux_2_17_x86_64.whl (2.9 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

openai_api_server_via_codex-0.1.6b2-py3-none-manylinux_2_17_aarch64.whl (2.7 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

openai_api_server_via_codex-0.1.6b2-py3-none-macosx_11_0_arm64.whl (2.7 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

openai_api_server_via_codex-0.1.6b2-py3-none-macosx_10_15_x86_64.whl (2.9 MB view details)

Uploaded Python 3macOS 10.15+ x86-64

File details

Details for the file openai_api_server_via_codex-0.1.6b2-py3-none-win_arm64.whl.

File metadata

File hashes

Hashes for openai_api_server_via_codex-0.1.6b2-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 40845449732100e21537f09c321f35706e68fc65e3973a35f75579abb9ca05f5
MD5 5faf385aa09f55333fc466257135f660
BLAKE2b-256 5c7a17cde2a1be26c9137de536553bf66ed97c5e69f3fde66f5a800336de49ea

See more details on using hashes here.

Provenance

The following attestation bundles were made for openai_api_server_via_codex-0.1.6b2-py3-none-win_arm64.whl:

Publisher: release.yml on hotchpotch/openai-api-server-via-codex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openai_api_server_via_codex-0.1.6b2-py3-none-win_amd64.whl.

File metadata

File hashes

Hashes for openai_api_server_via_codex-0.1.6b2-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 72a6ddcd5448ffbd9a4c20e5ef6f9a6d680e720932b0291b8dcdc6aa3b29b5fe
MD5 32dfe9ad5ade29a39810bee95d9bccd5
BLAKE2b-256 0be7b4a869fe205faa262cbf8ecf8d3fd6c71606800a4dd6fcf7d8b65052dc80

See more details on using hashes here.

Provenance

The following attestation bundles were made for openai_api_server_via_codex-0.1.6b2-py3-none-win_amd64.whl:

Publisher: release.yml on hotchpotch/openai-api-server-via-codex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openai_api_server_via_codex-0.1.6b2-py3-none-manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for openai_api_server_via_codex-0.1.6b2-py3-none-manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 9cee78840258c6b4d0eba6540bb2566d0dc0f28b6df9e70cbef263aea7b3d33c
MD5 0f6987e5c21b3fb77021e28f6ccaef45
BLAKE2b-256 1f23eb931023e040caedca4b59da41bf75ba5a199d7c9b6b2c8dcb562b5769a2

See more details on using hashes here.

Provenance

The following attestation bundles were made for openai_api_server_via_codex-0.1.6b2-py3-none-manylinux_2_17_x86_64.whl:

Publisher: release.yml on hotchpotch/openai-api-server-via-codex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openai_api_server_via_codex-0.1.6b2-py3-none-manylinux_2_17_aarch64.whl.

File metadata

File hashes

Hashes for openai_api_server_via_codex-0.1.6b2-py3-none-manylinux_2_17_aarch64.whl
Algorithm Hash digest
SHA256 5cca77ab74c4b3fa5ed3f85565b95c5965c8b31ba90bc7c3ead7a1559836a229
MD5 f82ab2e815c7ea1106a6825bf686e4df
BLAKE2b-256 158c041ad7cd0856b8f3c9fa853cd3044bff2785ba3d72949f15ebecd3ede609

See more details on using hashes here.

Provenance

The following attestation bundles were made for openai_api_server_via_codex-0.1.6b2-py3-none-manylinux_2_17_aarch64.whl:

Publisher: release.yml on hotchpotch/openai-api-server-via-codex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openai_api_server_via_codex-0.1.6b2-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for openai_api_server_via_codex-0.1.6b2-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 4646067c188fe5489f1bde41f9c109f9558fced189c83f90f943df5fefff5990
MD5 2662f7e606d9ee1a5d30b16c86ba0dbc
BLAKE2b-256 d1067eac17bf11549222e6878baccebb425b1e9c748b69c257a0ba22c6311c93

See more details on using hashes here.

Provenance

The following attestation bundles were made for openai_api_server_via_codex-0.1.6b2-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on hotchpotch/openai-api-server-via-codex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openai_api_server_via_codex-0.1.6b2-py3-none-macosx_10_15_x86_64.whl.

File metadata

File hashes

Hashes for openai_api_server_via_codex-0.1.6b2-py3-none-macosx_10_15_x86_64.whl
Algorithm Hash digest
SHA256 001056c7f202ad94cac646e38ac13031f44d958614832b0bc519ba03c26be40b
MD5 6671acf21bfce2ab377e01432f37ee81
BLAKE2b-256 1853cb3584ab666119fd12f3b73e155c9cb8549fdf9ce62f0ea9081f6e3e0c80

See more details on using hashes here.

Provenance

The following attestation bundles were made for openai_api_server_via_codex-0.1.6b2-py3-none-macosx_10_15_x86_64.whl:

Publisher: release.yml on hotchpotch/openai-api-server-via-codex

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.2.1

6 files

0.2.0

6 files

This release
Pre-release

0.1.6b2 This release

6 files

Pre-release

0.1.6b1

6 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

0.0.5

2 files

0.0.4

2 files

0.0.3

2 files

0.0.2

2 files

0.0.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page