Codex CLI 2 Deep Dive: Config, Profiles, Sandbox 2026

Codex CLI 2 is the most configurable agentic coding CLI shipping in 2026, and that configurability is its defining feature — every team that runs Codex in production touches config.toml, designs at least two profiles, picks a sandbox mode per workload, and wires at least one MCP server. Teams that treat configuration as an afterthought end up with a CLI that works on a laptop but fights them in CI; teams that invest a half-day in the config surface ship reliably.

The CLI's design philosophy is honest about the trade-off. Codex CLI is opinionated where the cost of a wrong default is high (sandbox defaults are conservative, approval policies start untrusted), and configurable where the right answer is workload-specific (model choice, network access, MCP servers, approval thresholds). The result is a CLI that can run a developer's exploratory edit, a CI test-generation pipeline, and an unattended production agent — from the same binary, with three different profiles, on the same machine.

This deep dive is the reference for engineers running Codex CLI 2 in production. The config.toml schema and its six sections, the profile API and how to design slots for dev / CI / prod / agent, the three sandbox modes and which workloads each fits, the MCP-server integration surface and the agent-loop primitives it exposes, a five-axis comparison with Claude Code, and four production workflows that ship. The closing FAQ covers the questions engineers ask before standardising on Codex.

The first time a team installs Codex CLI 2, the natural impulse is to copy the example config.toml from the README, set model = "gpt-5.5-codex", and start using the CLI. That config works — for one developer, on one laptop, doing exploratory edits. The moment the CLI moves into CI or onto a production agent, the README config becomes a liability: the sandbox is too permissive, the approval policy is wrong for unattended runs, the auth mode leaks long-lived tokens into CI logs, and the lack of profiles means every environment is fighting the same config.

The right mental model is to treat Codex CLI 2's config surface as a small, deliberately-designed declarative specification — six sections, named profiles, per-profile overrides — rather than a flat list of CLI flags transcribed to disk. Engineers familiar with Kubernetes manifests, Terraform modules, or CI workflow YAML already have the muscle memory: the schema is small, the activation is explicit, the defaults are conservative. Codex's value compounds when the config is designed; it leaks when the config is copy-pasted.

The remainder of this deep dive treats the configuration surface as the primary unit of analysis. Every section — schema, profiles, sandbox, MCP — is framed around the design decisions a team needs to make before standardising on Codex in production. The workflow archetypes at the end show how the decisions compose into shippable patterns.

The deeper context — what changed between v1 and v2, why the schema migration was necessary, how teams should phase the cut-over — is covered in our Codex CLI v1 to v2 migration playbook. This deep dive assumes a team has either completed that migration or is starting fresh on v2; the focus here is the production configuration design rather than the upgrade path.

The Codex CLI 2 config.toml schema has six top-level sections. Each section is independent — a config can omit any section and the CLI applies sensible defaults — but production deployments typically use all six. The sections are [model], [sandbox], [approval], [auth], [profiles], and [mcp]; everything else lives under one of those.

The schema is structurally flat at the top level and nested under [profiles.*] for per-profile overrides. Any top-level setting can be overridden inside a profile — so the base layer establishes defaults and the profile layer specialises them. Most production configs have a small base layer (the values genuinely shared across every environment) and most of their content inside the profile sections.

# config.toml — full Codex CLI 2 schema reference
# Six top-level sections, each independently optional.

# ----- [model] -----
[model]
name = "gpt-5.5-codex"
# Optional reasoning / generation overrides
temperature = 0.2
max_output_tokens = 8192

# ----- [sandbox] -----
[sandbox]
mode = "workspace-write"           # workspace-write | full-auto | read-only
network = false                     # default off in v2
writable_paths = ["./", "./tmp"]    # explicit writable list
forbidden_paths = ["~/.ssh", "~/.aws"]

# ----- [approval] -----
[approval]
policy = "untrusted"                # never | trusted | untrusted
require_confirm_on = ["git_push", "npm_publish"]

# ----- [auth] -----
[auth]
mode = "long-lived-token"           # oauth | long-lived-token | ci-issued
token_env = "CODEX_AUTH_TOKEN"      # env var reference, not literal

# ----- [profiles.*] -----
[profiles.dev]
extends = "base"

