Codex CLI Deep Dive: Config, Profiles, Sandbox 2026

Codex CLI 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 in production (versions 0.128 through 0.130 as of May 2026 — see the official changelog). The config.toml surface — flat top-level keys plus [profiles.*] and [mcp_servers.*] tables — the named-profile pattern and how to design profiles for dev / CI / prod / agent, the three sandbox modes (read-only, workspace-write, danger-full-access) 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, 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'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 in the TypeScript-to-Rust rewrite, why the schema reset was necessary, how teams should phase the cut-over — is covered in our Codex CLI Rust migration playbook. This deep dive assumes a team has either completed that migration or is starting fresh on the Rust CLI; the focus here is the production configuration design rather than the upgrade path.

The Codex CLI config.toml schema uses flat top-level keys for the core controls — model, approval_policy, sandbox_mode, web_search — with nested tables for the structured surfaces: [sandbox_workspace_write] for write-scope tuning, [mcp_servers.NAME] for the MCP registry, [profiles.NAME] for named overrides, and [shell_environment_policy] for env-var hygiene. See the official config reference for the canonical key list.

The schema is structurally flat at the top level and nested under [profiles.NAME] 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. Profiles do not chain via an extends key; each profile simply re-states the keys it wants to override and inherits the rest from the top-level defaults.

# ~/.codex/config.toml — Codex CLI reference shape
# See: https://developers.openai.com/codex/config-reference

# --- Top-level defaults (flat keys) ---
model           = "gpt-5.5-codex"
approval_policy = "on-request"           # untrusted | on-request | never
sandbox_mode    = "workspace-write"      # read-only | workspace-write | danger-full-access
web_search      = "cached"               # "live" enables --search browsing

# Write-scope tuning for workspace-write mode
[sandbox_workspace_write]
network_access  = false
writable_roots  = ["./", "./tmp"]

# --- MCP server registry ---
[mcp_servers.filesystem]
command = "npx"
args    = ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]

[mcp_servers.github]
command  = "npx"
args     = ["-y", "@modelcontextprotocol/server-github"]
env_vars = ["GITHUB_TOKEN"]

[mcp_servers.figma]
url                  = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

# --- Named profiles ([profiles.NAME], override any top-level key) ---
[profiles.dev]
model           = "gpt-5.5-codex"
approval_policy = "never"
sandbox_mode    = "workspace-write"

[profiles.ci]
approval_policy = "untrusted"
sandbox_mode    = "workspace-write"

[profiles.prod]
approval_policy = "untrusted"
sandbox_mode    = "read-only"

Two things to notice in the example above. First, each profile in [profiles.NAME] overrides only the keys it cares about — there is no explicit extends mechanism; everything not re-stated in a profile falls back to the top-level defaults. Second, MCP servers are declared once under [mcp_servers.NAME] and are available across all profiles by default — most teams find a single shared MCP roster sufficient and rely on a wrapper script or CI policy to scope tool access where needed.

A few schema notes worth keeping in mind. Unknown keys generally log a warning rather than hard-failing — useful when CLI versions move ahead of your config, but it also means typos can drift silently. Pin a Codex version per environment, and audit ~/.codex/config.toml when bumping. Admin-managed constraints (lifecycle hooks, forced login method) live in requirements.toml rather than config.toml.

One under-appreciated default worth calling out: workspace-write defaults to network access off, writes scoped to the workspace, and the user's home directory and most system paths blocked. Teams that want broader write access (a temp dir, a build cache) add it via writable_roots in [sandbox_workspace_write]; teams that want network access (package installs, web fetches) flip network_accesson per profile. The defaults are deliberately conservative — opt in, don't opt out.

The profile API is where Codex CLI 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, lean on the top-level defaults rather than duplicating settings across every profile — Codex profiles do not chain via an extends key, so anything not re-stated inside a [profiles.NAME] table simply inherits from the top-level config. Keep the shared defaults at the top and let each profile re-state only the deltas. 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 pass --profile NAME (or its short form -p NAME) on the codex command line; 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 a shell alias handles it.

Codex CLI ships three sandbox modes, each designed for a specific risk profile. The mode is set via the top-level sandbox_mode key (or per-profile inside [profiles.NAME]); the [sandbox_workspace_write] nested table refines the policy when workspace-write is active — network_access, writable_roots, and related knobs. 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. See the Codex CLI reference for the canonical mode list.

The defaults inside each mode are conservative and worth knowing. workspace-write defaults to network_access = false and writes scoped to the workspace; the [sandbox_workspace_write] table is where you broaden writable_roots or enable network access per profile. danger-full-access bypasses sandboxing entirely — there is no allowlist to maintain because the mode is intended for environments that are themselves disposable. read-only blocks all filesystem writes. Teams that want network access in any mode need to opt in explicitly.

One subtle but important behaviour: read-only mode is genuinely read-only — the CLI cannot write to a temporary directory. If a production agent legitimately needs scratch space, the practical pattern is a wrapper script that creates a tmp dir outsideCodex and exposes it to the agent via an MCP server, rather than relaxing the sandbox mode. Most production agents don't need scratch space — log readers, triage summarisers, audit walkers — and the explicit-opt-in design keeps the blast radius small.

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, danger-full-accessreserved for specific batch workloads inside throwaway containers. 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 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_servers.NAME] tables in config.toml declare the server roster; STDIO servers take command / args / env, HTTP servers take url plus bearer_token_env_var. Each server is launched (or connected to) when Codex starts, and the tools the server exposes become tool-call primitives the agent loop can invoke. The CLI and the Codex IDE extension share the same registry, so a server wired once is available in both clients.

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. Tool calls flow through the active sandbox and approval policy — a tool that wants to mutate the filesystem is bound by the profile's sandbox_mode, and an action that crosses the approval threshold pauses for confirmation rather than executing blindly.

# [mcp_servers.NAME] — Codex CLI MCP registry
# Docs: https://developers.openai.com/codex/mcp

# STDIO server: filesystem access scoped to the workspace
[mcp_servers.filesystem]
command = "npx"
args    = ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]

# STDIO server: GitHub API for PR / issue manipulation
[mcp_servers.github]
command  = "npx"
args     = ["-y", "@modelcontextprotocol/server-github"]
env_vars = ["GITHUB_TOKEN"]

# STDIO server: Postgres for data-aware code generation
[mcp_servers.postgres]
command  = "npx"
args     = ["-y", "@modelcontextprotocol/server-postgres"]
env_vars = ["DATABASE_URL"]

# HTTP server: bearer-token auth via env var
[mcp_servers.figma]
url                  = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

# Narrowing for CI: use a separate ~/.codex/config.toml in the CI image
# (or a CODEX_HOME override) that simply omits the servers CI shouldn't
# reach. The registry is global to the config file; least-privilege is
# applied at the config-layer/profile-image boundary, not via an
# "inherit" key.

Codex does not ship an in-config "inherit" key for the MCP registry — the registry is global to a given config.toml. The production discipline that holds up is to narrow tool surfaces at the layer above: separate CODEX_HOME directories per environment, a CI image that ships a stripped-down config.toml, or admin-managed entries in requirements.toml. The result is a CI run that cannot reach the production database because the postgres server simply isn't declared in the CI image — least-privilege applied to tool surfaces, not just filesystem paths.

Codex CLI 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 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 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.