codex-sdk-rs 0.1.0

Rust SDK for the OpenAI Codex app server
Documentation

OpenAI Codex SDK for Rust

CI crates.io docs.rs

An async-first Rust port of the public openai-codex Python SDK. It starts codex app-server over stdio, speaks its typed JSON-RPC protocol, routes concurrent turn streams by ID, and provides a blocking facade for direct migration from Python.

This port currently tracks upstream commit f0c30e5. It is not an official OpenAI Rust package.

Installation

cargo add codex-sdk-rs

Requirements

  • Rust 1.85 or newer.
  • A compatible codex executable on PATH, or an explicit CodexConfig::codex_bin.

The Python wheel pins and bundles Codex CLI 0.144.4. Rust crates cannot bundle that platform-specific executable in the same way, so production applications should explicitly manage and pin the CLI version.

Blocking quickstart

The default blocking feature provides the API closest to Python:

use codex_sdk_rs::{Codex, Result};

fn main() -> Result<()> {
    let codex = Codex::with_defaults()?;
    let thread = codex.thread_start()?;
    let result = thread.run("Explain this repository in three bullets.")?;
    println!("{}", result.final_response.unwrap_or_default());
    codex.close()
}

Async quickstart

use codex_sdk_rs::{AsyncCodex, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let codex = AsyncCodex::connect(Default::default()).await?;
    let thread = codex.thread_start().await?;
    let result = thread.run("Explain this repository in three bullets.").await?;
    println!("{}", result.final_response.unwrap_or_default());
    codex.close().await
}

Disable the blocking facade for async-only applications:

[dependencies]
codex-sdk-rs = { version = "0.1", default-features = false }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
tokio-stream = "0.1"

Inputs and options

Plain strings are shorthand for text input. Mixed inputs use InputItem:

use codex_sdk_rs::{
    AsyncCodex, InputItem, ReasoningEffort, Result, Sandbox, TurnOptions,
};

#[tokio::main]
async fn main() -> Result<()> {
    let codex = AsyncCodex::connect(Default::default()).await?;
    let thread = codex.thread_start().await?;
    let result = thread
        .run_with(
            vec![
                InputItem::text("Describe this image."),
                InputItem::local_image("/absolute/path/image.png"),
            ],
            &TurnOptions {
                effort: Some(ReasoningEffort::High),
                sandbox: Some(Sandbox::ReadOnly),
                ..TurnOptions::default()
            },
        )
        .await?;
    println!("{:?}", result.status);
    Ok(())
}

Python keyword arguments map to Rust option structs:

  • thread_start(...) → thread_start_with(&ThreadStartOptions { ... })
  • thread_list(...) → thread_list_with(&ThreadListOptions { ... })
  • thread_resume(...) → thread_resume_with(..., &ThreadResumeOptions { ... })
  • thread_fork(...) → thread_fork_with(..., &ThreadForkOptions { ... })
  • thread.run(...) / thread.turn(...) → run_with / turn_with

Streaming and controls

turn() returns a handle that can be steered, interrupted, streamed, or collected:

use codex_sdk_rs::{AsyncCodex, NotificationPayload, Result};
use tokio_stream::StreamExt;

#[tokio::main]
async fn main() -> Result<()> {
    let codex = AsyncCodex::connect(Default::default()).await?;
    let thread = codex.thread_start().await?;
    let turn = thread.turn("Work incrementally.").await?;
    let mut events = turn.stream()?;

    while let Some(event) = events.next().await {
        if let NotificationPayload::AgentMessageDelta(delta) = event?.payload {
            print!("{}", delta.delta);
        }
    }
    Ok(())
}

One turn handle has one consumable stream, matching the single-consumer behavior of Python's iterator. Separate active turns on the same client are routed independently.

Documentation

Verification

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo test --no-default-features
cargo llvm-cov --all-features --workspace --summary-only --fail-under-lines 98
cargo doc --no-deps --all-features
uv run --no-project python scripts/sync_upstream.py \
  --check \
  --ref f0c30e528a54bdf0fa9a4d52ff74b34383434811

The instrumented suite covers more than 98% of executable source lines and enforces that floor in CI. It exercises the complete public workflow against a deterministic app-server process: initialization, lifecycle RPCs, exact wire options, inputs, login, approvals, routing, concurrent streams, controls, result collection, errors, retry classification, and both sync/async facades. An opt-in authenticated test additionally runs a real model turn through the installed Codex CLI; see TESTING.md.