[profiles.dev.sandbox]
mode = "workspace-write"
network = true

[profiles.dev.approval]
policy = "never"

[profiles.dev.auth]
mode = "oauth"

[profiles.ci]
extends = "base"

[profiles.ci.sandbox]
mode = "workspace-write"
network = false

[profiles.ci.auth]
mode = "ci-issued"

[profiles.prod]
extends = "base"

[profiles.prod.sandbox]
mode = "read-only"
network = false

# ----- [mcp] -----
[mcp.servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]

[mcp.servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN_ENV = "GH_MCP_TOKEN" }

[mcp.servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]
env = { POSTGRES_URL_ENV = "DATABASE_URL" }

Two things to notice in the example above. First, the [profiles.*] entries inherit from a notional base profile via extends; the base is the top-level [sandbox], [approval], and [auth] sections taken together. Second, the [mcp] section is declared once at the top level but applies per-profile by default — individual profiles can override or extend the server list, but most teams find a single shared MCP server roster sufficient.

The schema is strict — Codex CLI 2 rejects unknown top-level keys by default, which catches typos and stale v1 settings that survived a migration. Custom keys for in-house tooling live under [extra], a reserved section v2 ignores but preserves for tool-specific extensions. Production configs should keep [extra] small and documented; it is an escape hatch, not a primary surface.

One under-appreciated default worth calling out: writable_paths defaults to the workspace root only, and forbidden_paths defaults to a curated list of common credential and config locations (~/.ssh, ~/.aws, ~/.config, and similar). Teams that want broader write access need to add it explicitly; teams that want to tighten the forbidden list further can extend it without touching the defaults. The two-layer model (curated denylist plus team allowlist) is the right shape for a sandboxed CLI.

The profile API is where Codex CLI 2 separates itself from every prior agentic CLI. A profile is a named bundle of settings — model, sandbox, approval, auth, and MCP overrides — that activates as a single unit. One config.toml file can declare any number of profiles, and activation is always explicit: either --profile dev on the command line or CODEX_PROFILE=dev in the environment.

The judgement call is which profiles to declare. The shape that ages best is profiles named after environments rather than people or projects — dev, ci, prod, and optionally agent for long-running production agents that deserve their own auth and approval policy. Teams that name profiles after people (alice, bob) discover the surface doesn't scale; teams that name them after projects (migration, refactor-2026) end up with stale profiles cluttering the config. Environments are the durable axis.

Two practical rules for designing profiles. First, default to inheriting from a base profile rather than duplicating settings; extends = "base" at the top of any profile section keeps shared defaults in one place and makes the deltas obvious. Second, keep the profile count low until pressure forces an addition — three profiles is the common landing point, four is reasonable for teams running autonomous agents, five or more is usually a sign that something else (project-level config files, environment variables, command-line flags) is being misused as a profile substitute.

Activation discipline matters as much as profile design. Every CI workflow, every wrapper script, every long-running agent should set CODEX_PROFILE or pass --profile explicitly; relying on the default profile leads to confused incidents where the wrong settings apply silently. The pattern that holds up is treating the profile flag as required everywhere except the developer laptop, where shell completion or a default in the shell rc file handles it.

Codex CLI 2 ships three sandbox modes, each designed for a specific risk profile. The mode is the headline setting in the [sandbox] section; everything else (network, writable_paths, forbidden_paths) refines the policy within the chosen mode. The matching of mode to workload is what separates a reliable Codex deployment from a brittle one — a workspace-write profile running an unattended production agent is asking for an incident; a read-only profile blocking a developer's exploratory edit is asking for friction.

The defaults inside each mode are conservative and worth knowing. workspace-write defaults to network off, writable_paths = ["./"], and the curated forbidden_paths denylist. full-auto defaults to network off but with a broader writable_paths default that includes /tmp and the workspace. read-only defaults to network off and ignores writable_paths entirely. Teams that want network access in any mode need to opt in explicitly per profile.

One subtle but important behaviour: read-onlymode is genuinely read-only — the CLI cannot write to a temporary directory by default, where v1's read-only mode allowed temp writes silently. If a production agent legitimately needs scratch space, the right setting is read-only-with-tmp(a sub-mode of read-only) which permits writes only to the OS temp directory. Most production agents don't actually need it — they were inheriting a v1 default — but a minority do, and the explicit opt-in is the right design.

