Codex CLI: OpenAI's open-source terminal coding agent

What Codex CLI is

Codex CLI is OpenAI's coding agent for the terminal. The README describes it as "a coding agent from OpenAI that runs locally on your computer": it reads a repository, plans changes, edits files and runs the tools already installed on the machine, all from a terminal UI. The client is open source under Apache-2.0 and lives in the openai/codex repository, while the models it talks to are OpenAI's hosted models, reached either through a ChatGPT plan or an API key.

The same repository sits at the centre of a wider family. The README points to an IDE extension for VS Code, Cursor and Windsurf, a desktop app experience launched with codex app, and Codex Web, the cloud-based agent at chatgpt.com/codex, which is a separate product. This page covers the open-source CLI.

The docs list three reasons to use it: work against a local repository with the tools already on the machine, stay in control of model, reasoning effort, permissions and commands, and compose Codex with scripts and CI through a non-interactive mode. It targets individual developers who want an agent in their terminal and teams who want to automate review, triage or release chores in pipelines.

How it works

The CLI is written in Rust; the source lives in a Cargo workspace under codex-rs. Running codex in a project directory opens an interactive TUI where you describe a task, watch commands and diffs as they appear, steer the active turn and keep follow-up work in the same session. Sessions are saved locally and can be reopened with codex resume.

Two layers govern what the agent may do. The sandbox mode defines what is technically possible when model-generated commands run, such as where they can write and whether they can reach the network; on the CLI and IDE extension it is enforced by OS-level mechanisms. The approval policy decides when Codex must stop and ask before acting. The security docs state that by default the agent runs with network access turned off and write access limited to the active workspace. In the "Auto" preset (--sandbox workspace-write --ask-for-approval on-request) Codex can read, edit and run commands in the working directory without asking, but needs approval to edit outside the workspace or to use the network. A read-only mode, reachable through the /permissions command, lets you chat and plan without changes.

Project context comes from AGENTS.md files. At startup Codex builds an instruction chain: a global file in the Codex home directory (~/.codex unless CODEX_HOME is set), then one file per directory from the project root down to the current directory, with AGENTS.override.md taking precedence over AGENTS.md at each level. Files closer to the working directory appear later and therefore override earlier guidance, and the combined size is capped by project_doc_max_bytes, 32 KiB by default.

Key features

• Interactive terminal loop: explore unfamiliar code, plan, edit and run local dev tools while seeing each command and diff.
• Session resume: codex resume reopens a recent chat from the current repository or searches older local chats.
• Image input: codex --image attaches a screenshot, diagram or design reference to the first prompt, or images can be pasted into the composer.
• Subagents: delegate focused parts of a larger investigation to specialised agents and bring their findings back to the main session.
• Live web search: codex --search enables web search for tasks that depend on current documentation or releases, with activity visible in the transcript.
• Cloud hand-off: codex cloud submits work to a configured Codex cloud environment and applies results locally.
• MCP support: codex mcp adds local or remote MCP servers and shows their tools before Codex uses them.
• Local code review: review uncommitted changes, a commit or a base branch; Codex reports prioritised findings without modifying the working tree.
• Skills and plugins: package repeatable instructions as skills and connect team tools through plugins.
• Non-interactive mode: codex exec runs a task from scripts or CI and prints only the final message to stdout.
• Granular network policy: an optional proxy feature constrains outbound traffic to allow and deny rules per domain.
• Shell completion and theming: codex completion generates completions, and longer prompts can open in the editor set by VISUAL or EDITOR.

Getting started

The README gives a standalone installer for macOS and Linux and one for Windows:

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

The installers download from releases.openai.com by default and fall back to GitHub Releases; setting CODEX_INSTALLER_USE_RELEASES_OPENAI_COM to false forces GitHub. npm and Homebrew are also supported:

npm install -g @openai/codex
brew install --cask codex

Then run codex in a project directory and choose Sign in with ChatGPT, which the README recommends for using Codex as part of a Plus, Pro, Business, Edu or Enterprise plan. API-key sign-in is also supported; the authentication docs show piping the key into codex login --with-api-key, and API usage is billed at standard API rates. Prebuilt archives for macOS (Apple silicon and x86_64) and Linux (x86_64 and arm64, musl builds) are attached to each GitHub release, along with a DotSlash file that lets a repository pin one Codex version for every contributor.

The installation guide lists system requirements of macOS 12+, Ubuntu 20.04+ or Debian 10+, or Windows 11 via WSL2, with 4 GB of RAM minimum and 8 GB recommended, and Git 2.23+ optional for built-in PR helpers. Building from source uses the Rust toolchain:

git clone https://github.com/openai/codex.git
cd codex/codex-rs
cargo build
cargo run --bin codex -- "explain this codebase to me"

Sandbox, approvals and network access

The security documentation goes further than most agent tools in spelling out its trust boundaries, and it is worth reading before giving Codex write access to important repositories. In the default workspace-write mode, command network access stays off unless enabled in configuration with network_access = true under [sandbox_workspace_write]. When network access is on, an optional network_proxy feature constrains outbound traffic with domain rules: exact hosts, *.example.com for subdomains only, **.example.com for apex plus subdomains, and deny rules that always win over allow rules. Enabling the proxy does not grant network access by itself; it only changes how access that is already enabled is enforced.

