Building and Scaling Codex: OpenAI's Production Coding Agent

openai · Tech · 2025 · source Agentic: yes · promotional bias: med · source-backed · extracted with prompt 0.5.5 (schema v2)

Generated from extraction.json — do not edit by hand. Every claim cites verbatim source evidence; stated means the quote directly asserts the claim, implied means it supports it indirectly.

Problem

Domain: AI coding agents

OpenAI needed Codex to move beyond code completion into a production software-engineering teammate that can work inside developer workflows, run code safely, handle long-running tasks, and be trusted enough for internal and external production software development.

Constraints:

developers need help inside existing IDE and terminal workflows rather than a separate mental model
cloud delegation created setup and prompting friction for users who were not already OpenAI-style reasoning-model power users
long autonomous tasks exceed a single model context window
the agent uses shell commands, so execution needs safety isolation and permission boundaries
reviewing AI-written code can become the human bottleneck even when generation is fast
internal dogfooding signal differs from general-market adoption behavior

Architecture

Codex is built as a three-layer agent system: GPT-5.1 Codex Max, a Codex API with long-context compaction support, and first-party harnesses that run in IDEs, CLIs, cloud computers, and sandboxes. The product shifted adoption from a cloud-first delegation model toward local IDE/CLI pairing so users could get immediate value, share their existing dependencies, and gradually configure trust. Long-running work is enabled by compaction across the model, API, and harness, while shell-based execution gives the model a general computer interface inside sandbox boundaries. Product and research teams iterate the model and harness together using dogfooding, retention, social feedback, difficult tasks, and validation/code-review loops.

Diagram confidence: reconstructed (reconstructed from prose).

flowchart LR
  user-workflow-surfaces[User workflow surfaces] --> local-sandbox-harness[Local sandbox harness]
  codex-cloud[Codex Cloud] --> cloud-computer-harness[Cloud computer harness]
  local-sandbox-harness --> shell-execution-interface[Shell execution interface]
  local-sandbox-harness --> codex-api[Codex API]
  cloud-computer-harness --> codex-api
  codex-api --> gpt-5-1-codex-max[GPT-5.1 Codex Max]
  codex-api --> compaction-service[Compaction service]
  compaction-service --> gpt-5-1-codex-max
  gpt-5-1-codex-max --> shell-execution-interface
  local-sandbox-harness --> validation-and-code-review[Validation and code review]
  validation-and-code-review --> user-feedback-and-metrics[User feedback and metrics]
  user-feedback-and-metrics --> product-research-loop[Product research loop]
  product-research-loop --> gpt-5-1-codex-max
  product-research-loop --> local-sandbox-harness

Drag to pan · scroll or use +/− to zoom · reconstructed from the source's described component topology

Components

Component	Role	Interacts with
`User workflow surfaces`	VS Code extension and terminal tool where most users pair with Codex interactively.	`Local sandbox harness`
`Codex Cloud`	Cloud delegation product that runs many async coding tasks on cloud computers.	`Cloud computer harness`
`Local sandbox harness`	Interactive execution environment that gives Codex access to local dependencies while isolating commands and asking for permissions when needed.	`User workflow surfaces`, `Shell execution interface`, `Codex API`, `Validation and code review`
`Cloud computer harness`	Remote task environment used for async delegation and parallel Codex Cloud work.	`Codex Cloud`, `Codex API`
`Shell execution interface`	Terminal-oriented tool interface through which the model reads, writes, tests, and executes code.	`Local sandbox harness`, `GPT-5.1 Codex Max`
`Codex API`	Serving layer between harnesses and the coding model, including API support for compaction transitions.	`Local sandbox harness`, `Cloud computer harness`, `GPT-5.1 Codex Max`, `Compaction service`
`GPT-5.1 Codex Max`	Coding-specialized reasoning model trained for the first-party harness, shell workflow, and compaction behavior.	`Codex API`, `Shell execution interface`, `Compaction service`, `Product research loop`
`Compaction service`	Cross-layer context-management capability that lets long-running Codex work continue after exceeding a context window.	`Codex API`, `GPT-5.1 Codex Max`
`Validation and code review`	Review and validation surfaces that help humans gain confidence in agent-written code and reduce the review bottleneck.	`Local sandbox harness`, `User feedback and metrics`
`User feedback and metrics`	D7 retention, signup dogfooding, social feedback, complaints, praise, benchmarks, and hard-task outcomes used to steer the product.	`Validation and code review`, `Product research loop`
`Product research loop`	Tightly integrated OpenAI product and research team iterating the model and harness together.	`User feedback and metrics`, `GPT-5.1 Codex Max`, `Local sandbox harness`

