Codex SDK: run local coding agents from TypeScript or Python

The short answer

Use the Codex SDK when your program needs a stateful local coding-agent thread. TypeScript supports server-side applications on Node.js 18 or later. The stable Python SDK requires Python 3.10 or later and controls the local Codex app-server over JSON-RPC.

Use Codex as an MCP server with the Agents SDK when Codex is one specialist inside a broader agent system. Choose App Server for a custom client that needs the underlying protocol. A one-off script may need only non-interactive CLI mode.

A production flow has six boundaries. Accept a bounded task, start or resume a thread, restrict the workspace, run the turn, verify artifacts and checks, then record the result for review.

Check the current official OpenAI Codex SDK documentation for supported libraries, requirements, and examples.

When the Codex SDK fits

The SDK fits coding work that benefits from conversation state and local repository access. Your application owns the trigger, policy, storage, user experience, and review path while Codex performs the bounded engineering task.

• CI or internal automation that diagnoses a failure and proposes a reviewed change.
• A developer tool that starts a coding task from an issue, alert, or approved form.
• A workflow that needs several turns on the same repository and thread.
• An application that needs the final response and structured lifecycle inside its own service.
• A controlled migration, maintenance, or code-review assistant with explicit verification.

When another Codex surface is simpler

• Run Codex CLI directly for interactive local work by a developer.
• Choose non-interactive mode for a small command-line or CI task that does not need an application library.
• Pick the GitHub Action when the workflow begins and ends inside GitHub Actions.
• Choose Codex as an MCP server when a broader Agents SDK workflow should call it as one specialist.
• Build on App Server when a custom client needs protocol-level events and controls.

OpenAI's App Server documentation describes the JSON-RPC interface beneath custom Codex clients.

Understand the thread lifecycle

A thread holds the ongoing Codex interaction. Create one for new work. Run another turn on that thread when the next instruction depends on its context. Persist the thread identifier if an approved later process must resume it.

1. 1Create the Codex client in a server-side process.
2. 2Open a thread with the required model, sandbox, and working context.
3. 3Run a narrow prompt with acceptance criteria and expected verification.
4. 4Inspect the final response, changed files, command output, and process status.
5. 5Continue the same thread only when prior context is useful and still trustworthy.
6. 6Store the thread identifier with access controls, task metadata, and retention rules.
7. 7Resume a past thread only after confirming the repository and policy state still match.

TypeScript library

The official TypeScript library is `@openai/codex-sdk`. OpenAI documents it for server-side use on Node.js 18 or later. Its core flow creates a `Codex` client, starts a thread, and calls `run()` with a prompt.

• Call `run()` again to continue work on the same thread.
• Use `resumeThread()` with a stored thread identifier to reopen past work.
• Treat `finalResponse` as one output to review, not proof that repository work is correct.
• Keep the SDK in trusted server code rather than exposing local agent control in a browser bundle.

Python library

The stable Python package is `openai-codex` and requires Python 3.10 or later. It controls the local Codex app-server over JSON-RPC. Published builds include a pinned Codex CLI runtime dependency.

• Use `Codex` in synchronous programs and `AsyncCodex` in an existing asynchronous application.
• Create the thread, set its model and sandbox where needed, then run a bounded prompt.
• Keep the pinned runtime by default so the SDK and local protocol stay aligned.
• Provide a specific Codex executable only when the integration intentionally controls that compatibility risk.

Set the smallest filesystem boundary

The Python SDK exposes read-only, workspace-write, and full-access sandbox presets. Read-only permits file inspection without writes. Workspace-write permits changes inside the workspace and configured writable roots. Full access removes filesystem restrictions and needs a stronger justification.

• Begin discovery and review turns in read-only mode.
• Use workspace-write only for an approved change inside a prepared checkout.
• Avoid full access for ordinary repository tasks.
• Pass a narrower sandbox for later review turns when writes are no longer needed.
• Remember that a sandbox passed to a Python turn applies to that turn and later turns on the thread.

Separate orchestration from agent authority

The surrounding service should decide who can trigger work and which repository revision is in scope. It should also control credentials and approvals. Codex should receive only the access required for the task.

• Use a fresh checkout or worktree for each write-capable job.
• Pin the base revision and reject a stale job when repository state changes.
• Keep production secrets, deployment credentials, and unrelated home-directory data outside the environment.
• Allow network destinations only when the task and dependency policy require them.
• Set time, turn, output, concurrency, and spend limits in the surrounding worker.
• Capture cancellation and process failure rather than waiting without a deadline.

Verify the work outside the final response

An agent can report success while a command failed, a test was skipped, or a diff exceeded scope. Make repository evidence the acceptance boundary.

1. 1Inspect the exact changed files and reject unrelated edits.
2. 2Run formatting, lint, type checks, tests, and builds required by the repository.
3. 3Record exit codes and keep important command output with the job.
4. 4Check generated files, lockfiles, migrations, permissions, and dependency changes separately.
5. 5Require human review before merge, deployment, publication, or another external side effect.
6. 6Clean or preserve the worktree according to the audit and retry policy.

A small production architecture

1. 1An authenticated API accepts a task, repository reference, and declared outcome.
2. 2A policy layer validates identity, scope, limits, and required approvals.
3. 3A queue gives one worker an idempotent job and an isolated checkout.
4. 4The worker starts or resumes a Codex thread with the chosen sandbox.
5. 5A verifier runs repository checks and summarizes evidence.
6. 6The service stores thread, revision, logs, costs, artifacts, and review state.
7. 7A person accepts, rejects, retries, or promotes the result through a separate action.

Implementation checklist

• The SDK surface matches the workflow rather than a simpler CLI or GitHub integration.
• Runtime and package versions follow current official OpenAI documentation.
• Thread identifiers are treated as controlled application state.
• Repository scope, sandbox, network, credentials, and approvals are explicit.
• Jobs are idempotent and have time, concurrency, retry, and cancellation limits.
• Verification reads repository evidence instead of trusting prose alone.
• Logs and artifacts redact secrets and follow a retention policy.
• A human controls merge, deployment, publication, and other material side effects.

Install and verify the supported local client before embedding it with Better Design's OpenAI Codex setup guide.

In summary

The Codex SDK embeds stateful local coding-agent threads in a trusted server workflow. Choose TypeScript or Python, use the smallest sandbox, preserve thread state carefully, verify repository evidence, and keep authority for external actions outside the agent turn.

Frequently asked questions