Codex SDK

The Codex SDK is how your own code drives Codex: install @openai/codex-sdk from npm for TypeScript (server-side, Node.js 18 or later) or openai-codex from pip for Python (3.10 or later), start a thread, and call run() with a prompt (OpenAI docs). OpenAI names four uses: CI/CD pipelines, your own agent that hands engineering work to Codex, internal tools, and Codex inside your application. Two lighter options sit beside it: codex exec, the non-interactive mode of the Codex CLI for scripts and CI, and the GitHub Action openai/codex-action@v1. For a full custom client, with sign-in, history, approvals and streamed events, OpenAI points to the open-source App Server instead.

The TypeScript SDK arrived when Codex became generally available on Oct 6, 2025, alongside the GitHub Action (OpenAI, changelog).

Quick facts

TypeScript

Install with npm install @openai/codex-sdk, then:

import { Codex } from "@openai/codex-sdk";

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 on the same thread to continue, or resume an old thread by its ID with codex.resumeThread(threadId, { sandboxMode: "workspace-write" }). startThread({ threadSource: "ci" }) labels threads your integration creates. Structured settings go in config; raw TOML overrides go in configOverrides and take precedence, and neither changes your Codex config files (OpenAI docs). The code is in the TypeScript folder of the openai/codex repository.

Python

Install with pip install openai-codex. The Python SDK talks to a local Codex App Server over JSON-RPC, and published builds bring their own pinned Codex CLI, so nothing else needs installing:

from openai_codex import Codex, Sandbox

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

AsyncCodex does the same for asynchronous programs. Content from another tool (an issue body, say) can be passed as an ExternalMessage, which Codex treats as tool output, below your own instructions in priority. turn_service_tier sets the speed for one turn (OpenAI docs). The model you name must be available to the signed-in account; leave it out to use your default. More on Codex Models.

codex exec for scripts and CI

codex exec (short form codex e) runs a task and exits, with no interactive screen. Progress goes to stderr and only the final answer to stdout, so the result pipes cleanly:

codex exec "generate release notes for the last 10 commits" | tee release-notes.md

Things worth knowing (Non-interactive mode):

• It starts in a read-only sandbox. Add --sandbox workspace-write to let it edit; use danger-full-access only on an isolated runner or container. --full-auto is no longer supported.
• --json streams every event as JSON Lines (thread.started, turn.completed, item.*, error and more); -o (--output-last-message) writes the final answer to a file.
• --output-schema schema.json asks for a final answer that matches a JSON Schema, for steps that need stable fields.
• Piped input becomes context for the prompt: curl ... | codex exec "format the top 20 items into a markdown table".
• --ephemeral keeps no session files on disk; codex exec resume --last continues the latest run; --worktree runs in a managed Git worktree (Developer commands).
• If an MCP server marked required = true fails to start, codex exec stops with an error.

Credentials in CI. codex exec reuses the CLI's saved sign-in. In other automation, set CODEX_API_KEY only for the Codex command, for example CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports". OpenAI warns against setting OPENAI_API_KEY or CODEX_API_KEY for a whole job that also runs repository code, since build scripts, tests and dependency hooks in that job could read it (Non-interactive mode).

The GitHub Action

For GitHub Actions, OpenAI recommends openai/codex-action@v1 over installing the CLI yourself: it installs Codex, starts a Responses API proxy so the key is less exposed, and runs codex exec with the permissions you set (GitHub Action).

1. Store an OpenAI API key as a repository secret, such as OPENAI_API_KEY.
2. Check out the code before the Codex step.
3. Add a step with uses: openai/codex-action@v1 and the inputs openai-api-key, a prompt or prompt-file, and optionally output-file.
4. Run it on a Linux or macOS runner (Windows needs safety-strategy: unsafe).

OpenAI's sample workflow reviews each new pull request and posts Codex's answer as a comment from a second job with write permission. The action's source is at github.com/openai/codex-action. Codex's built-in pull request reviews, which need no workflow, are on Codex Code Review.

The App Server

codex app-server is the interface Codex itself uses to power rich clients such as the VS Code extension. Use it to build Codex into a product with its own sign-in, chat history, approval prompts and streamed events. It speaks JSON-RPC 2.0 over stdio by default (one JSON message per line) or WebSockets, and is open source in the Codex repository (App Server). It also lets the CLI's terminal screen run on one machine against a server on another (codex app-server --listen ws://127.0.0.1:4500, then codex --remote ws://127.0.0.1:4500); anything beyond localhost needs authentication and TLS. OpenAI's advice: SDK for automation and CI, App Server for deep integrations.

The codex mcp-server command and codex-mcp-server binary, which once let other tools call Codex as an MCP server, were removed on Sep 5, 2026; existing integrations should move to the App Server (Codex SDK, changelog).

Codex Security SDK

Security scanning has a separate library, the Codex Security TypeScript SDK in the public @openai/codex-security package, for running scans and reading findings from your own tools; scans need Codex Security access (Codex Security). See Codex Security.

What does it cost?

The SDK and codex exec use the same sign-in as the CLI. Signed in with ChatGPT, they draw on your plan's Codex usage; with an API key they bill at API prices and can use the models your key reaches, but without cloud features (pricing). The GitHub Action uses an API key. For building agents of your own on OpenAI models rather than driving Codex, see Agents SDK and Responses API.

Frequently asked questions

How do I install the Codex SDK? Run npm install @openai/codex-sdk for TypeScript (Node.js 18 or later, server-side) or pip install openai-codex for Python (3.10 or later). The Python package ships with its own pinned Codex CLI.

What is codex exec? codex exec is the Codex CLI's non-interactive mode: it runs one task, prints the final answer to stdout, and exits, which suits scripts and CI. It starts read-only unless you pass --sandbox workspace-write.

How do I run Codex in GitHub Actions? Use OpenAI's openai/codex-action@v1 with an OpenAI API key stored as a secret and a prompt or prompt file, on a Linux or macOS runner. It installs Codex and runs codex exec for you.

What is the difference between the Codex SDK and the App Server? The Codex SDK is for automating Codex from code and CI; the App Server is the JSON-RPC protocol behind rich clients like the VS Code extension, for products that need their own sign-in, history and approval screens.

Can Codex still run as an MCP server? No. The codex mcp-server command was removed on Sep 5, 2026, and OpenAI points existing integrations to the Codex App Server. Codex can still connect to other MCP servers.

Sources

• Codex SDK, OpenAI docs, read Nov 6, 2026
• Non-interactive mode, OpenAI docs, read Nov 6, 2026
• GitHub Action, OpenAI docs, read Nov 6, 2026
• Codex App Server, OpenAI docs, read Nov 6, 2026
• Developer commands, OpenAI docs, read Nov 6, 2026
• Codex Security, OpenAI docs, read Nov 6, 2026
• Pricing, OpenAI docs, read Nov 6, 2026
• Changelog, OpenAI docs, read Nov 6, 2026
• Codex is now generally available, OpenAI, Oct 6, 2025
• openai/codex, GitHub, read Nov 6, 2026