Codex CLI's Harness

OpenAI's Codex CLI is an open-source coding agent, written in Rust, that runs in your terminal. Its harness leans hard on operating-system sandboxing and a two-layer safety model, with project memory in AGENTS.md and configuration in a single TOML file. Here it is through the same four-part lens.

Sources: OpenAI Codex documentation and the openai/codex repository. Features described are those documented as of mid-2026; a few fast-moving specifics are noted as such.

What Codex CLI is

Codex CLI is OpenAI's terminal coding agent. Unlike a closed product, it is open source under the Apache-2.0 license, with its core implemented in Rust (the npm package @openai/codex simply wraps prebuilt binaries). You install it with npm install -g @openai/codex, Homebrew, or an install script, and authenticate either by signing in with a ChatGPT account or with an API key.

It runs two ways: an interactive full-screen TUI you launch with codex, which reads the repository, edits files, and runs commands; and a non-interactive mode, codex exec, built for scripts and CI that streams progress to stderr and its final message to stdout, with flags like --json for machine-readable events. The interactive mode offers slash commands — including /init, /compact, /model, /permissions, /mcp, /review, and /status — for driving the session.

Tools and command execution

The model driving Codex is a current model from the GPT-5 Codex family, selectable mid-session with /model (the exact default id moves with releases, so it is best checked live rather than memorized). The tools it exposes are the familiar coding-agent core: shell/command execution, file read and edit operations, web search, plus any tools contributed by connected MCP servers.

What distinguishes Codex is where those commands run. Every shell command the model generates executes inside the platform sandbox rather than directly on your machine, and whether it runs at all is gated by the approval policy. Command execution, sandboxing, and approvals are therefore not separate afterthoughts — they are the same pathway, which is why the safety model deserves its own section below.

AGENTS.md — project instructions Codex reads first

Codex's persistent project memory is the AGENTS.md file: Markdown instructions, conventions, and context that Codex reads before it starts working. It uses a simple, predictable merge. A global ~/.codex/AGENTS.md applies everywhere; within a repository, Codex gathers the AGENTS.md files from the Git root down to your current directory, includes at most one per directory, and concatenates them from the root downward, joined by blank lines. Guidance closer to where you are working takes precedence over higher-level guidance.

By default the combined document is capped in size (32 KiB, adjustable via project_doc_max_bytes), and the /init command scaffolds a starter AGENTS.md in the current directory. AGENTS.md is a deliberately open, tool-agnostic format — plain Markdown that other agents can read too — rather than a proprietary schema.

Approval modes and sandboxing — two layers, not one

Codex separates safety into two independent controls, and understanding them separately is the key to the whole harness.

The sandbox: what is technically possible

The sandbox mode (--sandbox, or sandbox_mode in config) bounds what Codex can do at the OS level, regardless of what the model wants. There are three settings: read-only inspects files but runs no edits or commands without approval; workspace-write (the default) allows reads, edits, and commands within the workspace boundary, with additional writable roots configurable; and danger-full-access removes filesystem and network boundaries entirely. Network access is disabled by default under workspace-write and must be explicitly enabled.

Enforcement is real OS sandboxing, not just policy. On macOS, commands run under Apple's Seatbelt (sandbox-exec) with a profile matching the mode; on Linux and WSL2, Codex uses bubblewrap with user namespaces plus seccomp and Landlock. This is the "wall the agent cannot walk through" from Chapter 1, implemented by the kernel.

The approval policy: when to pause and ask

The approval policy (--ask-for-approval, or approval_policy) is the orthogonal question of when Codex stops to ask a human. Documented values include untrusted (auto-run known-safe reads, ask before mutating state), on-request (the default — prompt on sandbox escalations, network access, and destructive operations), and never (no prompts), plus a granular table form for finer control.

In the TUI these two dials are bundled into three presets you pick with /permissions: Read Only, Auto (the default — workspace-write with on-request approvals), and Full Access, which drops both the sandbox and approvals and therefore should be reserved for throwaway or already-isolated environments.

Config — one layered config.toml

Codex is configured through a single TOML file, ~/.codex/config.toml (under $CODEX_HOME). Its keys map directly onto the harness: model and model_provider choose the engine, approval_policy and sandbox_mode set the safety layers, and model_reasoning_effort (from minimal up to high, with higher tiers model-dependent) tunes how hard the model thinks. Sub-tables like [sandbox_workspace_write] and [model_providers.<id>] refine the boundaries and let you point Codex at alternative providers.

Settings layer with a clear precedence: command-line flags and -c overrides win first, then a selected named profile, then a trusted project-scoped config, then the user config, and finally managed and built-in defaults. Notably, a project-scoped config cannot override host-owned keys such as the model provider — a guardrail so an untrusted repository cannot silently redirect your agent. Named profiles let you keep, say, a cautious read-only setup and a fast autonomous one side by side and switch with --profile.

MCP support — client and server

Codex speaks the Model Context Protocol in both directions. As a client, it connects to external MCP servers declared under [mcp_servers.<id>] in config or managed with codex mcp add; both local stdio servers and streamable HTTP servers are supported, with per-server timeouts and per-tool approval controls. This is how Codex's fixed tool set gains new abilities.

Less commonly, Codex can also act as an MCP server: codex mcp-server runs Codex itself over stdio, exposing tools to start and continue a Codex conversation, so another agent or orchestrator can drive Codex as a sub-tool. That two-way capability makes Codex a component other harnesses can embed.

Context management

Codex keeps the context window in check with automatic history compaction, triggered when usage approaches a configurable token limit (model_auto_compact_token_limit), and a manual /compact command that summarizes the visible conversation to free space; /status reports current token usage. Combined with AGENTS.md — which supplies stable project context up front — this gives the model a working memory that is refreshed as needed without you re-explaining the project each time.

The pattern underneath

Codex's harness has a distinct character. Its center of gravity is OS-enforced sandboxing, with the elegant separation of "what is possible" (sandbox) from "when to ask" (approval policy). Its configuration is consolidated into one legible TOML file with layered precedence and host-owned keys that untrusted projects cannot touch. Its memory format, AGENTS.md, is deliberately open and shared across tools. And being open source and an MCP server as well as a client, Codex is built to be inspected and embedded. Keep this profile beside Claude Code's from the previous chapter — the final chapter sets them head to head.