Codex Harness Explained: OpenAI's Open-Source Agent Runtime

What is the Codex harness?

The Codex harness is the execution system that wraps an OpenAI model and turns it into a working agent. The model reasons; the harness gives it a task loop, memory across turns, tool access, a sandbox to run in, approval gates, and a way to stream progress back out. The industry shorthand is Agent = Model + Harness: the model supplies the intelligence, the harness supplies everything the model cannot do on its own.

Every Codex surface you have used — the app, the CLI, the IDE extension, the macOS app — runs on this same harness underneath. That is the point OpenAI made when it positioned Codex as a platform in August 2026: the reusable part is not any one interface, it is the agent loop and the machinery around it.

Beyond the core loop, the harness owns three responsibilities most teams underestimate when they try to build their own:

• Thread lifecycle and persistence — a thread is one conversation between a user and the agent. Codex creates, resumes, forks, and archives threads and persists the event history, so a client can disconnect and reconnect onto a consistent timeline.
• Config and auth — loading configuration, managing defaults, and running credential flows such as Sign in with ChatGPT.
• Tool execution and extensions — running shell and file tools inside a sandbox and wiring in MCP servers and skills under one consistent policy model.

All of this lives in a Rust component called Codex core, which is both the library holding the agent code and a runtime that can be spun up to drive the loop and persist a single thread.

Why the harness matters as much as the model

It is tempting to treat the model as the whole product and the surrounding code as plumbing. In practice the opposite bites you: the model sets the ceiling on reasoning, but the harness decides whether the model reaches that ceiling on a real, multi-step task. Two agents built on the identical model can behave completely differently depending on how their harness handles context, tools, and failure.

OpenAI's own numbers make the size of that gap concrete. On the ARC-AGI-3 benchmark, adding retained reasoning and context compaction raised a GPT-5.6 configuration's score from 13.3% to 38.3% while cutting output tokens sixfold — same model, better harness, roughly triple the score at a fraction of the cost.

The other reason the harness matters is that long agent runs fail quietly. A model left to its own devices has no way to check its claim of success against reality, so it will confidently report a task done when the environment says otherwise. A production harness closes that gap by verifying work — running the test suite after a change and only marking it complete when the tests pass — before a result reaches the user. This is why benchmarks like Terminal-Bench score the model and harness together as one unit rather than the model alone. If you are deciding where to spend engineering effort on an agent, the harness is usually the higher-leverage place.

What OpenAI actually open-sourced

The headline is that the harness is now open source, but it helps to be precise about what that includes and what it does not.

Open source, in the openai/codex repository: the Codex CLI, the app-server, and the official Codex SDK. OpenAI maintains an open-source components guide listing exactly what ships and where each piece lives.

Not open source: model access and the managed services stay separate. The open layer is the harness and the integration surface — the code that sits between your application and the model — not the model weights or the hosted infrastructure behind them.

The practical payoff is inspection and adaptation. You can read how the layer between your app and the model actually behaves, understand its approval and sandbox policies, and adapt the integration to fit your product rather than treating the runtime as a black box. For anyone who has debugged an opaque agent framework in production, being able to step into the harness itself is the real unlock.

Inside the architecture: Codex core and the App Server

Clients do not talk to Codex core directly. They talk to the Codex App Server, which is two things at once: a bidirectional JSON-RPC protocol, and a long-lived process that hosts one or more core threads. A single App Server process has four parts — a stdio reader, a message processor, a thread manager that spins up one core session per thread, and the core threads themselves. The reader and processor translate client JSON-RPC requests into core operations, then transform core's low-level internal events into a small set of stable, UI-ready notifications.

The transport is deliberately unglamorous: JSON-RPC framed as JSONL over stdio. OpenAI calls it a “JSON-RPC lite” variant that keeps the request, response, and notification shapes but drops the strict 2.0 header. That choice makes bindings easy to generate in almost any language — existing clients are written in Go, Python, TypeScript, Swift, and Kotlin. Crucially the channel is fully bidirectional: the server can initiate a request when the agent needs an approval, and pause the turn until the client replies allow or deny.

The three conversation primitives

