A coding agent looks simple from the chat window. You ask for a change, it reads a few files, runs commands, and gives you an answer. The interesting part is everything around the model that makes those actions controlled, observable, and recoverable.
I wanted a map of that surrounding system. So I read through the open source Codex repository and drew the main boundaries: where client requests enter, how a turn gets its context, how tool calls cross policy gates, what gets saved, and how one agent can delegate bounded work to another.
The idea that made the architecture click for me
The model chooses the next move. The harness makes the move real.
A model can write a shell command as text, but that text has no effect by itself. The harness has to recognize a structured tool request, check it against the active sandbox and approval policy, execute it, capture the result, and feed that result into the next model call.
That creates a loop:
- Assemble instructions, history, tools, configuration, and the current request.
- Ask the model what to do next.
- Evaluate any requested action under the active policy.
- Run the tool and capture its output.
- Add the result to the session record.
- Continue the loop or finish the turn.
The visual explainer lets you step through this loop one stage at a time. It also separates concepts that are easy to blur together, such as a sandbox and an approval policy, or an instruction in AGENTS.md and a model field passed by an orchestrator.
What the guide covers
The page moves from a plain English orientation into the implementation boundaries:
- The client surfaces and protocol layer around the core session loop
- The inputs used to construct a turn context
- A step-through diagram of the model and tool loop
- The separate roles of sandboxing, approvals, and command policy
- Rollout records, resume, fork, steering, cancellation, and compaction
- A planner and worker pattern using explicit model and reasoning fields
- When to use an
AGENTS.mdfile, skill, plugin, MCP server, connector, or hook
Each figure states what it simplifies. The diagrams show conceptual flow and responsibility rather than pretending to be a complete Rust call graph.
The boundaries that mattered most
The current terminal interface and headless command are clients of App Server infrastructure. That boundary can exist inside one operating-system process. An external application can use the App Server protocol, while the TypeScript SDK takes another route by launching codex exec and exchanging JSONL events. The model connection is separate again: model requests use Responses API transport, not the client-facing application protocol. The repeated sampling and tool cycle lives in the turn loop.
The storage picture also needed more than one box. The active session and model context live in memory. In the local persistence path, JSONL rollouts remain the canonical replay record, while SQLite supports metadata queries and projected history. The working project is a third system. Resuming a conversation can restore its history, but it cannot undo a file write or retract an effect in an external service.
Permissions have a similar split. Approval policy decides whether an action may proceed. A sandbox constrains what an executing process can access. The inspected backends vary by platform: macOS uses Seatbelt, Linux supports bubblewrap and a legacy Landlock path, and Windows has its own implementations. MCP-backed services have their own tool contracts and authorization boundaries, so a local shell sandbox is not a universal wrapper around every external action.
A concrete orchestration example
This workspace uses a root agent for research, planning, and review, then delegates code changes to a bounded implementation worker. The written policy helps every agent understand that split. The orchestration call still has to set the worker’s actual model and reasoning_effort fields.
That distinction matters. Prose can say which model should do the job. Only the runtime assignment makes that choice concrete.
The page includes a source-checked three-file example: project configuration for Astra at high reasoning effort, an implementer role fixed to Sol at medium effort, and an AGENTS.md policy that tells the root to delegate every edit. There is also a downloadable bundle. The TOML was parsed and checked against the repository schema, but I did not run a fresh authenticated installation test. Model and multi-agent access still depend on the installed client, effective settings, and account.
The stronger reading of “always delegate” needs one further step. A prose instruction does not remove the root agent’s write tools. If this split is a hard product requirement, the host application should enforce it by controlling which identity receives write-capable tools and by validating child model settings at the orchestration boundary.
Read the explainer
Open the visual architecture guide →
Opens in a new tab. The page is self-contained, responsive, printable, and uses no external JavaScript or web fonts.
The guide is based on the checked-out repository snapshot dated September 12, 2026. Codex changes quickly, so use the source links at the end of the page when you need exact details for the inspected snapshot.
Related reading: From the Codex Harness to Cloud Agents: Using the Agents API follows these boundaries into managed and self-hosted Agents API sessions.