---
title: "Codex Harness Architecture"
description: "Architecture of OpenAI's Codex harness: Clean/Hexagonal design, JSON-RPC app-server decoupling, multi-platform sandboxing, and bounded execution."
section: "concepts"
type: "concept"
created: "2026-08-27"
updated: "2026-08-30"
confidence: "high"
tags: ["agents", "context-engineering", "security", "workflow", "coding-guidelines"]
canonical: "https://pyweb.dev/wiki/codex-harness-architecture"
---
# Codex Harness Architecture

**Codex Harness Architecture** refers to the modular, protocol-driven systems design implemented in [OpenAI](/wiki/openai)'s open-source coding agent repository (`openai/codex`). Built in Rust (`codex-rs`), it exemplifies production [agent harness engineering](/wiki/agent-harness-engineering) by applying [Clean Architecture](/wiki/clean-architecture) and [Hexagonal Architecture](/wiki/hexagonal-architecture) (Ports & Adapters) to isolate non-deterministic LLM loops, OS-level process execution, and diverse client frontends.

```mermaid
flowchart TB
    subgraph Frontends["Frontends & Transports"]
        CLI["codex-cli"]
        TUI["codex-tui (Ratatui)"]
        IDE["IDE Extensions / Desktop"]
    end

    subgraph AppServer["Interface Adapters / Control Plane"]
        Server["codex-app-server (JSON-RPC daemon)"]
    end

    subgraph CoreEngine["Application Core"]
        Core["codex-core (OODA Turn Loop)"]
        Protocol["codex-protocol (Entities & Contracts)"]
    end

    subgraph OutboundPorts["Outbound Adapters & Substrates"]
        Sandbox["codex-sandboxing (bwrap / Seatbelt / Windows)"]
        Exec["unified_exec (HeadTailBuffer / PTY)"]
        MCP["codex-mcp (Tool Discovery & Execution)"]
        Store["codex-thread-store (Rollback / Fork / State)"]
    end

    CLI --> Server
    TUI --> Server
    IDE --> Server
    Server --> Core
    Core --> Protocol
    Core --> Sandbox
    Core --> Exec
    Core --> MCP
    Core --> Store
```

## Key Architectural Principles

### 1. Decoupled Control Plane (`App-Server` Pattern)
The core agent reasoning loop (`codex-core`) has zero awareness of terminal rendering or user input formatting.
- **Protocol-Driven Ingress:** Clients communicate with the harness exclusively through `codex-app-server-protocol` over JSON-RPC (via Unix Domain Sockets or WebSockets).
- **Multi-Client Surface:** The same underlying engine powers headless CLI executions (`/goal`), interactive TUI sessions, and background IDE extensions without code duplication.
- **Resilient Sessions:** Frontends can disconnect, reconnect, or inject mid-turn steer/interrupt signals without terminating the running background agent process.

### 2. Multi-Platform OS Sandboxing (`codex-sandboxing`)
To safely execute untrusted commands generated by models, Codex enforces strict OS-level process isolation rather than relying purely on user confirmation:
- **Linux:** Bubblewrap (`bwrap`) mount namespaces and Landlock LSM filesystem restrictions.
- **macOS:** Apple Seatbelt (`sandbox-exec`) security profiles compiled dynamically per execution.
- **Windows:** Job objects and restricted security tokens.

### 3. Bounded Context & Buffer Protection (`unified_exec`)
A common vulnerability in agent loops is context blowout caused by massive command stdout/stderr dumps (e.g., recursive directory listings or large log dumps). Codex integrates a `HeadTailBuffer` within `unified_exec` that captures the leading $N$ lines and trailing $M$ lines while discarding the middle, protecting the model's [smart zone](/wiki/smart-zone) against [context rot](/wiki/context-rot).

### 4. Asymmetric Tool Specialization (`apply-patch`)
While general-purpose harnesses rely on arbitrary JSON payloads, the Codex harness uses an optimized in-tree `apply-patch` crate tailored for unified diffs. This aligns with OpenAI frontier model training, which specializes in emitting unified diff chunks with anchor lines.

### 5. Deterministic State & Time-Travel (`thread-store`)
Session history is modeled as an ordered timeline of immutable turns:
- **Diff Tracking:** Every turn records file mutations via `turn-diff-tracker`.
- **First-Class Operations:** Primitives like `thread_rollback`, `thread_fork`, and `thread_resume` allow agents and human operators to backtrack safely from failed implementation branches.

## Failure Modes

| Symptom | Root cause | Fix |
|---|---|---|
| Harness and policy entangled | Ports not drawn at the right seams | Re-draw boundaries: every side effect behind a port |
| Tool output trusted raw | No validation at the boundary | Validate/deny at the adapter, never deep in the core |
| Sessions drift across restarts | State kept in-memory only | Persist session state through a repository port |

## Rule of Thumb

If a component would break when the model provider is swapped, it is
on the wrong side of the dependency boundary.

## Related Concepts
- [agent harness engineering](/wiki/agent-harness-engineering) — broader discipline of agent runtime infrastructure
- [clean architecture](/wiki/clean-architecture) — inward dependency boundaries
- [hexagonal architecture](/wiki/hexagonal-architecture) — ports and adapters isolation
- [deepseek harness](/wiki/deepseek-harness) — microkernel plugin alternative for agent harnesses
- [agent containment and blast radius](/wiki/agent-containment-and-blast-radius) — containment and egress security
- [context rot](/wiki/context-rot) — degradation from unbounded token accumulation
- [openai](/wiki/openai) — creator of Codex and the GPT models

---

## Agent Navigation

cluster: person (170 pages) | betweenness: 178.7

### References (outbound)
- [OpenAI](https://pyweb.dev/wiki/openai.md)
- [Smart Zone](https://pyweb.dev/wiki/smart-zone.md)
- [Agent Harness Engineering](https://pyweb.dev/wiki/agent-harness-engineering.md)
- [Clean Architecture](https://pyweb.dev/wiki/clean-architecture.md)
- [Hexagonal Architecture](https://pyweb.dev/wiki/hexagonal-architecture.md)
- [DeepSeek Harness](https://pyweb.dev/wiki/deepseek-harness.md)
- [Agent Containment and Blast Radius](https://pyweb.dev/wiki/agent-containment-and-blast-radius.md)
- [Context Rot](https://pyweb.dev/wiki/context-rot.md)

### Referenced by (inbound)
- [Agent Harness Engineering](https://pyweb.dev/wiki/agent-harness-engineering.md)
- [OpenAI](https://pyweb.dev/wiki/openai.md)

### Evidence (verified primary sources)
- [openai-codex-repository-architecture-2026](https://pyweb.dev/wiki/raw/articles/openai-codex-repository-architecture-2026.md) | origin: https://github.com/openai/codex | ingested: 2026-08-27 | sha256: 45788dafc27357bf9e9c323f46f57878d22dfb425b0373df899ea2284cfb7db5
- [picrew-awesome-agent-harness-2026](https://pyweb.dev/wiki/raw/articles/picrew-awesome-agent-harness-2026.md) | origin: https://github.com/Picrew/awesome-agent-harness | ingested: 2026-08-24 | sha256: 23785adad495721aa2e74aadeea442b74946c76e8cf89e3d7e32c3ac8a92735c

### Machine endpoints
- Knowledge graph: https://pyweb.dev/api/graph.json
- Graph analysis: https://pyweb.dev/api/graph-analysis.json
- Context index: https://pyweb.dev/llms.txt