An agent interaction is not a clean request and response, so the protocol is built from three primitives with explicit lifecycles. Getting these right is what lets a client render a live, resumable UI instead of a spinner.

• Item — the atomic unit of input or output (a user message, an agent message, a tool execution, an approval request, a diff). Each item moves through item/started, optional item/*/delta streaming events, and a final item/completed. That lifecycle is what lets a client start rendering on start, stream deltas as they arrive, and finalize on completion.
• Turn — one unit of agent work initiated by a single user input, such as “run the tests and summarize failures.” A turn contains the sequence of items produced along the way and ends when the agent finishes that input.
• Thread — the durable container holding many turns. Threads can be created, resumed, forked, and archived, and their history is persisted so a client can reconnect and rebuild the timeline.

You do not hand-write the client binding from a spec. Generate it from the Rust protocol definitions:

# TypeScript definitions straight from the protocol
codex app-server generate-ts

# Or a JSON Schema bundle to feed your own code generator
codex app-server generate-json-schema

codex exec vs Codex SDK vs App Server vs MCP

Building on Codex does not mean one integration for every job. There are four common ways to drive the harness, and picking the wrong one is where teams waste the most time. The right choice is a function of how tightly the agent is woven into your product.

OpenAI's own recommendation is the App Server as the first-class, long-term integration surface — but that is guidance for products that embed the agent, not a rule for every script. If your use case is a nightly CI check, codex exec is the honest answer and the App Server is over-engineering. Match the layer to how deeply the agent lives inside your product.

Codex harness vs other agent runtimes

The Codex harness landing in the open is part of a broader shift. Developers used to build on model APIs that returned a completion; increasingly they build on harness APIs that return a runtime — the loop, the tools, context management, hooks, and sandbox primitives out of the box. The Codex SDK, the Claude Agent SDK, and the OpenAI Agents SDK all point the same direction. The question is no longer “which model” alone, but “whose harness do I want to inherit.”

Two practical distinctions matter when you choose:

• Depth vs portability. Cross-provider harness protocols give you one abstraction across runtimes, but they tend to converge on the common subset of capabilities, which makes provider-specific interactions harder to represent. The Codex App Server goes the other way: it exposes the full, Codex-specific richness at the cost of being Codex-specific. Choose portability if you are orchestrating many providers; choose the App Server if you want everything the Codex harness can do.
• Composition. Because Codex can run as an MCP server, you can embed it as a callable tool inside another harness — for example, calling Codex from an agent built on the OpenAI Agents SDK. That makes “Codex harness vs another runtime” less of a binary and more of a layering decision.

One more accuracy note, since it comes up often: the harness is built and tuned around OpenAI's Codex models. Community adapters such as the AI SDK's Codex adapter allow pointing at OpenAI-compatible endpoints by selecting a direct auth mode and setting OPENAI_BASE_URL, but do not assume drop-in parity with an arbitrary third-party model. Treat the harness as an OpenAI-model runtime first.

What teams are building on the Codex harness

The most useful mental model comes from Relay, the sample operations app OpenAI shipped on the App Server. Relay puts an agent beside a shipment dashboard, connects it to application-owned MCP tools, and requires human approval before a shipment is rebooked. The user does not write a prompt from scratch; they select a shipment and click an action, the application supplies the context, Codex fetches current data through the app's tools, explains the options, and any consequential write goes through an approval gate. The harness runs the loop, conversation state, and tool interaction; the product keeps its dashboard, its records, and its controls.

That pattern is already in production well beyond engineering IDEs. Cisco uses the Codex SDK inside App Builder for Cisco Cloud Control. Thrive Holdings and Crete built a tax-preparation workflow on Codex whose pilot processed 7,000 returns and cut preparation time by about a third. GitHub and JetBrains bring Codex into existing IDE workflows. The same shape — app owns the interface, context, tools, and approvals; harness owns the agent loop — applies equally to a support console, an incident-triage queue, or an account-research workflow.

The takeaway for anyone building agentic software: you no longer have to invent a runtime to ship a serious agent. Start from the harness, then decide what your application should own. If you want a hand designing that boundary — which context and tools to expose, where the approval gates go, how the agent returns results into your system of record — that architecture work is exactly what our custom software development practice focuses on.