Data flow

A developer starts Codex from a VS Code extension, terminal tool, or Codex Cloud task. The local or cloud harness gathers task context, runs shell commands inside a sandbox, and calls the Codex API to reach GPT-5.1 Codex Max. For long tasks, the model prepares for context transfer, the API exposes the compaction transition, and the harness prepares the payload so work can continue in a fresh context window. The agent produces code changes, runs tests or validation commands, asks the user for permissions outside the sandbox, and returns work for review. Usage telemetry, D7 retention, internal dogfooding, Reddit/Twitter feedback, public benchmarks, and hard-task outcomes feed back into the integrated product/research loop.

4 supporting quotes

“Codex is Open AI's coding agent. So super concretely that means it's an IDE extension, like a VS Code extension, uh that you can install or terminal tool that you can install.”transcript, stated

“actually, we need to serve that model through an API into a harness and both of those things also have a really big role here.”transcript, stated

“if the agent needs to do something, like it needs to run a command, it can do so within the sandbox, we don't have to set up any environment.”transcript, stated

“at the API layer, you need an API that like understands this concept and like has an endpoint that you can hit to do this change.”transcript, stated

Why this architecture

OpenAI chose a co-designed model/API/harness stack because a production coding agent needs more than raw inference: it needs tool execution, safety boundaries, context transfer, and workflow integration. The local IDE/CLI harness made adoption easier than a cloud-only async model, while the shell interface gave the model a general-purpose computer interface that could be optimized in one opinionated harness. Compaction was implemented across all layers because long tasks routinely exceed a context window. Evaluation mixes quantitative retention with qualitative social feedback and hard task performance because a power-user coding tool can otherwise overfit late-stage users and internal dogfooding.

4 supporting quotes

“the way that we decided to set up the Codex team uh was to build a you know, a really tightly integrated product and research team that are iterating on the model and the harness together.”transcript, stated

“the key unlock is actually first you need to land with users in a way that's like much more intuitive and like trivial to get value from.”transcript, stated

“the way that we built Codex is that it just uses the shell, but in order to make that like safer and secure, we have a sandbox that the model is used to operating in.”transcript, stated

“have a solution for that which we call compaction. Um that compaction is actually a feature that uses like all three layers of that stack. So, you need to have a model that has a concept of compaction and knows like, "Okay, as I start to approach its context window, I might be asked to like prepare”transcript, stated

Models used: GPT-5.1 Codex Max · GPT-5.1 Codex

Scale

