Codex SDK

Codex SDK is for integrating Codex into your own app, internal tool, or automation workflow. Copy the Base URL, API Key, and model name from the dashboard, then pass the connection values when you instantiate Codex.

Use the Base URL, API Key, and model name shown in the dashboard. Do not copy these values from screenshots, old docs, or another user’s config.

Prerequisites

You have completed Create an account.
You have completed Get an API Key.
Node.js 18 or later is installed.
Codex CLI is installed and codex --version works.
You have a TypeScript or JavaScript project.

An API Key is a sensitive credential. Do not put it in frontend code, commit it to a repository, or print it in logs.

Use cases

Codex SDK is useful when you need to place Codex inside an existing engineering workflow.

Scenario	What it is good for
CI/CD automation	Trigger code checks, root-cause analysis, fix suggestions, or structured reports in a pipeline.
Automated code review	Run review tasks in GitHub Actions, GitLab CI/CD, Azure DevOps Pipelines, or Jenkins, then publish findings as code comments.
Internal developer tools	Add Codex to internal platforms for migration plans, repository analysis, or build failure diagnosis.
In-app engineering assistant	Start Codex threads from your application and let Codex handle multi-step engineering tasks.
Structured output workflows	Ask Codex for JSON schema output, then call your SCM, Slack, ticketing system, or internal APIs.

If you only want to use 4096bytes from a local terminal, start with Codex CLI. Use the SDK when you need to control Codex from code.

Install the SDK

Install Codex SDK in your project.

npm install @openai/codex-sdk

Codex SDK calls the local Codex CLI. If Codex CLI is not installed, install it first:

npm install -g @openai/codex

After installation, verify the command:

codex --version

If you use pnpm or yarn, use the matching command.

pnpm add @openai/codex-sdk

yarn add @openai/codex-sdk

Copy connection values

Open API Keys

Open the dashboard and go to API Keys.

Choose an API Key

Find the API Key you want to use with the SDK, then click Use key.

Copy SDK values

Copy the Base URL, API Key, and model name shown in the dashboard. Replace every placeholder in the example with the live dashboard value.

Configure environment variables

Store the API Key, Base URL, and model name in server-side environment variables.

export CODEX_API_KEY="YOUR_4096BYTES_API_KEY"
export CODEX_BASE_URL="YOUR_BASE_URL"
export CODEX_MODEL="YOUR_MODEL_NAME"

If your runtime uses a .env file, write:

CODEX_API_KEY=YOUR_4096BYTES_API_KEY
CODEX_BASE_URL=YOUR_BASE_URL
CODEX_MODEL=YOUR_MODEL_NAME

Initialize Codex

Create a Codex instance in server-side code. Pass apiKey and baseUrl to the constructor.

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

const apiKey = process.env.CODEX_API_KEY;
const baseUrl = process.env.CODEX_BASE_URL;
const model = process.env.CODEX_MODEL;

if (!apiKey || !baseUrl || !model) {
  throw new Error("Missing CODEX_API_KEY, CODEX_BASE_URL, or CODEX_MODEL");
}

const codex = new Codex({
  apiKey,
  baseUrl,
});

const thread = codex.startThread({
  model,
});

const result = await thread.run("Describe the purpose of this project in one sentence.");

console.log(result.finalResponse);

Set CODEX_API_KEY to the API Key you created in the dashboard. Copy CODEX_BASE_URL and CODEX_MODEL from the dashboard.

Verify the connection

Start with a read-only prompt.

const result = await thread.run("Reply with ok only. Do not modify any files.");

After the response works, connect the SDK to your real workflow.

Code review example

OpenAI’s official cookbook shows an automated code review workflow. The workflow triggers Codex in a CI/CD runner, has Codex read the PR diff, asks for structured JSON schema output, and then calls the SCM API to publish inline comments. You can use this pattern for:

Automated PR review.
Review workflows for on-premise repositories or non-GitHub SCMs.
Creating tickets, sending Slack notifications, or updating internal quality dashboards from structured results.

Start with read-only review tasks. After the output is stable, connect comment publishing, ticket creation, or other actions that change external state. Official example: Build Code Review with the Codex SDK. For more SDK usage, see the official OpenAI docs: Codex SDK.

Common issues

Which Base URL should I use

Use the current Base URL shown in the dashboard. Do not copy a fixed address from docs, screenshots, or old config.

Which model name should I use

Use the model name shown in the dashboard. Copy the full value, including casing, hyphens, and version suffixes.

Can I call it from browser frontend code

This is not recommended. Frontend code exposes the API Key. Call the SDK from server-side code, backend jobs, or controlled automation.

Authentication failed

Check that the API Key was copied completely, the runtime can read the environment variables, and the Base URL belongs to the same dashboard account or environment.

Quickstart

Clients

SDKs

Prerequisites

Use cases

Install the SDK

Copy connection values

Configure environment variables

Initialize Codex

Verify the connection

Code review example

Common issues

​Prerequisites

​Use cases

​Install the SDK

​Copy connection values

​Configure environment variables

​Initialize Codex

​Verify the connection

​Code review example

​Common issues

Prerequisites

Use cases

Install the SDK

Copy connection values

Configure environment variables

Initialize Codex

Verify the connection

Code review example

Common issues