Codex SDK

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.

If you use Codex through Codex CLI, the IDE extension, or Codex cloud, you can also control it programmatically.

Use the SDK when you need to:

• Control Codex as part of your CI/CD pipeline
• Create your own agent that can engage with Codex to perform complex engineering tasks
• Build Codex into your own internal tools and workflows
• Integrate Codex within your own application

Use the Codex SDK for coding-focused Codex threads. If Codex is one specialist inside a broader orchestrated workflow, run Codex CLI as an MCP server and orchestrate it with the Agents SDK.

If you have beta access and need repository or change scans with structured security findings and coverage, use the Codex Security TypeScript SDK.

TypeScript library

The TypeScript library lets your application start, continue, and resume local Codex threads.

Use the library server-side; it requires Node.js 18 or later.

Installation

To get started, install the Codex SDK using npm:

npm install @openai/codex-sdk

Usage

Start a thread with Codex and run it with your prompt.

const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
  "Make a plan to diagnose and fix the CI failures"
);

console.log(result.finalResponse);

Call run() again to continue on the same thread, or resume a past thread by providing a thread ID.

// running the same thread
const result = await thread.run("Implement the plan");

console.log(result.finalResponse);

// resuming past thread

const threadId = "<thread-id>";
const thread2 = codex.resumeThread(threadId);
const result2 = await thread2.run("Pick up where you left off");

console.log(result2.finalResponse);

For more details, check out the TypeScript repo.

Python library

The Python SDK controls the local Codex app-server over JSON-RPC. It requires Python 3.10 or later. Published SDK builds include a pinned Codex CLI runtime dependency.

Installation

To install the SDK run:

pip install openai-codex

Published SDK builds automatically use their pinned runtime. Pass CodexConfig(codex_bin=...) only when you intentionally want to run against a specific local Codex executable.

While the Python SDK is in beta, pip install openai-codex selects the latest published beta build. After a stable SDK release exists, use pip install --pre openai-codex to opt in to newer prerelease builds.

Usage

Start Codex, create a thread, and run a prompt:

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(
        model="gpt-5.4",
        sandbox=Sandbox.workspace_write,
    )
    result = thread.run("Make a plan to diagnose and fix the CI failures")
    print(result.final_response)

Use AsyncCodex when your application is already asynchronous:

import asyncio

from openai_codex import AsyncCodex


async def main() -> None:
    async with AsyncCodex() as codex:
        thread = await codex.thread_start(model="gpt-5.4")
        result = await thread.run("Implement the plan")
        print(result.final_response)


asyncio.run(main())

Sandbox presets

Use the same Sandbox presets when creating a thread or changing its filesystem access for a later 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: Read files and write inside the workspace and configured writable roots.
• Sandbox.full_access: Run without filesystem access restrictions.

When you omit sandbox=, app-server uses its configured default. A sandbox passed to run(...) or turn(...) applies to that turn and later turns on the thread.

For more details, check out the Python repo.