Codex grew about 20x since GPT-5 launched in August.
“the last thought we shared there was like we were like well over 10x since August. In fact, it's been like 20x since then.”transcript, stated
Codex models serve many trillions of tokens per week.
“the Codex models are serving many many trillions of tokens a week now, and it's basically like our most served coding model.”transcript, stated
Long Codex tasks are reported as running overnight or for 24 hours.
“now routinely we'll hear about people saying like, "Yeah, it ran like overnight." or it ran for 24 hours.”transcript, stated
GPT-5.1 Codex Max was reported as roughly 30% faster than GPT-5.1 Codex for a given task.
“for any given task that you were using GPT-5.1 Codex for, it's like, you know, roughly uh 30% faster at accomplishing that task.”transcript, stated
The Sora Android app reached employee launch in 18 days and public launch in 28 days with a small engineering group.
“we built it in 18 days. It went from like zero to launch to employees. And then 10 days later, so 28 days total, we went to just like GA to the public.”transcript, stated
“imagine there's the number one app in the App Store with like a handful of engineers. Uh I think it was like two or three possibly”transcript, stated
For Atlas, a task that had taken two to three weeks for two to three engineers was reported as one engineer for one week.
“previously would have taken two to three weeks for two to three engineers, and now it's like one engineer, one week.”transcript, stated

Alternatives considered (roads not taken)

Cloud-first async delegation as the primary adoption path

Rejected because: It supported parallel work and matched OpenAI's internal power-user behavior, but created setup and prompting friction for the general market.

“Codex Cloud. And that was basically a product that had its own computer, lived in the cloud, you could delegate to it.”transcript, stated

“some of the challenges that we saw are that it's a little bit harder to set that up both in terms of like environment configuration”transcript, stated

Separate model development from product harness design

Rejected because: The team found faster experimentation by tuning the model, API, and harness together for a specific first-party environment.

“we're building all three things in parallel and like kind of tuning each one and um you know, constantly experimenting with how those things work”transcript, stated

Optimize the model for many different coding-tool harness philosophies at once

Rejected because: OpenAI chose an opinionated shell-first harness so training and product work could move faster in one world.

“You know, you can be much you can move much faster if you're just optimizing for one of those worlds. Right? And so, the way that we built Codex is that it just uses the shell, but in order to make that like safer and secure, we have a sandbox that the model”transcript, stated

Benchmark-only evaluation

Rejected because: The team also watches D7 retention, new-user experience, social complaints, dogfooding, and hard real tasks because coding-agent value depends on adoption and trust.

“it's like just critically important to like go look at like your like D7 retention. Right? Just go try the product. Like, sign up from scratch again.”transcript, stated

“we actually monitor a lot just like what the vibes are on social media pretty often. Especially I think for for Twitter X, um it's a little bit more hypey. And then Reddit is a little more negative, but real actually. Um so, I've started increasingly paying”transcript, stated

Patterns

`tool-use-orchestration` (agent-runtime)

Codex uses a terminal/shell-first harness so the model can run commands, tests, and code operations through a general computer interface.

“the way that we built Codex is that it just uses the shell, but in order to make that like safer and secure, we have a sandbox”transcript, stated

`context-compaction` (runtime)

The model, API, and harness coordinate compaction so Codex can continue tasks that exceed one context window.

“for a model to work continuously for that amount of time, it's going to exceed its context window. And so, we have a solution for that which we call compaction.”transcript, stated

`privacy-preserving-processing` (safety)

Codex executes in a sandbox that isolates local operations and asks the user when a command cannot run inside the sandbox.

“it works within a sandbox, which is actually like a really cool piece of tech to to help that be safe and secure.”transcript, stated

“if it's a command that doesn't work in the sandbox, it can just ask you.”transcript, stated

`eval-driven-development` (quality)

The Codex team combines public benchmarks, D7 retention, fresh signup dogfooding, hard-task anecdotes, Reddit/Twitter feedback, and internal dogfooding to steer development.

3 supporting quotes

“When you think about progress on Codex, I imagine you have a bunch of evals, and there's all these public benchmarks.”transcript, stated

“it's like just critically important to like go look at like your like D7 retention.”transcript, stated

“think we might be the most like user feedback {slash} social media pilled team out there in this space is like a few of us are like constantly on Reddit and Twitter. And you know, there's uh there's praise up there, and there's a lot of complaints, but we take the complaints like very seriously”transcript, stated

`human-in-the-loop-gate` (control)

The adoption path starts with side-by-side pairing, permission prompts, code review, and validation before expanding into longer autonomous delegation.

