Codex Harness - OpenAI's Open-Source Underlying Execution Framework for AI Agents

What Is Codex Harness

Codex Harness is OpenAI's open-source underlying execution framework for AI Agents. Codex Harness is the exoskeleton that drives Agents, responsible for the complete execution loop including task understanding, memory retention, tool invocation, progress display, failure handling, and human approval. Through the three major components of CLI, SDK, and app-server, developers can seamlessly embed AI agents into their own products, operational dashboards, or business systems, without having to cram workflows into a generic chat box.

Main Features of Codex Harness

Agent Execution Loop: Drives AI agents through the complete iterative process from task understanding to result output.
Context and Memory Management: Maintains contextual coherence in long conversations, intelligently compressing and reviewing relevant information.
Tool and Skill Invocation: Supports AI in flexibly invoking external APIs, databases, and custom business tools.
Sandboxed Secure Execution: Provides an isolated runtime environment to ensure file system and network operations are secure and controllable.
Streaming Event Transmission: Supports real-time pushing of AI's thought process and execution progress to the application frontend.
Human Approval Intervention: Automatically pauses before critical operations and requests human confirmation, enabling secure human-machine collaboration.
Session Persistence: Supports saving and restoring conversation state, threads, and task lifecycle across sessions.
Frontend-Backend Decoupled Architecture: Separates the approval interface from the underlying execution loop, making it easy to seamlessly embed into any business system.

Follow WeChat and reply "Open Source", join theAI Open Source Project Communication Group

How to Use Codex Harness

Get the Open-Source Code: Go to the openai/codex repository on GitHub and clone the project to unlock the complete Harness tool library.
Quick CLI Execution: Use the codex exec command-line tool to run bounded Agent workflows, suitable for scripting and CI automation tasks.
SDK Programming Integration: Through the official TypeScript or Python SDK, precisely start, resume, or stream Codex tasks in code.
App-Server Product Embedding: Deploy the Codex app-server and deeply integrate the Agent loop into your own business system through the JSON-RPC protocol.
Expose Business Tools: Expose the application's own APIs, databases, and operational interfaces to Harness through the MCP protocol, allowing AI to invoke real business data.
Configure Approval Workflow : Connect the approval interface on the frontend; Harness will automatically pause before critical operations and request human confirmation, enabling secure human-machine collaboration.
Listen to Streaming Events: Subscribe to Harness's streaming event output to display AI's thought process and execution progress in real time on the application frontend.
Inject Business Context: Pass product interface state, user behavior, and business rules to Harness, enabling AI to work based on real scenarios rather than a generic chat box.

Core Advantages of Codex Harness

Open Source and Embeddable: Developers can embed the AI Agent execution loop directly into their own products, operations dashboards, or business systems, without having to force workflows into a generic chat box.
Complete front-end and back-end decoupling: The application layer controls the interface, context, tools, and approval process, while the Harness layer focuses on the Agent loop and sandbox execution, achieving communication separation through the JSON-RPC protocol.
Harness design is performance: On the ARC-AGI-3 benchmark, optimizing only the Harness (retaining reasoning + context compression) raised the GPT-5.6 Sol score from 13.3% to 38.3%, while reducing Token consumption by 6x.
Secure sandbox execution: Built-in isolated runtime environment with strict control over file system, network access, and runtime approvals, ensuring Agent actions are controllable, auditable, and rollback-capable.
Native Human-in-the-Loop: Automatically pauses before critical operations and requests human confirmation, continuing only after approval, naturally suited to business scenarios with extremely low tolerance for error.
Streaming events and persistent sessions: Supports real-time pushing of AI thinking and execution progress to the front end, and can save and restore thread state across sessions, adapting to long-cycle workflows.
Model-agnostic execution engine: Harness is an orchestration layer rather than a model layer, and can work with different underlying models, focusing on "how to manage models" rather than being tied to a specific model.

Codex Harness project address

Project website：https://developers.openai.com/blog/codex-as-a-platform
GitHub repository：https://github.com/openai/codex

