Codex CLI: Setup, Sandbox Modes, and Verifying Its Output

What Is Codex CLI?

Codex CLI is OpenAI's open-source coding agent that runs in a terminal. It is written in Rust, published under the Apache-2.0 licence, and works against a local Git repository: it reads files, proposes and applies edits, runs shell commands, and pauses for approval according to a sandbox policy you set. That plan-act-observe loop is what makes it agentic AI rather than autocomplete.

The openai/codex repository is public and carries the Apache-2.0 licence in its repository metadata.

That matters practically rather than ideologically: you can read exactly what the agent does before it touches a production checkout, and you can pin a release rather than tracking whatever the install script last fetched.

Codex is one product with several surfaces, and the CLI is the local one.

• Codex CLI - runs on your machine against your working tree, so it sees uncommitted changes, your local toolchain, and your environment variables.
• Codex cloud - runs the task in an OpenAI-hosted environment. The CLI hands work over with codex cloud, which suits long jobs you do not want to hold a terminal open for.
• The IDE extension - the same agent inside an editor, with its own MCP server menu rather than the CLI config file.

If you are still deciding which terminal agent to standardise on, the wider category comparison lives in our roundup of agentic coding CLI tools. This article assumes the decision is made and gets Codex CLI working properly.

How to Install Codex CLI and Run Your First Task

Check the requirements before the install command, because the Windows answer surprises people. The repository's install documentation lists macOS 12 or later, Ubuntu 20.04 or later, Debian 10 or later, or Windows 11 through WSL2, with Git 2.23 or later recommended for the built-in pull-request helpers and 4 GB of RAM as the minimum, 8 GB recommended.

Three install paths are supported. Pick one and stay on it, because mixing npm and Homebrew installs leaves two binaries on your PATH.

# npm, if you already manage global Node packages
npm install -g @openai/codex

# Homebrew on macOS
brew install --cask codex

# install script for macOS and Linux (also the update path)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

Re-running the install script is how you update, and you will run it often. This is the query I ran against the releases API to get the cadence figures quoted above, and its output on 27 August 2026.

$ curl -s "https://api.github.com/repos/openai/codex/releases?per_page=100" \
  | jq -r '.[] | select(.tag_name | test("^rust-v[0-9]+\\.[0-9]+\\.[0-9]+$"))
           | "\(.tag_name)  \(.published_at[0:10])"'

rust-v0.150.1  2026-08-27
rust-v0.150.0  2026-08-26
rust-v0.149.1  2026-08-24
rust-v0.149.0  2026-08-20
rust-v0.148.0  2026-08-18
rust-v0.147.0  2026-08-07
rust-v0.146.1  2026-08-05
rust-v0.146.0  2026-07-29

Eight stable tags in thirty days is the update cadence you are signing up for. Pin a version in CI rather than tracking latest, or a pipeline that passed on Monday can behave differently on Friday.

Then start a session in the repository you want to work on. The first run walks you through sign-in; after that, five slash commands cover most of what you need.

• /init - writes a starter AGENTS.md into the repository so Codex has project context on every later run.
• /status - prints the current session setup, which is the fastest way to confirm which model and permissions are actually live.
• /permissions - sets what Codex may do without asking, per session.
• /model - switches model and reasoning effort mid-session.
• /review - has Codex inspect the current changes and report problems before you commit them.

Two more commands are worth knowing on day one: codex resume reopens a recent conversation instead of restarting from cold, and codex --search enables live web search for the session. If you are wondering how much headroom a plan gives you before any of this starts erroring, we cover reading the counters in how to check your Codex usage limits.

Codex CLI Sandbox and Approval Modes

Two independent settings decide how much rope the agent gets. sandbox_mode controls what it is technically able to touch; approval_policy controls when it stops and asks you. Getting them confused is the most common way people end up either approving every single command or handing over far more access than they meant to.

The values below come from the OpenAI Codex configuration reference.

Read the two together rather than separately. approval_policy = "never" with sandbox_mode = "read-only" is a perfectly reasonable configuration for a research task, because nothing can be damaged. The same approval policy with danger-full-access is an unattended agent with root-equivalent reach over your machine.

# ~/.codex/config.toml - a sane interactive default
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

[sandbox_workspace_write]
network_access = false

Leaving network_access at false is the setting most worth keeping. It means a dependency install has to be an explicit decision rather than something the agent quietly does mid-task, which keeps supply-chain surprises out of an unattended run.