“So that's how people use it mostly today is they pair with it. But we want to get to the point where, you know, it can work like just like a new intern that you hire, and you don't only ask them to write code, but you ask them to participate across the cycle.”transcript, stated

“we can ship a code review feature that like helps you both confidence the AI written code.”transcript, stated

Tradeoffs

Adoption path

Chose local IDE/CLI pairing inside a sandbox over cloud-only async delegation as the primary entry point.

Rationale: Local pairing reduced setup friction, matched existing developer workflows, and helped users build trust before delegating longer tasks.

“the vast majority of users discover Codex today is either they download an IDE extension, or they run it in their CLI, and the agent works there with you on your computer interactively.”transcript, stated

“And eventually that's actually how you want to spend most of your time, so that's still the future. But it's hard to initially adopt.”transcript, stated

Harness interface

Chose shell-based execution over semantic-search or bespoke-tool-first harnesses.

Rationale: Optimizing the model for one opinionated shell harness let the team move faster and gave Codex a powerful general interface.

“maybe you have a strong opinion that it should work using semantic search. Right? Maybe you have a strong opinion that it should like call the spoke tools.”transcript, stated

“in our case a strong opinion that it should just use like the shell, work in the terminal.”transcript, stated

System development model

Chose co-design the model, API, and harness over optimize the model alone.

Rationale: Features like compaction only work when all three layers understand the behavior and coordinate the state transition.

“that compaction is actually a feature that uses like all three layers of that stack.”transcript, stated

“shipping this compaction feature that now just like made this behavior possible to like anyone using Codex, actually meant working across all three things”transcript, stated

Product evaluation

Chose retention, signup dogfooding, social feedback, and hard-task results over public benchmarks alone.

Rationale: A coding agent can pass benchmarks while still failing onboarding, trust, review, or workflow-fit problems.

“we can accidentally spend a lot of our time thinking about features that are like very deep in the user adoption journey.”transcript, stated

“with Reddit, there's a like really good upvoting mechanics, and like maybe most people are still not bots. Unclear. Um so, you get you get like good signal on what matters”transcript, stated

Gotchas (what bit them)

The first Codex Cloud adoption path was too far ahead of typical user workflows.

Root cause: Async cloud delegation required environment setup and a prompting style that OpenAI internal power users already understood but general developers did not.

Resolution: Move the primary adoption path into IDE extensions and CLI tools that pair locally with the user inside a sandbox.

“it required too much upfront configuration and prompted a different mental model than most developers were ready for.”summary, stated

“first you need to land with users in a way that's like much more intuitive and like trivial to get value from.”transcript, stated

Long-running coding work exceeded the context window.

Root cause: Overnight or 24-hour tasks require more continuity than a single model context can hold.

Resolution: Implement compaction as a coordinated model, API, and harness feature so the model can prepare for a fresh context window.

“for a model to work continuously for that amount of time, it's going to exceed its context window.”transcript, stated

“as I start to approach its context window, I might be asked to like prepare to be run in a new context window.”transcript, stated

Generation speed shifted bottlenecks into human review.

Root cause: AI agents can write large amounts of code, but engineers may still need to manually inspect and validate the output.

Resolution: Invest in code review and agent self-validation features that help humans trust the work faster.

“nowadays when you work with a coding agent, um it writes a ton of code, but it turns out writing code is actually one of the most fun parts of software engineering”transcript, stated

“another thing we could do is we can make it so that the agent's like better able to validate its work.”transcript, stated

Internal dogfooding signal overestimated market readiness for async delegation.

Root cause: OpenAI employees were unusually comfortable with reasoning models, upfront prompting, and massively parallel async work.

Resolution: Keep dogfooding but weight external user behavior and adoption metrics heavily.

“the signal we got from dogfooding is a little bit different from the signal you get from like the general market”transcript, stated

