Codex CLI & config.toml: Setup That Sticks

Codex is OpenAI's coding agent that runs locally on your machine — it reads your code, edits files, and runs commands from the terminal rather than from a chat window in a browser. The CLI is fast to install and friendly on day one, but its real personality lives in a single file: ~/.codex/config.toml. That file decides how much the agent can touch, when it stops to ask you, and which tools it can reach.

This guide takes you from a clean install to a setup that sticks — defaults you can trust on a Tuesday afternoon, profiles you can switch into when the job changes, and a security mindset that keeps a convenient install from becoming a stolen credential. Everything here is checked against OpenAI's official Codex documentation.

Why config.toml is the whole game

Most agent mistakes are not "the model was dumb." They are "the agent had more permission than the task needed." Codex separates two ideas that beginners tend to blur: the sandbox, which is the hard technical boundary on what the agent can do, and the approval policy, which decides when it pauses to ask. config.toml is where you set both. Get this file right once and every future session inherits sane behavior; get it wrong and you are either babysitting approvals all day or handing the agent the keys to your whole filesystem.

Sandbox modes: what the agent can do

The sandbox is the boundary Codex cannot cross even if it decides to. There are three modes, set with the sandbox_mode key:

read-only — Codex can inspect files but cannot edit them or run commands without approval. This is the safe default for exploring an unfamiliar repo, code review, or any session where you only want answers, not changes.

workspace-write — Codex can read files, edit within the workspace, and run routine local commands inside that boundary. This is the low-friction mode for everyday development. Crucially, network access is off by default here: in the default permission posture, Codex asks before using the internet or reaching beyond the workspace. You opt network back in explicitly (shown below), which is exactly the kind of decision you want to make on purpose rather than by accident.

danger-full-access — Codex runs with no sandbox restrictions at all: the filesystem and network boundaries are removed. The name is a warning, not decoration. Reserve it for throwaway containers and CI runners you fully control, never your primary machine.

Approval policy: when it stops to ask

The sandbox decides capability; approval_policy decides interruption. The documented values are untrusted (Codex runs only commands it considers trusted and asks for everything else), on-request (the agent runs what it can within the sandbox and pauses to ask when it wants to step outside the boundary), and never (it never pauses to ask — pair this only with a sandbox tight enough that "never asking" is still safe). Codex also supports a granular object form of approval_policy for fine-grained control, but the three string values cover the cases most people need.

The mental model: sandbox is the fence, approval is the doorbell. A tight fence with a loud doorbell (read-only + on-request) is cautious. A wide fence with no doorbell (danger-full-access + never) is how people lose an afternoon to an agent that rm -rf'd the wrong directory.

The [sandbox_workspace_write] table

When you choose workspace-write, the [sandbox_workspace_write] table lets you tune the edges of that boundary. The most consequential key is network_access (a boolean): set it to true only when the task genuinely needs the internet — installing dependencies, calling an API — and prefer to grant it inside a dedicated profile rather than your global default. The table also accepts writable_roots, an array of additional paths the agent may write to beyond the workspace, plus toggles like exclude_slash_tmp and exclude_tmpdir_env_var for controlling whether temporary directories stay writable. Keep this table small. Every path you add and every boolean you flip to true is a piece of the fence you just removed.

Profiles: a posture per file

You rarely want a single permission posture. Reviewing a stranger's pull request wants read-only; an unattended CI job wants no approval prompts; refactoring your own repo wants the comfortable middle. Profiles let you keep each of these postures in its own file and switch between them per invocation.

You define each profile in its own file at ~/.codex/NAME.config.toml, using the same top-level keys you would put in config.toml — not nested under a [profiles.NAME] table. Select one at launch with --profile NAME (or the shorthand -p NAME): Codex loads ~/.codex/config.toml first, then overlays the chosen profile file on top. Settings resolve by precedence — command-line arguments win over the active profile, which wins over the top-level config.toml defaults — so your top-level keys are the "if I say nothing" behavior, and each profile is a deliberate override you opt into by name.

(Heads up if you are migrating an older setup: as of Codex 0.134.0 the in-config [profiles.NAME] table syntax was removed — --profile no longer reads it — so move each block into its own ~/.codex/NAME.config.toml file.)

MCP servers in Codex

Codex can call external tools through the Model Context Protocol (MCP) — the same open standard other agents use to reach databases, browsers, issue trackers, and custom internal tools. You wire a server in with a [mcp_servers.NAME] table. The keys are the launch recipe: command is the executable, args is an array of arguments, env is a table of environment variables to pass, and startup_timeout_sec bounds how long Codex waits for the server to come up.