Steering Codex CLI with AGENTS.md

AGENTS.md is where your working agreements live: run this test command, prefer this package manager, never add a production dependency without asking. Codex reads these files before it does any work, and it builds an instruction chain once per run.

Discovery follows a documented precedence order, set out in the OpenAI guide to custom instructions with AGENTS.md.

Learn it exactly, because most confusing Codex behaviour traces back to it.

• Global scope first. In the Codex home directory (~/.codex by default, or wherever CODEX_HOME points), Codex reads AGENTS.override.md if it exists, otherwise AGENTS.md. Only the first non-empty file at this level is used.
• Project scope next. Starting at the Git root, Codex walks down to your current working directory and checks each directory for AGENTS.override.md, then AGENTS.md, then any name listed in project_doc_fallback_filenames. At most one file per directory.
• Merge order last. Files are concatenated from the root down, so a file closer to your working directory appears later in the prompt and overrides what came before it.

The failure mode nobody warns you about is the size cap. Codex stops adding files once the combined instruction chain reaches project_doc_max_bytes, which defaults to 32 KiB. In a monorepo with an instruction file per package, the deepest and most specific file is exactly the one that gets dropped, and nothing tells you it happened.

Two fixes: raise the cap deliberately, or keep each file short enough that the chain never reaches it. The second is better, because a 32 KiB prompt preamble is not being read carefully by anything.

# AGENTS.md at the repository root

## Working agreements
- Run `npm run lint` and `npm test` after changing anything under src/.
- Prefer pnpm when installing dependencies.
- Ask before adding a new production dependency.

## Verification
- A change to a user-facing flow is not done until a browser check passes.

Connecting MCP Servers to Codex CLI

Model Context Protocol servers are how Codex reaches anything outside your repository: a documentation index, an issue tracker, a database, an internal service. Codex supports both local stdio servers and remote streamable-HTTP servers.

# add a local stdio server
codex mcp add context7 -- npx -y @upstash/context7-mcp

# pass environment variables through to the server process
codex mcp add internal --env API_TOKEN=$TOKEN -- ./bin/internal-mcp

# what is configured, and sign in where OAuth is required
codex mcp list
codex mcp login internal

Inside the terminal UI, /mcp lists the servers active for the current session, which is the check to run when a tool you expected is not being called. For anything beyond the basics, declare servers directly in configuration as an [mcp_servers.<server-name>] table, either in ~/.codex/config.toml for yourself or a project-scoped .codex/config.toml that ships with the repository.

A stdio server entry takes a required command, plus optional args, env, env_vars, and cwd keys. Project-scoped configuration is the useful pattern for teams: everyone who clones the repository gets the same tool surface without each person repeating the add commands.

When a server is configured but its tools never get called, the problem is usually the server rather than Codex. Our guide to MCP Inspector covers testing and debugging a server in isolation, and if you are building one rather than consuming it, the walkthrough on how to build an MCP server covers the protocol side.

Running Codex CLI in CI with codex exec

codex exec is the non-interactive mode: no terminal UI, no prompts, suitable for pipelines and scripts. Its output contract is what makes it composable. Per the OpenAI documentation on non-interactive mode, progress streams to stderr while only the final agent message goes to stdout, so a plain redirect captures the result and nothing else.

# final message only, straight into a file
codex exec "generate release notes for the last 10 commits" | tee release-notes.md

# allow edits, explicitly, for an automated fix job
codex exec --sandbox workspace-write "bump the minor version and update the changelog"

# no session rollout files left on the runner
codex exec --ephemeral "triage this repository and list the riskiest modules"

Four flags carry most of the weight in an automated context.

• --sandbox - the default for codex exec is a read-only sandbox, so any job that edits files has to widen it on purpose. Prefer the explicit --sandbox workspace-write over the deprecated --full-auto, which now prints a warning.
• --ephemeral - skips writing session rollout files to disk, which matters on a shared runner where those artifacts would outlive the job.
• --ignore-user-config - runs without loading $CODEX_HOME/config.toml, so the job behaves the same regardless of what is on the machine.
• --ignore-rules - skips user and project execpolicy rules files for a controlled automation environment.

Piped stdin composes cleanly with all of it: if you pipe content in and also pass a prompt argument, Codex treats the prompt as the instruction and the piped content as context. That is what makes a shell one-liner such as a curl feeding into codex exec feeding into a file a practical pattern rather than a demo.