“we train reasoning models all day and so, we're very used to this kind of prompting and like, you know, think up front, run things massively in parallel.”transcript, stated

Shell execution is powerful but creates safety requirements.

Root cause: A general coding agent needs to run commands on real developer environments, which can cross local permission and dependency boundaries.

Resolution: Run commands inside a sandbox and ask the user when an operation cannot be performed within that boundary.

“it works within a sandbox, which is actually like a really cool piece of tech to to help that be safe and secure.”transcript, stated

“if it's a command that doesn't work in the sandbox, it can just ask you.”transcript, stated

Evaluation

OpenAI evaluates Codex through public coding benchmarks, difficult bug-solving tasks, internal dogfooding, D7 retention, fresh signup/onboarding checks, Reddit and Twitter feedback, API/model usage, and product features that help validate AI-authored code.

Metrics: public coding benchmarks · D7 retention · fresh signup experience · Reddit and Twitter praise/complaints · internal dogfooding signal · growth since launch · tokens served per week · hard bug-solving outcomes · code review catches and validation quality

4 supporting quotes

“I imagine you have a bunch of evals, and there's all these public benchmarks.”transcript, stated

“it's like just critically important to like go look at like your like D7 retention. Right? Just go try the product. Like, sign up from scratch again.”transcript, stated

“we actually monitor a lot just like what the vibes are on social media pretty often.”transcript, stated

“Codex code review is like catching a lot of mistakes. It's actually caught some like pretty interesting configuration mistakes.”transcript, stated

Outcomes

Codex grew roughly 20x since the GPT-5 launch in August
Codex models serve many trillions of tokens each week
Codex became OpenAI's most-served coding model and the most-served coding model in the API
Sora Android reached employee launch in 18 days and public launch in 28 days with help from Codex
Atlas engineering reported a two-to-three-week, two-to-three-engineer effort becoming one engineer for one week
Codex is used across OpenAI technical staff and by designers, product marketers, and researchers
Codex code review has caught configuration mistakes in training infrastructure
OpenAI is exploring Codex loops that monitor training graphs and take corrective action

The product operates at frontier-company scale: many trillions of tokens per week, 20x growth after GPT-5 launch, broad internal OpenAI adoption, external API use, and long-running tasks that can continue overnight or for 24 hours through compaction.

4 supporting quotes

“it's been like 20x since then. Um also, the Codex models are serving many many trillions of tokens a week now”transcript, stated

“we've reached a point where actually the Codex model is the most served coding model in the API as well.”transcript, stated

“we built it in 18 days. It went from like zero to launch to employees. And then 10 days later, so 28 days total, we went to just like GA to the public.”transcript, stated

“Codex code review is like catching a lot of mistakes. It's actually caught some like pretty interesting configuration mistakes.”transcript, implied

Building and Scaling Codex: OpenAI's Production Coding Agent

Problem

Architecture

Components

Data flow

Why this architecture

Scale

Alternatives considered (roads not taken)

Cloud-first async delegation as the primary adoption path

Separate model development from product harness design

Optimize the model for many different coding-tool harness philosophies at once

Benchmark-only evaluation

Patterns

tool-use-orchestration (agent-runtime)

context-compaction (runtime)

privacy-preserving-processing (safety)

eval-driven-development (quality)

human-in-the-loop-gate (control)

Tradeoffs

Adoption path

Harness interface

System development model

Product evaluation

Gotchas (what bit them)

The first Codex Cloud adoption path was too far ahead of typical user workflows.

Long-running coding work exceeded the context window.

Generation speed shifted bottlenecks into human review.

Internal dogfooding signal overestimated market readiness for async delegation.

Shell execution is powerful but creates safety requirements.

Evaluation

Outcomes

`tool-use-orchestration` (agent-runtime)

`context-compaction` (runtime)

`privacy-preserving-processing` (safety)

`eval-driven-development` (quality)

`human-in-the-loop-gate` (control)