A practical note that doubles as a security note: an MCP server is a program Codex will execute on your behalf. Adding one is closer to installing a plugin than editing a setting. Pin it to a specific, trusted package, read what it does, and pass secrets through env rather than hard-coding them in arguments that might land in logs.

A setup that sticks

Put it together and the workflow is calm. Your top-level config.toml is conservative — workspace-write plus on-request, network off. Named profiles capture the exceptions: review for untrusted code, ci for unattended runs, deps for the rare network task. MCP servers are added deliberately, one trusted package at a time, with secrets in env. And every install comes from @openai/codex or another method OpenAI documents — never a lookalike. The payoff is that you stop thinking about permissions during the work: you decided the boundaries once, in a file you can read top to bottom, and now the agent operates inside them by default.

Commands and flags: the file is only half the story

config.toml sets the standing posture; the command line sets the posture for this one run. Most of what you tune in the file has a flag that overrides it for a single invocation, and a handful of flags have no file equivalent at all. [V] Every flag below is a documented global option on the codex command — combine them freely, and remember that anything you pass here outranks every file.

Inline overrides and the precedence ladder

The -c / --config flag is the escape hatch: it sets any config key for one run using TOML syntax, with dot notation for nested tables. [V] The value is parsed as TOML, so strings need TOML quoting — which is why a string value often carries an inner pair of quotes:

• codex -c approval_policy=never -c sandbox_mode=workspace-write — flip both dials for a single run.
• codex --config model='"gpt-5.4"' — the inner "…" is the TOML string; the outer '…' keeps your shell from eating it. [V]
• codex -c sandbox_workspace_write.network_access=true — dotted path reaches into a table. [V]
• codex --config 'shell_environment_policy.include_only=["PATH","HOME"]' — values can be arrays too. [V]

When the same key is set in more than one place, Codex resolves it top-down and the first hit wins. [V] From highest priority to lowest:

1. CLI flags and -c overrides — what you typed this run.
2. Project config — .codex/config.toml files from the repo root down to your cwd (closest wins; trusted projects only).
3. Profile file selected with --profile NAME (~/.codex/NAME.config.toml).
4. User config — ~/.codex/config.toml.
5. System config — /etc/codex/config.toml on Unix, if present.
6. Built-in defaults.

The practical read: a flag always beats the file, a trusted project's .codex/config.toml beats your personal profile, and your global defaults are the floor that everything else stands on. Note the trust gate on layer 2 — an untrusted project's .codex/ directory is skipped entirely (see trust_level below), so a hostile repo cannot silently lower your guardrails by shipping its own config.

Sessions: resume, fork, replay

Every interactive run is recorded as a rollout transcript — newline-delimited JSON written under ~/.codex/sessions/. [V] That history is what makes a session resumable instead of disposable:

• codex resume — pick from recent sessions interactively. [V]
• codex resume --last — jump straight back into the most recent one. [V]
• codex resume --last --all — widen the search beyond the current directory to every recorded session. [V]
• codex resume <SESSION_ID> — reopen a specific session by its id. [V]
• codex fork — branch from an existing session so you can explore an alternative path without overwriting the original transcript. [V]

Because the transcript is plain JSONL on disk, it is also auditable: you can read exactly what the agent did, which is the other half of why keeping sessions tight (and out of untrusted hands) matters.

Permission profiles: the modern alternative to sandbox_mode

sandbox_mode plus [sandbox_workspace_write] is the original, coarse model — one fence with a few toggles. The newer permission profiles replace it with a named policy that combines filesystem rules (what commands may read or write) and network rules (which destinations they may reach), expressed as glob-matched allow / write / read / deny entries where the most specific rule wins and deny beats write beats read. [V]

You turn the system on by setting default_permissions to a profile name. Three presets are built in: :read-only (execution can read but not write), :workspace (writes allowed inside the active workspace roots and temp dirs), and :danger-full-access (local sandbox removed). [V] Custom profiles live under [permissions.<name>] and should extends a preset so baseline protections carry forward instead of being restated. [V]

The one rule that trips people up: permission profiles do not compose with the old sandbox keys. [V] Configure either default_permissions + [permissions], or sandbox_mode / [sandbox_workspace_write] — never both in the same config. Pick the model you want and commit to it.