Codex Runtime

codex-runtime is a Rust wrapper around the local codex app-server, the stdio JSON-RPC backend started by the codex CLI.

Repository identity:

• repository and crate: codex-runtime
• Rust import path: codex_runtime
• current crate version: 0.6.2

The project is intentionally layered so callers can start with one prompt and move down only when they need more control.

Install

Requires codex CLI >= 0.104.0 on $PATH.

Published crate:

[dependencies]
codex-runtime = "0.6.2"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Workspace path:

[dependencies]
codex-runtime = { path = "crates/codex-runtime" }

Safe Defaults

All high-level entry points share the same baseline unless you opt out:

Privileged execution must be enabled explicitly. Tool-use hooks do not bypass sandbox or approval policy.

Quick Start

One-shot prompt

use codex_runtime::quick_run;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let out = quick_run("/abs/path/workdir", "Summarize this repo in 3 bullets").await?;
    println!("{}", out.assistant_text);
    Ok(())
}

Reusable workflow

use codex_runtime::{Workflow, WorkflowConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let workflow = Workflow::connect(
        WorkflowConfig::new("/abs/path/workdir")
            .with_model("gpt-4o")
            .attach_path("docs/API_REFERENCE.md"),
    )
    .await?;

    let out = workflow.run("Summarize only the public API").await?;
    println!("{}", out.assistant_text);

    workflow.shutdown().await?;
    Ok(())
}

Explicit client and session

use codex_runtime::runtime::{Client, SessionConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::connect_default().await?;
    let session = client
        .start_session(SessionConfig::new("/abs/path/workdir"))
        .await?;

    let first = session.ask("Summarize the current design").await?;
    let second = session.ask("Reduce that to 3 lines").await?;

    println!("{}", first.assistant_text);
    println!("{}", second.assistant_text);

    session.close().await?;
    client.shutdown().await?;
    Ok(())
}

Scoped streaming

use codex_runtime::runtime::{Client, PromptRunStreamEvent, SessionConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::connect_default().await?;
    let session = client
        .start_session(SessionConfig::new("/abs/path/workdir"))
        .await?;

    let mut stream = session.ask_stream("Explain the current module boundaries").await?;

    while let Some(event) = stream.recv().await? {
        if let PromptRunStreamEvent::AssistantMessageDelta(delta) = event {
            print!("{delta}");
        }
    }

    let final_result = stream.finish().await?;
    println!("\nturn={} text={}", final_result.turn_id, final_result.assistant_text);

    session.close().await?;
    client.shutdown().await?;
    Ok(())
}

Session::ask_wait(prompt) is the convenience path for ask_stream(...).finish().await when you do not need manual event handling.

Automation

use std::time::{Duration, SystemTime};

use codex_runtime::automation::{spawn, AutomationSpec};
use codex_runtime::runtime::{Client, SessionConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::connect_default().await?;
    let session = client
        .start_session(SessionConfig::new("/abs/path/workdir"))
        .await?;

    let handle = spawn(
        session,
        AutomationSpec {
            prompt: "Keep reducing the backlog one item at a time".to_owned(),
            start_at: Some(SystemTime::now() + Duration::from_secs(60)),
            every: Duration::from_secs(1800),
            stop_at: Some(SystemTime::now() + Duration::from_secs(8 * 3600)),
            max_runs: None,
        },
    );

    let status = handle.wait().await;
    println!("{status:?}");
    client.shutdown().await?;
    Ok(())
}

Automation contract:

• one prepared Session per runner
• fixed Duration cadence only
• one turn in flight at a time
• missed ticks collapse into one next eligible run
• any PromptRunError is terminal
• no cron parsing, persistence, or restart recovery in v1

Public Modules

Root crate exports include:

• quick_run, quick_run_with_profile, QuickRunError
• Workflow, WorkflowConfig
• AppServer, rpc_methods
• HookMatcher, FilteredPreHook, FilteredPostHook, ShellCommandHook
• automation, plugin, runtime, web, artifact

Runtime Contracts

• High-level builders stay intentionally smaller than raw upstream payloads.
• Stable upstream fields graduate into typed APIs first.
• Experimental or custom methods remain available through raw JSON-RPC.
• Validation is strict in typed paths and only relaxed when callers explicitly choose raw mode.
• Detached cleanup and validation paths are kept data-first where practical so side effects stay at the outer boundary.

Hooks

Hooks let you intercept lifecycle phases without forking the runtime call path.

Phases:

• PreRun, PostRun
• PreSessionStart, PostSessionStart
• PreTurn, PostTurn
• PreToolUse, PostToolUse

Key rules:

• pre-hooks can mutate or block
• post-hooks observe outcomes and issue reports
• tool-use hooks run inside approval-gated command/file-change handling
• hook logic sits on top of sandbox and approval policy, not instead of it

Documentation

• docs/API_REFERENCE.md: public API and contract reference
• docs/TEST_TREE.md: test layers and release-gate boundaries
• docs/README.md: documentation index
• CHANGELOG.md: release history

Quality Gates

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Opt-in real-server tests:

CODEX_RUNTIME_REAL_SERVER_APPROVED=1 \
cargo test -p codex-runtime ergonomic::tests::real_server:: -- --ignored --nocapture

License

MIT