Full deep dive: OpenAI Codex Architecture Breakdown
OpenAI's cloud-based coding agent that runs tasks in isolated sandboxes, powered by GPT-5.3-Codex. Features a three-layer architecture (agent loop, prompt/context layer, App Server), kernel-level sandboxing via Landlock/seccomp, and the AGENTS.md cross-tool standard. Tasks execute in parallel cloud containers or locally via the open-source CLI.
Architecture Overview
Codex uses three layers:
- Agent Loop — reads, plans, edits, verifies code iteratively
- Prompt & Context Manager — assembles context, manages prompt cache alignment for efficiency
- App Server — bidirectional JSON-RPC protocol (JSONL over stdio) that unifies CLI, VS Code, and web surfaces through a single API
Key Design Decisions
| Decision | Detail |
|---|---|
| Sandbox model | Cloud: air-gapped Docker containers. CLI: Landlock + seccomp (Linux) / Seatbelt (macOS) |
| Protocol | Custom JSON-RPC (rejected MCP — too tool-oriented for rich IDE interactions like streaming diffs and approval flows) |
| Agent loop | Prompt cache-aware — old prompt is always an exact prefix of new prompt |
| Cross-tool standard | AGENTS.md — repository-level instructions readable by any coding agent |
| Model | GPT-5.3-Codex (o3-derived, RL-trained on real coding tasks) |
Execution Modes
- Cloud sandbox: Isolated container preloaded with your repo, internet disabled. Ideal for parallel background work.
- CLI (local): Three approval levels — Suggest, Auto Edit, Full Auto. Open source on GitHub.
Why It's in Assess
Codex's App Server architecture (decoupling agent logic from client surfaces via JSON-RPC) and its decision to reject MCP in favor of richer session semantics are worth studying for anyone building coding agent infrastructure. The kernel-level sandbox (Landlock/seccomp) is the most aggressive security model in the space. See the full tear down for detailed architecture diagrams and comparisons with Claude Code.
Key Characteristics
| Property | Value |
|---|---|
| Company | OpenAI |
| System | Codex (cloud + CLI) |
| Model | GPT-5.3-Codex |
| Key innovations | App Server protocol, kernel-level sandbox, AGENTS.md |
| Open source | CLI only (GitHub) |
| Sources | OpenAI Blog, Agent Loop, App Server |