mirror of https://github.com/openai/codex.git synced 2026-05-30 07:50:17 +00:00

Files

Ahmed Ibrahim 0db49a7e6a [codex] Rename Python SDK AppServerConfig to CodexConfig (#24800 )

## Why

`AppServerConfig` is exported as part of the ergonomic Python SDK
surface and passed to `Codex(...)` and `AsyncCodex(...)`. That name
exposes the underlying app-server transport at the same layer where
users are configuring the Codex client. `CodexConfig` makes the common
callsite read naturally and names the object it configures.

## What changed

- Renamed the public configuration dataclass from `AppServerConfig` to
`CodexConfig`.
- Updated `Codex`, `AsyncCodex`, and the transport clients to accept
`CodexConfig`.
- Updated binary-resolution messages, package exports, docs, examples,
and related coverage to use the new public name.

## API impact

```python
from openai_codex import Codex, CodexConfig

with Codex(config=CodexConfig(codex_bin="/path/to/codex")) as codex:
    ...
```

Callers should now import and construct `CodexConfig`; `AppServerConfig`
is no longer part of the Python SDK surface.

## Validation

- `uv run --frozen --extra dev ruff check src/openai_codex scripts
examples tests`
- Tests are deferred to online CI for this PR.

2026-05-27 16:10:15 -07:00

4.2 KiB

Raw Blame History

OpenAI Codex Python SDK (Experimental)

Experimental Python SDK for codex app-server JSON-RPC v2 over stdio, with a small default surface optimized for real scripts and apps.

The generated wire-model layer is sourced from the pinned openai-codex-cli-bin runtime package and exposed as Pydantic models with snake_case Python fields that serialize back to the protocol's camelCase wire format. The package root exports the ergonomic client API; public Codex protocol value and event types live in openai_codex.types.

Install

cd sdk/python
uv sync
source .venv/bin/activate

Published SDK builds pin an exact openai-codex-cli-bin runtime dependency with the same version as the SDK. Pass CodexConfig(codex_bin=...) only when you intentionally want to run against a specific local app-server binary.

Quickstart

from openai_codex import Codex, Sandbox

with Codex() as codex:
    # Call login_api_key(...) first when this Codex session is not
    # already authenticated.
    thread = codex.thread_start(model="gpt-5", sandbox=Sandbox.workspace_write)
    result = thread.run("Say hello in one sentence.")
    print(result.final_response)
    print(len(result.items))

thread.run(...) and thread.turn(...).run() return TurnResult. Its final_response is None when the turn completes without a final-answer or phase-less assistant message item.

Sandbox

Use the same enum when creating a thread or changing its sandbox for a turn:

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(sandbox=Sandbox.workspace_write)
    thread.run("Make the requested change.")
    review = thread.run("Review the diff only.", sandbox=Sandbox.read_only)

Available presets:

Sandbox.read_only: read files without allowing writes.
Sandbox.workspace_write: the normal default for projects with a recorded trust decision; read files and write inside the workspace and configured writable roots.
Sandbox.full_access: run without filesystem access restrictions.

When sandbox= is omitted, Codex uses its configured default. A sandbox passed to run(...) or turn(...) applies to that turn and subsequent turns on the thread.

Use the auth helper that matches your app:

from openai_codex import Codex

with Codex() as codex:
    codex.login_api_key("sk-...")
    account = codex.account()
    print(account.account)

Interactive ChatGPT login returns a handle. Open the provided URL or device-code page, then wait for the matching completion event:

with Codex() as codex:
    login = codex.login_chatgpt()
    print(login.auth_url)
    completed = login.wait()
    print(completed.success)

Use login_chatgpt_device_code() for device-code auth, handle.cancel() to stop an in-progress interactive login, and logout() to clear the active Codex account session.

Docs map

Golden path tutorial: docs/getting-started.md
API reference (signatures + behavior): docs/api-reference.md
Common decisions and pitfalls: docs/faq.md
Runnable examples index: examples/README.md
Jupyter walkthrough notebook: notebooks/sdk_walkthrough.ipynb

Examples

Start here:

cd sdk/python
python examples/01_quickstart_constructor/sync.py
python examples/01_quickstart_constructor/async.py

Runtime

Published SDK builds are pinned to an exact openai-codex-cli-bin package version, and that runtime package carries the platform-specific binary for the target wheel. The SDK package version and runtime package version must match.

Compatibility and versioning

Package: openai-codex
Runtime package: openai-codex-cli-bin
Python: >=3.10
Target protocol: Codex app-server JSON-RPC v2
Versioning rule: the SDK package version is the underlying Codex runtime version

Notes

Codex() is eager and performs startup + initialize in the constructor.
Use context managers (with Codex() as codex:) to ensure shutdown.
Plain strings are accepted anywhere a turn input is accepted; they are shorthand for TextInput(...).
Prefer thread.run("...") for the common case. Use thread.turn(...) when you need streaming, steering, or interrupt control.
For transient overload, use retry_on_overload from the package root.

4.2 KiB Raw Blame History