Comparison of Codex Harness with similar competitors

Comparison dimension	Codex Harness	LangGraph
Core positioning	Treats the Agent loop as an embeddable underlying execution engine for products	Agent workflow orchestration framework based on a graph state machine
Architecture design	Front-end/back-end separation: the application layer controls the interface/approvals, Harness handles the execution loop	Node-edge model: developers define explicit state flows and checkpoints
Approval mechanism	Natively built-in Human-in-the-Loop, automatically pauses at critical operations to request confirmation	Developers must manually insert interruption/approval logic between nodes
Sandbox execution	Built-in isolated runtime, controls file system, network, and tool access	No native sandbox, relies on external container/environment isolation
Integration method	JSON-RPC protocol connects App-Server, with real-time streaming event push	Embedded directly in code as a Python/JS library, with checkpoint persistence
Applicable scenarios	Products with an existing mature business interface that need AI to execute at the underlying level while humans control approvals	Complex workflow orchestration that requires precise control over multi-step state transitions

Application scenarios of Codex Harness

Tax and finance compliance automation: Embedded into tax preparation workflows, AI handles complex tax logic and automatically fills out tax return forms, tax professionals approve and confirm key fields; has been verified on 7,000 tax returns, reducing preparation time by about one-third.
Enterprise cloud platform application building: Such as Cisco App Builder, where customers use natural language to create custom applications within their cloud control platform, while Harness handles permission validation and underlying logic flow behind the scenes.
Logistics scheduling exception handling: Embed an Agent in the logistics dashboard. After the dispatcher clicks "Investigate delay," the Agent automatically calls MCP tools to retrieve real-time waybill data and analyze the cause of the delay. Any order modification operation requires manual approval.
Operations dashboard embedding: Integrate the Agent directly into the existing operations dashboard to analyze business metrics in real time, trigger anomaly alerts, and execute remediation actions without switching to a separate chat interface.
Security operations approval: A security analyst directly invokes the Agent in the alert queue to investigate the status of affected services, and high-risk operations automatically trigger Human-in-the-Loop approval before execution.

Questions about Codex Harness

Q: What is Codex Harness? How is it different from the Codex model?

A: Harness is the underlying execution engine that drives the AI Agent, responsible for task understanding, memory retention, tool invocation, sandbox execution, streaming events, and approval workflows; the Codex model is the "brain" that generates code/reasoning. Harness is the "exoskeleton," the model is the "brain," and only when the two work together can the complete Agent workflow run.

Q: What is the open-source license? Can it be used commercially for free?

A: Apache-2.0 license, fully free for commercial use. You can freely embed it in your own products, modify the source code, and redistribute it without open-sourcing your upper-layer business code.

Q: Is it mandatory to bind to OpenAI's GPT models? Can I use Claude or DeepSeek?

A: Harness is a model-agnostic orchestration layer and does not architecturally mandate binding to GPT. However, the current official implementation connects to the OpenAI API by default; to replace it with another model, you need to adapt the model invocation layer yourself.

Q: How do I choose among the three components? Which one should I use for which scenario?

A：

codex exec → scripts, CI pipelines, one-off background tasks, returning structured results.

Codex SDK → you are writing application code and need to start, resume, or stream tasks programmatically.

Codex app-server → the Agent needs to become part of the product, requiring persistent conversations, real-time events, interrupting work, and approval handling.

Q: I already have a business system. How do I integrate Harness?

A: Connect through the Codex app-server's JSON-RPC protocol. Your application is responsible for providing the "product interface + business context + approval workflow," while Harness is responsible for the "Agent loop + sandbox execution." The two sides communicate bidirectionally through Context in / Events out.

Q: How is Human-in-the-Loop implemented? Is it very intrusive to the business?

A: When Harness detects an "operation requiring approval," it automatically pauses the Agent loop and pushes an approval request to the frontend through streaming events; after the user confirms, Harness continues execution. The business side only needs to implement an approval UI and respond to JSON-RPC events, with very low intrusiveness.