openai · owenlin0 · Mar 10, 2026 · Mar 10, 2026 · Mar 10, 2026 · Mar 10, 2026
diff --git a/sdk/python-runtime/README.md b/sdk/python-runtime/README.md
@@ -0,0 +1,9 @@
+# Codex CLI Runtime for Python SDK
+
+Platform-specific runtime package consumed by the published `codex-app-server-sdk`.
+
+This package is staged during release so the SDK can pin an exact Codex CLI
+version without checking platform binaries into the repo.
+
+`codex-cli-bin` is intentionally wheel-only. Do not build or publish an sdist
+for this package.
diff --git a/sdk/python-runtime/hatch_build.py b/sdk/python-runtime/hatch_build.py
@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class RuntimeBuildHook(BuildHookInterface):
+    def initialize(self, version: str, build_data: dict[str, object]) -> None:
+        del version
+        if self.target_name == "sdist":
+            raise RuntimeError(
+                "codex-cli-bin is wheel-only; build and publish platform wheels only."
+            )
+
+        build_data["pure_python"] = False
+        build_data["infer_tag"] = True
diff --git a/sdk/python-runtime/pyproject.toml b/sdk/python-runtime/pyproject.toml
@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling>=1.24.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codex-cli-bin"
+version = "0.0.0-dev"
+description = "Pinned Codex CLI runtime for the Python SDK"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "OpenAI" }]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Homepage = "https://github.com/openai/codex"
+Repository = "https://github.com/openai/codex"
+Issues = "https://github.com/openai/codex/issues"
+
+[tool.hatch.build]
+exclude = [
+  ".venv/**",
+  ".pytest_cache/**",
+  "dist/**",
+  "build/**",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codex_cli_bin"]
+include = ["src/codex_cli_bin/bin/**"]
+
+[tool.hatch.build.targets.wheel.hooks.custom]
+
+[tool.hatch.build.targets.sdist]
+
+[tool.hatch.build.targets.sdist.hooks.custom]
diff --git a/sdk/python-runtime/src/codex_cli_bin/__init__.py b/sdk/python-runtime/src/codex_cli_bin/__init__.py
@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+PACKAGE_NAME = "codex-cli-bin"
+
+
+def bundled_codex_path() -> Path:
+    exe = "codex.exe" if os.name == "nt" else "codex"
+    path = Path(__file__).resolve().parent / "bin" / exe
+    if not path.is_file():
+        raise FileNotFoundError(
+            f"{PACKAGE_NAME} is installed but missing its packaged codex binary at {path}"
+        )
+    return path
+
+
+__all__ = ["PACKAGE_NAME", "bundled_codex_path"]
diff --git a/sdk/python/README.md b/sdk/python/README.md
@@ -11,6 +11,10 @@ cd sdk/python
 python -m pip install -e .
 ```
 
+Published SDK builds pin an exact `codex-cli-bin` runtime dependency. For local
+repo development, pass `AppServerConfig(codex_bin=...)` to point at a local
+build explicitly.
+
 ## Quickstart
 
 ```python
@@ -40,33 +44,45 @@ python examples/01_quickstart_constructor/sync.py
 python examples/01_quickstart_constructor/async.py
 ```
 
-## Bundled runtime binaries (out of the box)
+## Runtime packaging
 
-The SDK ships with platform-specific bundled binaries, so end users do not need updater scripts.
+The repo no longer checks `codex` binaries into `sdk/python`.
 
-Runtime binary source (single source, no fallback):
+Published SDK builds are pinned to an exact `codex-cli-bin` package version,
+and that runtime package carries the platform-specific binary for the target
+wheel.
 
-- `src/codex_app_server/bin/darwin-arm64/codex`
-- `src/codex_app_server/bin/darwin-x64/codex`
-- `src/codex_app_server/bin/linux-arm64/codex`
-- `src/codex_app_server/bin/linux-x64/codex`
-- `src/codex_app_server/bin/windows-arm64/codex.exe`
-- `src/codex_app_server/bin/windows-x64/codex.exe`
+For local repo development, the checked-in `sdk/python-runtime` package is only
+a template for staged release artifacts. Editable installs should use an
+explicit `codex_bin` override instead.
 
-## Maintainer workflow (refresh binaries/types)
+## Maintainer workflow
 
 ```bash
 cd sdk/python
-python scripts/update_sdk_artifacts.py --channel stable --bundle-all-platforms
-# or
-python scripts/update_sdk_artifacts.py --channel alpha --bundle-all-platforms
+python scripts/update_sdk_artifacts.py generate-types
+python scripts/update_sdk_artifacts.py \
+  stage-sdk \
+  /tmp/codex-python-release/codex-app-server-sdk \
+  --runtime-version 1.2.3
+python scripts/update_sdk_artifacts.py \
+  stage-runtime \
+  /tmp/codex-python-release/codex-cli-bin \
+  /path/to/codex \
+  --runtime-version 1.2.3
 ```
 
-This refreshes all bundled OS/arch binaries and regenerates protocol-derived Python types.
+This supports the CI release flow:
+
+- run `generate-types` before packaging
+- stage `codex-app-server-sdk` once with an exact `codex-cli-bin==...` dependency
+- stage `codex-cli-bin` on each supported platform runner with the same pinned runtime version
+- build and publish `codex-cli-bin` as platform wheels only; do not publish an sdist
 
 ## Compatibility and versioning
 
 - Package: `codex-app-server-sdk`
+- Runtime package: `codex-cli-bin`
 - Current SDK version in this repo: `0.2.0`
 - Python: `>=3.10`
 - Target protocol: Codex `app-server` JSON-RPC v2

diff --git a/sdk/python/docs/faq.md b/sdk/python/docs/faq.md
@@ -33,15 +33,27 @@ Use `thread(...)` for simple continuation. Use `thread_resume(...)` when you nee
 
 Common causes:
 
-- bundled runtime binary missing for your OS/arch under `src/codex_app_server/bin/*`
+- published runtime package (`codex-cli-bin`) is not installed
+- local `codex_bin` override points to a missing file
 - local auth/session is missing
 - incompatible/old app-server
 
-Maintainers can refresh bundled binaries with:
+Maintainers stage releases by building the SDK once and the runtime once per
+platform with the same pinned runtime version. Publish `codex-cli-bin` as
+platform wheels only; do not publish an sdist:
 
 ```bash
 cd sdk/python
-python scripts/update_sdk_artifacts.py --channel stable --bundle-all-platforms
+python scripts/update_sdk_artifacts.py generate-types
+python scripts/update_sdk_artifacts.py \
+  stage-sdk \
+  /tmp/codex-python-release/codex-app-server-sdk \
+  --runtime-version 1.2.3
+python scripts/update_sdk_artifacts.py \
+  stage-runtime \
+  /tmp/codex-python-release/codex-cli-bin \
+  /path/to/codex \
+  --runtime-version 1.2.3
 ```
 
 ## Why does a turn "hang"?

diff --git a/sdk/python/docs/getting-started.md b/sdk/python/docs/getting-started.md
@@ -14,7 +14,7 @@ python -m pip install -e .
 Requirements:
 
 - Python `>=3.10`
-- bundled runtime binary for your platform (shipped in package)
+- installed `codex-cli-bin` runtime package, or an explicit `codex_bin` override
 - Local Codex auth/session configured
 
 ## 2) Run your first turn

diff --git a/sdk/python/pyproject.toml b/sdk/python/pyproject.toml
@@ -30,7 +30,7 @@ Repository = "https://github.com/openai/codex"
 Issues = "https://github.com/openai/codex/issues"
 
 [project.optional-dependencies]
-dev = ["pytest>=8.0", "datamodel-code-generator==0.31.2"]
+dev = ["pytest>=8.0", "datamodel-code-generator==0.31.2", "ruff>=0.11"]
 
 [tool.hatch.build]
 exclude = [
@@ -44,7 +44,6 @@ exclude = [
 [tool.hatch.build.targets.wheel]
 packages = ["src/codex_app_server"]
 include = [
-  "src/codex_app_server/bin/**",
   "src/codex_app_server/py.typed",
 ]