The honest reading of the mix is that most teams settle on a two-mode shape: workspace-write for dev and CI, read-only for production agents, full-autoused only for specific batch workloads. The teams that mix modes per workload tend to be running mature agentic platforms with five or more distinct Codex use cases; the rest find the two-mode shape sufficient and don't benefit from added complexity.

Codex CLI 2 supports the Model Context Protocol as a first-class extension surface — the same protocol Claude Code popularised — which means the MCP server ecosystem is portable across both CLIs. The [mcp] section in config.toml declares the server roster, each server is launched as a child process when Codex starts, and the tools the server exposes become tool-call primitives the agent loop can invoke. The integration surface is symmetrical with Claude Code; the operational details differ in small ways.

The agent-loop primitives Codex exposes are the standard MCP shape: list_tools, call_tool, list_resources, read_resource, and the prompts surface for parameterised tool calls. Codex adds two of its own primitives on top — a sandbox-aware file_edit that respects the profile's writable_paths, and a propose_command primitive that surfaces shell commands for approval rather than executing them blindly. Both are optional, both are off by default, and both interact with the approval policy in the obvious way.

# [mcp] section — common server roster

# Filesystem access, scoped to the workspace
[mcp.servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]

# GitHub API for PR / issue manipulation
[mcp.servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN_ENV = "GH_MCP_TOKEN" }

# Postgres for data-aware code generation
[mcp.servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]
env = { POSTGRES_URL_ENV = "DATABASE_URL" }

# Per-profile override — CI gets a narrower server list
[profiles.ci.mcp.servers]
filesystem = { inherit = true }
github = { inherit = true }
# postgres explicitly omitted in CI to prevent inadvertent queries

The per-profile override pattern at the bottom of the example is the production discipline worth adopting. Production CI profiles should declare exactly which MCP servers they need, inheriting the base config's server definitions but narrowing the active set. The result is a CI run that cannot reach the production database even if the base config declares the postgres server — least-privilege applied to tool surfaces, not just filesystem paths.

Codex CLI 2 and Claude Code are the two production-grade agentic CLIs in 2026, and most teams running serious agentic engineering eventually pick one as the default and use the other for specific workloads. The honest comparison is five-axis rather than headline-feature: configuration model, sandbox design, MCP surface, headless auth, and editor integration. Each axis has a winner; no CLI sweeps all five.

The pattern that emerges from teams running both CLIs in production: Codex CLI 2 for CI-resident agentic workloads (test generation, codemod runs, scheduled audits) where the headless auth and per-profile config pay back the configuration investment; Claude Code for interactive editor-side work (refactors, feature builds, code review) where the VS Code integration and subagent system reduce friction. The choice isn't exclusive — most mature teams use both — and the MCP-server roster carries across the boundary, so the tool-call investment is durable either way.

For broader CLI context including Windsurf, Cursor, and the agentic-editor surface, our AI transformation engagements cover the longer-form evaluation pattern. The TL;DR for most teams is: pick one CLI as the default for interactive work, run the other in CI where its strengths shine, and treat the MCP server roster as the portable layer that survives the choice.

The four workflow archetypes below are the patterns we see most often across production Codex CLI 2 deployments. Each has a characteristic profile design, sandbox mode, auth pattern, and MCP-server roster. The patterns aren't mutually exclusive — most teams run two or three of them — but isolating them as archetypes makes the configuration design concrete.

The test-generation pipeline is the workflow that most teams adopt first because the value is immediate and the configuration is well-trodden. Our Codex test-generation pipeline tutorial walks the full pattern end-to-end, including the CI workflow YAML, the profile definition, and the failure modes to watch for. Workflows 02 through 04 build on the same foundation with progressively different trade-offs around containment and auth.

One operating rule that holds across all four archetypes: each workflow gets its own profile, even if two workflows share most settings. The cost of an extra profile is small (a few lines in config.toml); the cost of sharing a profile across distinct workflows is high (a change to one workflow's sandbox accidentally affects the other). Profile-per-workflow is the discipline that pays back across quarters.