The harder question in an unattended pipeline is what counts as done when nobody is watching the run. We work through that in how async agents verify their own work.

Verifying What Codex CLI Ships

Codex has a /review command and it is genuinely useful. It is also structurally limited in one specific way: it reviews the diff. A coding agent reads code, so it can confirm that a handler is wired up and cannot confirm that the button rendering that handler is visible, clickable, and does the right thing when a real user presses it.

That gap is not a Codex flaw. It applies to every agent that verifies by reading source rather than by running the application, and it is why a merge gate has to exercise the built product. We work through the general shape of that gate in continuous verification for AI code.

Kane CLI from TestMu AI is built for that job. It is a deterministic browser agent that drives a real Chrome instance through the Chrome DevTools Protocol, takes a natural-language objective instead of selectors or test scripts, and grants a pass only when the expected state is confirmed through explicit evidence: DOM state, URL changes, network responses, screenshots, console logs.

For agent workflows it runs in agent mode, where the terminal UI is suppressed entirely and every lifecycle event is emitted as one JSON object per line on stdout. The terminal run_end event carries the complete result: status, summary, extracted values, token usage, the run directory, and a Test Manager URL a reviewer can open.

The Codex integration reuses the file you already configured in the AGENTS.md section. Installing the skill appends a Kane CLI section to AGENTS.md, and Codex picks it up on the next run.

# install the binary (Node 18 or later)
npm install -g @testmuai/kane-cli

# install the skill into Codex CLI, Claude Code and Gemini CLI in one command
npx @testmuai/kane-cli-skill

# what Codex then runs on your behalf, or you run in CI
kane-cli run "Log in with a valid account and confirm the dashboard loads" --agent --headless

With the skill installed, Codex checks that kane-cli is present and authenticated, builds the run command from your request, parses the NDJSON stream until run_end, and reports the status, steps, duration, and assertion results back to you. On a failure it inspects the run directory logs and screenshots to diagnose what actually broke. The Kane CLI getting started documentation covers authentication, which is the one step to sort out first, since OAuth login needs a browser window that a CI runner does not have.

Note: Codex writes the change. Kane CLI proves it works in a real Chrome browser and hands back evidence a reviewer can open. Try TestMu AI free

Where Codex CLI Fits and Where It Does Not

The tasks Codex CLI handles well share one property: a clear definition of done that can be checked mechanically.

• Dependency and version bumps - the end state is unambiguous, the test suite says whether it worked, and the whole job fits in one codex exec invocation.
• Codemods across a large repository - a mechanical transformation applied consistently is exactly the shape of work where an agent's patience beats a human's.
• Migrations with a defined endpoint - moving off a deprecated API has a finish line the agent can check itself against.
• Repository summarisation and release notes - read-only work, no sandbox risk, and stdout goes straight into a file.

Where it fits less well is anything where done is a judgment call. Exploratory design work, performance tuning without a target number, and refactors driven by taste all produce plausible diffs that nobody can grade automatically. The agent will finish; whether it finished correctly is still your problem.

The honest limitation to plan around is the one from the previous section. Any user-facing change needs a check that runs the application, whether that is a browser gate in the pipeline or a person opening the page. Teams running several agents side by side hit this quickly, which is why we wrote up the same pattern for a different agent in verifying Claude Code output with Kane CLI, and again in verifying Gemini CLI output.

Running more than one agent is common, and the comparison people actually make is against Claude Code. Codex CLI wins on licensing and an explicit permission model; Claude Code has the stronger multi-agent story, which we cover in Claude Code agent teams. Neither one can see the rendered page, so the verification gate is the same either way.

Where to Start with Codex CLI

Install it, open a repository you know well, and run /init to generate an AGENTS.md. Set approval_policy = "on-request" with sandbox_mode = "workspace-write" and leave network access off for the first week, so you learn what the agent tries to do before you decide what to allow.

Once that feels predictable, move one bounded job into CI with codex exec. A dependency bump or a changelog generator is the right size: read-only or workspace-write, one command, output you can diff.

Then close the loop on the part Codex cannot check itself. Append the Kane CLI skill to the same AGENTS.md, and put a browser-level check in front of merge so a user-facing change ships with evidence rather than a plausible diff. Start with a free TestMu AI account and the Kane CLI GitHub Actions setup guide to wire the gate into an existing workflow.