What openai-codex Beta Gets Wrong on First Install

What openai-codex v0.1.0b1 Ships

openai-codex v0.1.0b1 is OpenAI's first officially published Python SDK for embedding Codex agent capabilities directly in application code. It is distinct from the earlier community package openai-codex-sdk, which wrapped the CLI binary via JSONL over stdin/stdout and first appeared in December 2025 . The official beta landed May 28, 2026 alongside Codex CLI v0.135.0, and the SDK version tracks the CLI directly. Both 0.1.0b1 and 0.1.0b2 appeared on PyPI the same day under Apache-2.0 .

Quick Answer: openai-codex v0.1.0b1 is OpenAI's official Python SDK for Codex agent threads, released May 28, 2026 under Apache-2.0. Install with pip install openai-codex==0.1.0b1. Requires Python ≥3.10. The CLI binary is bundled automatically — no separate CLI install needed.

Three PRs stabilized the API surface before the public release: schema-generated types (PR #18862, April 21, 2026) , runtime wheel publishing (PR #18865), and Codex-pinned versioning (PR #18996, April 27, 2026) . The package ships as Development Status 4 (beta); public APIs are not stable until 1.0.

The headlining new surface is three named Sandbox presets at the thread level, replacing the older --profile flag approach:

Installation and Prerequisites

The only hard requirement is Python ≥3.10 — tested against 3.10, 3.11, 3.12, and 3.13. No separate Codex CLI install is needed; the package auto-installs openai-codex-cli-bin as a pinned runtime dependency . Install and pin the exact version to avoid silent resolution to 0.1.0b2, which shares the same May 28, 2026 release date :

pip install openai-codex==0.1.0b1

Four authentication flows are available:

• Reuse existing CLI credentials — simplest for local dev; instantiate Codex() with no arguments and it picks up cached credentials automatically.
• API key — call codex.login_api_key('sk-...') after instantiation; set OPENAI_API_KEY in the environment. Suited for CI/CD pipelines.
• Browser login — codex.login_chatgpt() returns an auth URL to open in a browser; suited for interactive terminals.
• Device-code flow — codex.login_chatgpt_device_code() returns a verification URL and user code; suited for headless servers.

Device-code and API-key flows became first-class in CLI v0.132.0, released May 20, 2026 . If you are reusing credentials from an older CLI install, run an explicit login step — silent failures are a known issue (see Gotchas below).

From Import to First Thread: A Walkthrough

The snippet below is illustrative — the codex_app_server module is auto-installed as part of the openai-codex package but was not available in the test environment at time of writing. Run the install comment first, then the code. The getting-started guide has a fully executed variant.

"""First beta install: python -m pip install openai-codex==0.1.0b1"""

from codex_app_server import Codex


with Codex() as codex:
    thread = codex.thread_start(model="gpt-5.4")

    first = thread.run("Reply with exactly: first beta thread started")
    print("first:", first.final_response)

    followup = thread.run("Reply with exactly: same thread follow-up")
    print("followup:", followup.final_response)

Step by step:

1. Import and open. The with Codex() as codex: context manager starts a local JSON-RPC app-server on entry and shuts it down cleanly on exit. No manual server lifecycle management required.
2. Start a thread. codex.thread_start(model="gpt-5.4") creates a persistent conversation unit. Supported models include gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex, and gpt-5.3-codex-spark (ChatGPT Pro only) . Pass sandbox="read_only" here to scope the agent's filesystem access for the thread's lifetime.
3. Run a turn. thread.run("...") sends a prompt and blocks until completion. Plain strings auto-convert to TextInput; pass ImageInput(url=...) or LocalImageInput(path=...) for vision prompts.
4. Inspect the result. The returned TurnResult exposes final_response (str or None), items (list of ThreadItem), usage (ThreadTokenUsage), duration_ms, started_at, and completed_at . Log result.usage and result.duration_ms from your first run — you want a baseline before switching models or sandbox presets.

For async contexts, swap Codex for AsyncCodex and replace with / thread.run() with async with / await thread.run(). Lazy initialization keeps import-time overhead negligible. The interface is otherwise identical, making it a straightforward drop-in for FastAPI routes or asyncio pipelines:

import asyncio
from openai_codex import AsyncCodex

async def main():
    async with AsyncCodex() as codex:
        thread = await codex.thread_start(model="gpt-5.4-mini")
        result = await thread.run("Generate a docstring for utils.py")
        print(result.final_response)

asyncio.run(main())

Gotchas and Beta Caveats

Five issues worth knowing before you take this beyond a prototype:

• Version collision on install day. v0.1.0b1 and v0.1.0b2 share the same May 28, 2026 PyPI release date . Without an explicit pin, pip may silently resolve to the higher patch. Always lock to the version you tested: openai-codex==0.1.0b1 in requirements.txt.
• Unstable public API. Development Status 4 (beta) means TurnResult field names, ThreadTokenUsage shape, and sandbox preset identifiers may change before 1.0 . Check the Codex changelog before each version bump.
• Heavier install size. The bundled CLI binary adds roughly 50–100 MB depending on platform . The binary layer changes infrequently, so isolate it early in your Docker build to keep CI caches effective.
• full_access documentation gap. The full_access preset documentation was incomplete at launch. Always test agentic loops using this preset inside an isolated container before pointing it at a real repository.
• Stale credential failures. Credentials cached by CLI versions older than v0.132.0 (pre–May 20, 2026 ) may fail silently with the new auth flows. Run codex.login_api_key('sk-...') or the device-code flow explicitly to force a fresh credential set.

Further Experiments: Async, Image Inputs, and Thread Configuration

Once a basic thread is running, these four patterns cover the most productive next steps:

• Async drop-in. Replace Codex with AsyncCodex for integration with FastAPI or any asyncio loop. Lazy initialization keeps import-time overhead low; the rest of the interface is identical.
• Screenshot-to-fix loop. Pass LocalImageInput(path='screenshot.png') alongside a text prompt to thread.run(). Useful for UI regression triage — the model sees the screenshot directly without a written description of the diff.
• Subagent model routing. Use gpt-5.4-mini for high-frequency sub-tasks where latency and cost matter ; reserve gpt-5.4 or gpt-5.5 for the outer planning and reasoning layer.
• Sandbox scoping per task. Pass sandbox='read_only' to thread_start() for safe inspection and explanation tasks; use full_access only in throwaway containers for self-modifying experiments.

The SDK API reference also documents TurnHandle and AsyncTurnHandle for fine-grained mid-flight control: streaming events as they arrive, steering a running turn with updated instructions, or interrupting it outright — relevant for long agentic loops where checkpoints reduce unnecessary token spend.

Frequently Asked Questions

Do I need to install the Codex CLI separately before using the openai-codex Python package?

No. The openai-codex package auto-installs openai-codex-cli-bin as a pinned runtime dependency. The CLI binary is bundled and managed by the SDK — no separate install step is required .

What Python versions does openai-codex v0.1.0b1 support?

Python 3.10, 3.11, 3.12, and 3.13. Python versions below 3.10 are not supported .

How does v0.1.0b1 differ from v0.1.0b2?

Both landed on PyPI on May 28, 2026 . No public release notes distinguish the two at time of writing. Since the SDK tracks CLI versions and each patch bump may adjust bundled binary behavior, the safest practice is to pin whichever version you tested in requirements.txt and upgrade deliberately.

Is openai-codex v0.1.0b1 ready for production?

Development Status 4 (beta) means public APIs are not stable. TurnResult field names, ThreadTokenUsage shape, and sandbox preset identifiers may change before 1.0. Pin the exact version, treat the API surface as unstable, and keep it out of critical production paths until a stable release is tagged.

What is the difference between Codex and AsyncCodex?

Codex is synchronous and context-manager-safe — the right choice for scripts, CLIs, and synchronous frameworks. AsyncCodex is its async counterpart with lazy initialization, designed for asyncio-based frameworks like FastAPI. The thread and turn interfaces are otherwise identical across both classes .

What to Build Next

With a first thread running, the most useful immediate step is to log result.usage and result.duration_ms across a handful of real tasks before adding any complexity. That baseline tells you concretely what switching models or sandbox presets costs in tokens and latency — information that is hard to reconstruct later.

From there, the two patterns worth exploring early are the LocalImageInput vision path for screenshot-driven workflows, and TurnHandle streaming for long agentic loops where mid-flight interruption can save significant token spend. Both are covered in the SDK API reference and the Python SDK repository.

Given that 0.1.0b1 and 0.1.0b2 shipped the same day, the release cadence at this beta stage is fast. Subscribe to the Codex changelog and review it before each version bump — a field rename in TurnResult will not announce itself loudly at runtime.

Last updated: 2026-05-31. Based on openai-codex v0.1.0b1 and Codex CLI v0.135.0 as released May 28, 2026.