loading…

Codex Harness Architecture

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

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 against 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 — broader discipline of agent runtime infrastructure
• clean architecture — inward dependency boundaries
• hexagonal architecture — ports and adapters isolation
• deepseek harness — microkernel plugin alternative for agent harnesses
• agent containment and blast radius — containment and egress security
• context rot — degradation from unbounded token accumulation
• openai — creator of Codex and the GPT models