What is Codex: OpenAI's coding agent, CLI, IDE and cloud

Codex is OpenAI’s coding agent: it reads your repository, edits files and runs commands, and you can use it from a terminal (Codex CLI), an editor (the Codex IDE extension), the ChatGPT desktop app, or as a cloud agent that works on tasks in isolated environments (openai/codex README, Codex CLI docs). To install the CLI on macOS or Linux:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Applies to: Codex CLI 0.153.2 and OpenAI’s Codex docs as of October 2, 2026. Last checked: October 2, 2026.

On this page

What Codex is today

OpenAI’s documentation describes Codex as a set of clients for one agent, with usage included in ChatGPT plans (Pricing). The openai/codex README says the CLI “is a coding agent from OpenAI that runs locally on your computer,” and points to the other ways to run it: the IDE extension, the desktop app (codex app), and the cloud agent at chatgpt.com/codex.

The CLI is open source under the Apache-2.0 license in the openai/codex repository. The latest stable release on the releases page is 0.153.2, published September 3, 2026.

How to install the Codex CLI

The Codex CLI getting-started page lists four install methods.

macOS and Linux, standalone installer (the same command updates it):

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows, standalone installer:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

npm (install and update):

npm install -g @openai/codex

Homebrew:

brew install --cask codex

Update with Homebrew:

brew upgrade --cask codex

The standalone installer puts the codex command in ~/.local/bin on macOS/Linux and in %LOCALAPPDATA%\Programs\OpenAI\Codex\bin on Windows; CODEX_INSTALL_DIR changes that location (Environment variables). For scripted installs the docs show:

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh

The README also links prebuilt binaries on GitHub Releases, for example codex-aarch64-apple-darwin.tar.gz for Apple Silicon and codex-x86_64-unknown-linux-musl.tar.gz for x86_64 Linux.

How to sign in: ChatGPT account or API key

Codex has two sign-in methods for OpenAI models: Sign in with ChatGPT for subscription access and sign in with an API key for usage-based access. The desktop app, CLI and IDE extension accept both; Codex cloud requires ChatGPT sign-in (Authentication).

1. Open a project directory and run codex. The first time, choose Sign in with ChatGPT or another sign-in method (Codex CLI).

2. Or run the login command directly. With no flags it opens the browser OAuth flow:

   codex login
   

3. To use an API key instead, pipe it through stdin:

   printenv OPENAI_API_KEY | codex login --with-api-key
   

4. On a remote or headless machine, use device code login (beta), which you first enable in your ChatGPT security settings or workspace permissions:

   codex login --device-auth
   

5. Check which method is active, or sign out:

   codex login status
   codex logout
   

Which sign-in to choose

Sources: Authentication, Pricing. The docs recommend API keys for programmatic workflows such as CI/CD. For plan prices and limits, see the plan listings for Codex Plus, Codex Pro and Codex with an API key.

Credentials are cached in ~/.codex/auth.json or the OS credential store. The CLI and IDE extension share the same cached login. OpenAI’s docs say to treat auth.json “like a password: it contains access tokens” (Authentication). The cli_auth_credentials_store key in config.toml sets where credentials go (file, keyring, auto or ephemeral):

# file | keyring | auto | ephemeral
cli_auth_credentials_store = "keyring"

Which models Codex uses

Per the Models page, OpenAI recommends GPT-6.1 Sol (gpt-6.1-sol) for complex coding and agentic work, and GPT-6 Luna (gpt-6-luna) for focused, repeatable tasks. GPT-6 Astra is the option the docs name for the hardest end-to-end work. Availability depends on plan, sign-in method, client and rollout. The pricing page lists GPT-6 Luna for Free and Go (in the desktop app, subject to rollout) and GPT-6 Sol and GPT-6 Luna for Plus.

Switch models inside a CLI session with /model, or at launch:

codex --model gpt-6.1-sol

Set a default in config.toml, which the desktop app, CLI and IDE extension share:

model = "gpt-6.1-sol"

Retirements listed on the Models page:

The page notes that the OpenAI API and Codex used with your own API key are not affected by these ChatGPT-side retirements.

AGENTS.md: project instructions

Codex reads AGENTS.md files before doing any work (Custom instructions with AGENTS.md). Discovery order:

1. Global: in your Codex home (~/.codex unless CODEX_HOME is set), Codex reads AGENTS.override.md if present, otherwise AGENTS.md.
2. Project: from the project root (usually the Git root) down to the current directory, Codex checks each directory for AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames, and takes at most one file per directory.
3. Merge: files are concatenated from the root down, so files closer to your working directory appear later and override earlier guidance.

The combined size stops at project_doc_max_bytes, 32 KiB by default. Example from the docs:

# AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.

To accept a different filename and raise the size limit:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

OpenAI publishes ready-made skills for Codex too; see the OpenAI skills for Codex listing.

Sandbox and approval modes

Two controls decide what Codex can do on your machine (Agent approvals & security, Sandbox):

• Sandbox mode sets the technical boundary: where Codex can write and whether commands can reach the network.
• Approval policy sets when Codex stops and asks you.

The untrusted approval policy is retired; OpenAI says it can prevent the client from starting and should be removed from configuration (Agent approvals & security).

The Auto preset is:

codex --sandbox workspace-write --ask-for-approval on-request

In that preset Codex asks before editing files outside the workspace or running commands that need network access. Inside a session, /permissions opens the permissions picker. Sandboxing is OS-native: Seatbelt on macOS, the native Windows sandbox in PowerShell, and bubblewrap on Linux and WSL2, which the docs ask you to install first:

sudo apt install bubblewrap

Warning

OpenAI describes full access as sandbox_mode = "danger-full-access" together with approval_policy = "never", which “removes the filesystem and network boundaries and should be used only when you want the agent to act with full access” (Sandbox). The documented lower-risk alternatives are the workspace-write + on-request preset, writable_roots to add specific directories, and rules to allow, prompt or forbid specific command prefixes outside the sandbox.

To give commands network access while keeping the sandbox, enable it in config.toml:

[sandbox_workspace_write]
network_access = true

CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"