Skip to main content
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.
ScenarioWhat it is good for
CI/CD automationTrigger code checks, root-cause analysis, fix suggestions, or structured reports in a pipeline.
Automated code reviewRun review tasks in GitHub Actions, GitLab CI/CD, Azure DevOps Pipelines, or Jenkins, then publish findings as code comments.
Internal developer toolsAdd Codex to internal platforms for migration plans, repository analysis, or build failure diagnosis.
In-app engineering assistantStart Codex threads from your application and let Codex handle multi-step engineering tasks.
Structured output workflowsAsk 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

1

Open API Keys

Open the dashboard and go to API Keys.
2

Choose an API Key

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

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

Use the current Base URL shown in the dashboard. Do not copy a fixed address from docs, screenshots, or old config.
Use the model name shown in the dashboard. Copy the full value, including casing, hyphens, and version suffixes.
This is not recommended. Frontend code exposes the API Key. Call the SDK from server-side code, backend jobs, or controlled automation.
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.