Codex & Agentic Development with OpenAI
Codex is OpenAI's coding agent that runs in your terminal — it reads your repo, plans, edits files, and runs commands in a loop. This is the OpenAI counterpart to the Claude Code chapter: how to install it, the agentic loop, and — most importantly — the sandbox and approval model that keeps it safe.
Learning objectives
- Explain what an agentic coding CLI is and when to reach for one.
- Install Codex and run your first task, interactively and headless.
- Reason about the agentic loop: plan → edit → run → iterate.
- Configure sandbox modes and approval policy — the safety model.
- Wire MCP servers and run Codex non-interactively in CI.
1 · What an agentic coding CLI is essential
There's a leap between "the model writes code in a chat window" and "the model fixes the bug in your repo." In a chat window, you are the hands: you copy the suggestion, paste it into a file, run it, paste the error back. An agentic coding CLI closes that loop — it is the hands. It reads your files, proposes an edit, runs the test, sees the failure, and tries again, all without you shuttling text back and forth. Codex is OpenAI's version of that tool; it's the direct peer to Claude Code.
The mental model is a junior pair-programmer at your keyboard. You describe the goal ("make the failing test pass", "add a flag to this CLI"); the agent explores the codebase, forms a plan, makes changes, and runs commands to check its work. Crucially, it operates inside your environment — your files, your shell, your git — which is exactly what makes it powerful and exactly what makes the safety model (section 4) the most important part of this chapter.
The common mistake is treating it like autocomplete and letting it run unsupervised with full permissions on day one. It is far more capable than autocomplete and far more consequential: an agent that can run shell commands can also delete files or push commits. The professional posture is the opposite — start locked down, watch what it does, and widen trust only as you learn its behavior.
- The first box is where the agent reads your repo and forms a plan from your goal.
- The middle boxes are the actions — editing files and running commands (tests, builds) — the parts that touch your real environment.
- The green box is observation: it reads the result and the dashed loop takes it back to planning until the goal is met.
- The whole loop runs inside the limits you set — which is what section 4 is about.
In short: it's the chat-window loop with the copy-paste removed — and the safety is in how tightly you bound the "run commands" step.
2 · Install & first run essential
Codex ships as a CLI (plus IDE extension and a cloud version). Install it with whichever package manager you already use:
terminal# npm
npm install -g @openai/codex
# or Homebrew (macOS)
brew install --cask codex
# or the install script (macOS/Linux)
curl -fsSL https://chatgpt.com/codex/install.sh | sh
Then launch it and authenticate. The easiest path is to sign in with your ChatGPT account (Plus/Pro/Business/Edu/Enterprise plans include Codex access); alternatively you can use an OpenAI API key.
terminalcodex # launches the interactive TUI; choose "Sign in with ChatGPT"
- The install puts a
codexbinary on yourPATH. Any one of the three methods works — pick the package manager you already maintain. - Running
codexwith no arguments opens the interactive terminal UI, where you describe tasks in natural language and watch the agent work. - On first run you authenticate once — "Sign in with ChatGPT" is simplest; an API key is the alternative for automation or non-ChatGPT accounts.
Try this: in a throwaway git repo, launch codex and ask it to "add a README with a one-line description of this project." Watch it propose the file before anything is written — that preview is the approval model doing its job.
3 · The agentic loop in practice intermediate
What makes the agent feel different from autocomplete is that it closes its own feedback loop. You give it a goal; it doesn't just emit a diff and stop. It reads the relevant files to understand context, proposes edits, runs the command that would tell it whether the edit worked (a test, a build, a linter), reads the output, and — if something failed — tries again with that new information. The same think-act-observe cycle you built by hand in the Agents chapter (Ch 4), now pointed at your codebase.
In practice you steer it with the goal and the guardrails, not the steps. A good task is outcome-shaped: "make test_auth.py pass", "refactor this module to remove the global", "add retry-with-backoff to the API client." The agent decides which files to touch and which commands to run; your job is to review its plan and bound its permissions — which is the next section.
4 · Sandbox & approvals — the safety model advanced
This is the most important section on the page, because an agent that can run shell commands is an agent that can do damage. Codex gives you two independent dials — a sandbox that limits what the agent can do, and an approval policy that controls when it must ask you first. Set them deliberately; the defaults lean safe, and you widen only as you build trust.
The sandbox (sandbox_mode in config, or --sandbox) has three levels:
| Sandbox mode | What the agent can do |
|---|---|
read-only | Read files only — no edits, no commands that change state. Safest; good for "explain this codebase." |
workspace-write | Read and write within the working directory, run commands — but no network/outside access by default. The everyday default. |
danger-full-access | No restrictions. Only for trusted, isolated environments (e.g. a disposable container). |
The approval policy (approval_policy) controls when the agent pauses to ask permission before acting:
| Approval policy | When Codex asks you |
|---|---|
untrusted | Asks before anything not on a known-safe list — most cautious. |
on-failure | Runs, and asks for approval only if a command fails (e.g. to retry with more access). |
on-request | The agent decides when it needs to ask — it requests escalation for riskier steps. |
never | Never asks — fully autonomous. Pair only with a tight sandbox or a disposable environment. |
The two dials combine. The common beginner error is reaching for danger-full-access + never because the prompts are annoying — which hands an LLM unsupervised control of your machine. The professional default is workspace-write with approvals on, escalating a specific task to more access only when you've watched the agent behave. There's a --full-auto convenience flag for a low-friction (workspace-write + auto-approve) mode when you're iterating fast in a safe repo.
- The left column is the sandbox — capability rising from green
read-onlyto purpledanger-full-access. - The right column is the approval policy — from green
untrusted(asks the most) to purplenever(fully autonomous). - They're independent: you choose a point on each. The dangerous corner is purple-plus-purple; the safe everyday setting is the middle/green zone.
In short: sandbox = what it can touch; approvals = when it asks. Default to the safe end of both and widen deliberately.
5 · Non-interactive runs for CI advanced
The interactive TUI is for you at your desk; CI needs the agent to run headless. Codex supports a non-interactive mode — codex exec "<task>" — that runs a task to completion without the TUI, which is what you wire into a pipeline (for example, "triage this failing build" or "open a PR that fixes the lint errors"). Because there's no human at the keyboard to answer prompts, the sandbox and approval settings become load-bearing: a headless run with never approvals must be paired with a tight sandbox or a disposable, isolated environment, or you've built an unsupervised agent with your credentials.
terminalcodex exec "fix the failing unit tests in this package"
approval_policy = "never" with sandbox_mode = "danger-full-access" on a runner that holds real secrets. Use workspace-write in an ephemeral container, scope the credentials to the minimum, and treat the agent like any other automated job with least privilege.6 · config.toml & MCP servers professional
Codex reads a config file at ~/.codex/config.toml where you set defaults so you're not passing flags every time — the model, the sandbox mode, the approval policy, and any MCP servers you want the agent to use. MCP (the subject of the next chapter) lets the agent reach standardized external tools — a filesystem server, a GitHub server, a database server — each declared as an entry with a launch command and args.
~/.codex/config.toml# defaults so you don't pass flags every run
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
# an MCP server the agent can call (see ox4-mcp)
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
- The top keys set your defaults: which
model, how cautious theapproval_policy, and how capable thesandbox_mode— the same two dials from section 4, now persisted. - Each
[mcp_servers.<name>]table declares an MCP server the agent can use;command+argsare how Codex launches it (here, a filesystem server over stdio). - With this in place,
codexstarts already knowing your preferences and tool connections — no repeated flags.
Try this: set sandbox_mode = "read-only" in config and ask the agent to make a change — watch it explain what it would do but refuse to write. That's the config enforcing the dial.
7 · CLI agent vs API vs IDE tech-lead
Codex, the raw API, and an IDE assistant solve overlapping but different problems — knowing which to reach for is a leadership call. Reach for the CLI agent (Codex) when the task is a repo-level change with a verifiable outcome: fix the failing tests, do a mechanical refactor across many files, triage a build. Reach for the raw API (ox2) when you're building a product feature — the model is a component inside your app, not a tool at your terminal. Reach for an IDE assistant when you want inline, keystroke-level help while you drive.
For a team, the governance questions mirror section 4 at organizational scale: which repos may run an agent, in what sandbox, with whose credentials, and reviewed how. Treat an autonomous coding agent in CI like any other privileged automation — least privilege, auditable, and never holding more access than the task needs.
🪜 Practice ladder beginner → industry
- Beginner: install Codex and run it in
read-onlymode; ask it to explain an unfamiliar repo. - Easy: in a throwaway repo, let it add a small file in
workspace-writewith approvals on; approve each step. - Core: give it a failing test and have it iterate until green; watch the plan→edit→run→observe loop.
- Stretch: write a
~/.codex/config.tomlwith your preferred model, sandbox, and approval defaults. - Hard: add an MCP filesystem server to the config and have the agent use it.
- Industry: design a safe
codex execCI job — ephemeral container, scoped creds,workspace-write, and an audit trail.
✓ Checkpoint — you can move on when you can…
- Explain what an agentic coding CLI does and when to use one.
- Install Codex and run a task interactively and with
codex exec. - Set
sandbox_modeandapproval_policydeliberately and explain the safe default. - Configure
~/.codex/config.tomlwith defaults and an MCP server.
Knowledge check check yourself
What are Codex's sandbox modes, and what is the safe default pairing with the approval policy?
Show answer
read-only (read files only), workspace-write (read/write and run commands within the working directory), and danger-full-access (no restrictions). The safe everyday default is workspace-write with the approval policy on (e.g. on-request or untrusted), widening only with trust. Never pair danger-full-access with never approvals outside a disposable, isolated environment.How do you run Codex non-interactively, and why do the sandbox/approval settings matter more there?
Show answer
codex exec "<task>" to run a task headless without the TUI — this is what you wire into CI. The settings matter more because there's no human to answer approval prompts: a headless run with never approvals must be paired with a tight sandbox (e.g. workspace-write) in an ephemeral, least-privilege environment, or it becomes an unsupervised agent holding your credentials.