Local and private destinations are blocked by default (allow_local_binding = false), including hostnames that resolve to private IPs. Codex performs a best-effort DNS classification check to reduce DNS rebinding risk, and the docs state plainly that this does not eliminate it, recommending lower-layer egress controls if hostile DNS is a concern. Two settings, dangerously_allow_non_loopback_proxy and dangerously_allow_all_unix_sockets, deliberately widen the boundary and are meant only for tightly controlled environments.

Codex can also ask for approval before calling app or MCP tools that advertise side effects, and tools annotated as destructive always require approval. The docs describe asynchronous safety monitoring that can pause a task if it detects potentially unsafe model behaviour; on the CLI, full findings and resume are not available, so such a task simply ends.

Automation with codex exec

codex exec is the scripting interface. Progress streams to stderr and only the final agent message goes to stdout, so output can be piped into files or other tools. If stdin is piped alongside a prompt argument, the prompt is treated as the instruction and the piped content as context. --json turns stdout into a JSON Lines stream of events such as thread.started, turn.completed and item events for commands, file changes, MCP calls and web searches. --output-schema requests a final answer that conforms to a JSON Schema, and -o writes the final message to a file. --ephemeral avoids persisting session files to disk.

By default codex exec runs in a read-only sandbox; --sandbox workspace-write allows edits, and danger-full-access is meant only for isolated CI runners or containers. For GitHub Actions the docs recommend the Codex GitHub Action and warn against setting OPENAI_API_KEY or CODEX_API_KEY as job-level environment variables in workflows that run repository-controlled code, because build scripts, tests or dependency hooks could read them.

Configuration and permission profiles

User settings live in config.toml under the Codex home directory, and any key can be overridden for a single run with -c, for example -c 'sandbox_workspace_write.network_access=true'. Beyond the built-in sandbox modes, the security docs describe named permission profiles: a default_permissions key selects a profile, a profile can extend the built-in :workspace profile, and each profile can enable network access and list allowed domains, which are enforced when the network_proxy feature is on. A per-project trust_level = "untrusted" entry makes commands require approval unless an execution-policy rule allows them, and it also disables project-local configuration.

For managed fleets, administrators can set policy in a requirements.toml file. The repository's configuration notes call out one example: allow_managed_hooks_only = true ignores user, project and session lifecycle hook configs while still allowing managed hooks, and it only works in requirements.toml, not in config.toml. In automation, --ignore-user-config skips the user's config.toml, --ignore-rules skips execpolicy .rules files, and an MCP server marked required = true makes codex exec exit with an error if it fails to start.

For debugging, Codex honours the standard Rust RUST_LOG variable. The TUI keeps diagnostics in bounded local stores by default, and setting log_dir writes a plaintext codex-tui.log for a run; codex exec defaults to RUST_LOG=error and prints messages inline.

Use cases

• Exploring an unfamiliar codebase: ask for an explanation of the project structure, then follow up on specific modules in the same session.
• Focused changes with review: let Codex make a scoped edit in workspace-write mode, inspect the diff, and run a local review against the base branch before committing.
• CI automation: generate release notes from recent commits, summarise risky areas, or produce structured JSON reports with codex exec and an output schema.
• Team conventions: encode test commands, package-manager preferences and review rules in layered AGENTS.md files so every run starts with the same expectations.
• Tool-connected workflows: add MCP servers so the agent can read from issue trackers or internal services while staying inside approval rules.

How it compares

The README itself draws the main distinction: Codex CLI runs locally on your machine, while Codex Web is OpenAI's cloud-based agent, and the CLI can hand work to the cloud with codex cloud. Against other terminal coding agents, the practical comparison points are the model ecosystem each is tied to, how sandboxing is enforced (Codex documents OS-level enforcement with network off by default), how project instructions are discovered, and how well the tool scripts into CI. Codex's open-source client and documented JSONL event stream make it easier to audit and integrate than a closed binary, but the inference itself remains a hosted OpenAI service.

Things to know before adopting

• Open client, hosted models: the CLI is Apache-2.0, but it depends on OpenAI's hosted models and either a ChatGPT plan or API billing. Data handling follows the sign-in method: ChatGPT workspace settings for ChatGPT sign-in, API organisation settings for API keys.
• Fast release cadence: releases are tagged as rust-v0.x with frequent alpha builds; rust-v0.166.0 shipped on 29 October 2026. The project is pre-1.0 and options change.
• Breaking configuration changes: the docs say approval_policy = "untrusted" is no longer supported and can prevent the client from starting, and --full-auto is no longer supported in codex exec; older scripts and config files need updating.
• Windows: the README provides a native PowerShell installer, while the installation guide's requirements table still lists Windows 11 via WSL2; check current docs for your setup.
• Installer scripts: the recommended install pipes a remote script into a shell; npm, Homebrew, release archives or source builds are alternatives.
• Security boundaries: full-access sandbox modes, network enablement and the "dangerously" settings widen what the agent can reach. The DNS rebinding protection is best-effort by the docs' own account.
• Checkpoints: the getting-started guide recommends creating Git checkpoints before and after a task so changes can be reverted.

Project activity

As of November 2026 the repository has about 133,000 stars and around 21,000 forks. It was created in April 2025, is written mainly in Rust, and is licensed under Apache-2.0. Releases ship several times a week, and the repository documents an open source fund alongside its contributing guide. The source is at github.com/openai/codex, and documentation is at developers.openai.com/codex.

[![Featured on TechLogHub](https://techloghub.com/badge-neutral.svg)](https://techloghub.com/open-source/openai-codex-cli?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)