--- source: 'https://howaiworks.ai/ai-tools/openai-codex' section: ai-tools title: OpenAI Codex description: >- OpenAI's coding agent for terminal, IDE, web and iOS. Runs GPT-6 Astra inside an OS-level sandbox and ships as Apache-2.0 open source. category: Code & Development developer: OpenAI projectType: CLI Tool & Platform pricing: Freemium launchDate: '2025-04-16' modelUsed: 'GPT-6 Astra, GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna' officialWebsite: 'https://developers.openai.com/codex' pricingPage: 'https://learn.chatgpt.com/docs/pricing' tags: - AI Tool - CLI - Development - Autonomous Agent - MCP - Open Source difficultyLevel: Beginner setupTime: 3 minutes apiAvailable: true integrationTypes: - CLI - VS Code - Web - iOS - GitHub isReviewed: false toolLevel: featured lastUpdated: '2026-09-06' --- # OpenAI Codex > OpenAI's coding agent for terminal, IDE, web and iOS. Runs GPT-6 Astra inside an OS-level sandbox and ships as Apache-2.0 open source. Codex is OpenAI's coding agent. It reads a repository, plans a change, edits files, runs the commands needed to check its work, and reports back — in a terminal, in VS Code, in a browser, or on a phone. The terminal client, Codex CLI, is the part most developers mean when they say "Codex", and it is open source under Apache-2.0. ## Overview Codex began in April 2025 as a small open-source terminal client and has since grown into OpenAI's full agentic-coding surface. The same agent now runs in five places: the CLI, a VS Code extension, the Codex web app, an iOS app, and — since June 2026 — Amazon Bedrock. What separates Codex from an autocomplete tool is that it *executes*. It runs your test suite, reads the failure, and tries again. That is also what makes the sandbox the most important part of the product rather than a footnote: an agent with a shell is only as safe as the box you put it in. The model underneath changed on **4 September 2026**: [GPT-6 Astra](https://howaiworks.ai/models/gpt) shipped that day and became Codex CLI's bundled default in release 0.153.4. The previous-generation GPT-5.6 tiers — Sol, Terra and Luna, generally available since 9 July 2026 — are still selectable, and OpenAI cut their prices at the Astra launch, so dropping down mid-session is cheaper than it was. Codex is the closest direct competitor to [Claude Code](https://howaiworks.ai/ai-tools/claude-code), and the two have converged on nearly the same shape — terminal-first, [MCP](https://howaiworks.ai/glossary/model-context-protocol)-native, sandboxed, driven by a Markdown instructions file. The meaningful choice between them is which model you want on your codebase. ## Key Features - **Three-tier sandbox.** `workspace-write` is the default: read anything, edit inside the workspace, run commands, no network. `read-only` answers questions without touching disk. `danger-full-access` removes sandboxing entirely and is named to discourage you. - **Four approval policies.** `on-request` prompts before escalations, `untrusted` auto-runs only known-safe reads, `never` runs autonomously inside whatever sandbox is configured, and `auto_review` routes approval requests through a reviewer agent instead of interrupting you. - **AGENTS.md.** Standing project instructions the agent reads on every run — build commands, conventions, directories to leave alone. `/init` writes a first draft by inspecting the repo. - **MCP client and server.** `codex mcp` connects external tools, and Codex can itself be exposed as an MCP server to other agents. - **Skills and plugins.** Repeatable instructions packaged as reusable units, plus third-party plugin integration. - **Runtime model switching.** `/model` changes both tier and reasoning effort without restarting the session, so an expensive planning step and a cheap mechanical step can share one conversation. - **Apache-2.0.** The client is genuinely open source — 103k stars on GitHub, core written in Rust. You can read exactly what it does with your files. ## How It Works You start `codex` in a repository. It reads `AGENTS.md` if one exists, builds context by exploring the project rather than requiring you to paste files, and proposes a plan. From there it works in a loop: edit, run, read the output, correct. The [agentic](https://howaiworks.ai/glossary/agentic-workflow) part is that loop closing without you in it — Codex sees its own test failures and iterates. Your control point is the approval policy, which decides when the loop pauses to ask permission. The sandbox is enforced by the operating system, not by the model's good intentions: | Platform | Mechanism | |---|---| | macOS | Seatbelt policies via `sandbox-exec` | | Linux | `bwrap` plus `seccomp` | | Windows | Native sandbox or WSL2, depending on setup | This matters more than it sounds. A [reasoning model](https://howaiworks.ai/glossary/reasoning-model) that has been talked into running a destructive command by a [prompt injection](https://howaiworks.ai/glossary/prompt-injection) hidden in a dependency's README is stopped by kernel-level confinement, and not by any amount of instruction-following. Network access being off by default in the standard mode is the single most useful line of that defence. ## Technical Details - **License**: Apache-2.0 - **Core implementation**: Rust (`codex-rs`) - **Default model**: `gpt-6-astra` — the bundled default since Codex CLI 0.153.4, 4 September 2026 - **Also selectable**: `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, the research-preview `gpt-5.3-codex-spark` on Pro, and the older `gpt-5.5` line - **Context window**: 1,050,000 tokens on Astra and on all three GPT-5.6 tiers; Astra takes up to 922,000 of that as input and caps output at 128,000. See [context window](https://howaiworks.ai/glossary/context-window) - **Knowledge cutoff**: 30 April 2026 on Astra; 16 February 2026 on the GPT-5.6 tiers - **Reasoning effort**: `low`, `medium`, `high`, `xhigh`, `max`, plus `ultra`, which delegates work to subagents - **Authentication**: ChatGPT account sign-in, or an OpenAI API key - **Config file**: `AGENTS.md` in the repository root - **Debug commands**: `codex debug seatbelt` on macOS, `codex debug landlock` on Linux — run an arbitrary command under the sandbox profile to see what it blocks ## Use Cases - **Multi-file refactors.** The case that justifies an agent over autocomplete: rename a concept across forty files, update the call sites, run the tests, fix what broke. - **Test-driven repair.** Hand Codex a failing test and let the execute-and-read-output loop close on its own. This is where the sandbox pays for itself. - **Codebase onboarding.** `read-only` mode turns Codex into a question-answering layer over an unfamiliar repository, with no risk of it editing anything while you learn. - **CI and review work.** The cloud surface handles GitHub code review and long-running tasks that outlive a terminal session. - **Cost-tiered automation.** Luna for mechanical bulk edits, Sol for the architecture decision at the start. Mid-session `/model` switching makes this practical rather than theoretical. - **Mobile follow-up.** The iOS app is genuinely useful for checking on a long cloud task, and genuinely not useful for writing code. ## Integrations - **Editors**: VS Code extension (also covers Cursor and Windsurf via the VS Code extension API) - **Source control**: GitHub, including automated code review on pull requests - **Cloud**: Amazon Bedrock, added June 2026 - **Protocol**: MCP in both directions — Codex as client, Codex as server - **Chat**: Slack integration on cloud-enabled plans ## Pricing & Access The CLI is free. The model usage behind it is not, and there are two separate ways to pay. **Through a ChatGPT plan** — usage is metered in messages against rolling five-hour windows, and local CLI messages share that window with cloud chats. Weekly caps may also apply. | Plan | Price | Notes | |---|---|---| | Free | $0 | Local tasks only, limited allowance | | Go | $8/mo | Lightweight local coding | | Plus | $20/mo | Full cloud access | | Pro | $100/mo (5×) or $200/mo (20×) | Multiples of the Plus allowance | | Business | $20/user/mo, annual | Larger VMs, SSO, no training on your data | | Enterprise / Edu | Contact sales | Shared credit pool, SCIM, audit logs | Per-window allowances on Plus run roughly 5–45 messages on GPT-6 Astra, 10–100 on Sol, 25–200 on Terra, and 250–2,000 on Luna; Pro multiplies those by 5× or 20×. The spread inside each range is real — a message that triggers a long agentic run costs far more than a one-line question, and there is no pre-task estimate. Note how small the Astra allowance is: the default model is also the one you run out of first. **Through an API key** — pay per token at the published rates, all per million tokens, with cached input discounted 90% on every tier: | Model | Input | Cached input | Output | |---|---|---|---| | GPT-6 Astra | $10.00 | $1.00 | $50.00 | | GPT-5.6 Sol | $4.00 | $0.40 | $20.00 | | GPT-5.6 Terra | $2.00 | $0.20 | $12.00 | | GPT-5.6 Luna | $0.20 | $0.02 | $1.20 | The GPT-5.6 rates are the reduced ones OpenAI introduced alongside Astra, published as promotional and available at least through **21 November 2026** — treat them as provisional rather than permanent. If you exhaust a plan allowance you can buy credits instead, priced per model: 250 credits per million input tokens on Astra, 100 on Sol, 50 on Terra and 5 on Luna. For steady daily use, a plan is cheaper and simpler. For bursty or automated use, the API key avoids the five-hour window entirely. ## Getting Started ```bash # macOS / Linux curl -fsSL https://chatgpt.com/codex/install.sh | sh # or via npm npm install -g @openai/codex # or via Homebrew brew install --cask codex ``` Windows has a PowerShell installer, and release binaries are on GitHub for manual installation. Then, in a repository: ```bash codex # start a session; sign in with ChatGPT or an API key /init # generate a starting AGENTS.md /permissions # set the sandbox and approval policy /model # switch tier or reasoning effort ``` Start in `read-only` on a repository you care about. Move to `workspace-write` once you have watched it work. Reach for `danger-full-access` when you have a specific reason and a disposable environment, which in practice means almost never. ## Limitations - **The five-hour window is opaque.** You cannot see what a task will cost before running it, and a single ambitious request can consume an afternoon's allowance. This is the most common complaint from daily users, and the default model has the smallest allowance of the four. - **Astra's long-prompt surcharge bites on the API path.** Any request whose input exceeds 272,000 tokens is billed at 2x the input and cache rates and 1.5x the output rate — for the whole request, not just the tokens above the line. An agent that lets a session's context grow unchecked can cross it without any warning in the terminal. - **Free and Go tiers exclude the cloud.** No GitHub review, no Slack, no long-running tasks. Local-only is a real product but it is not the whole product. - **Benchmark positioning is contested.** Coding leaderboards disagree sharply about Codex versus Claude Code depending on the harness, the reasoning effort and the scoring script. OpenAI publicly disputes SWE-Bench Pro's task quality, where its own models trail. Treat any single number as a claim about a configuration, not about the tool. - **Sandboxing is not free of friction.** Network-off by default breaks dependency installs and any test that reaches a service, and the escalation prompts arrive at the least convenient moment. The alternative is worse. - **iOS is a monitoring surface.** Useful for checking a running task, not for authoring. ## Alternatives - **[Claude Code](https://howaiworks.ai/ai-tools/claude-code)** — the closest equivalent. Same terminal-first shape, same MCP support, Anthropic models instead of OpenAI's, proprietary rather than open source. Strong on large multi-file refactors and context efficiency. - **[Cursor](https://howaiworks.ai/ai-tools/cursor)** — if you want an editor rather than a terminal. Better when you stay in the loop on every edit; weaker for long autonomous runs. - **[GitHub Copilot](https://howaiworks.ai/ai-tools/github-copilot)** — the incumbent, now agentic too, and the path of least resistance in a GitHub-centric organisation. - **[Aider](https://howaiworks.ai/ai-tools/aider)** — open source, model-agnostic, Git-native. The right answer if you want to bring your own model or keep everything local. - **[Cline](https://howaiworks.ai/ai-tools/cline)** — open-source VS Code extension with a bring-your-own-key model, for teams that want agentic editing without a vendor subscription. For a side-by-side, see [Claude Code vs Cursor vs Windsurf](https://howaiworks.ai/blog/claude-code-vs-cursor-vs-windsurf-which-coding-agent). ## Community & Support - **GitHub**: `openai/codex` — Apache-2.0, 103k stars, issues and releases - **Documentation**: [developers.openai.com/codex](https://developers.openai.com/codex) - **Support**: OpenAI Help Center for billing and usage limits; GitHub issues for the client itself Because the client is open source and the model is not, bug reports split cleanly: anything about sandboxing, the TUI, MCP wiring or config belongs on GitHub, and anything about model behaviour or quota belongs to support. ## Frequently Asked Questions ### Is Codex CLI free? The CLI itself is free, Apache-2.0 licensed software. What costs money is the model behind it: you either sign in with a paid ChatGPT plan and draw on its usage allowance, or supply an API key and pay per token. ### Which model does Codex use by default? GPT-6 Astra. It became the bundled default in Codex CLI 0.153.4 on September 4, 2026, the day OpenAI shipped it. You can still switch to GPT-5.6 Sol, Terra or Luna mid-session with the /model command, and change reasoning effort at the same time. ### Can I use GPT-6 Astra on a cheap ChatGPT plan? Astra appears on the paid plans, but its allowance is the tightest of any Codex model — roughly 5 to 45 local messages per five-hour window on Plus and Business, against 10 to 100 on GPT-5.6 Sol and 250 to 2,000 on Luna. Pro multiplies those by 5x or 20x. ### What is the difference between Codex CLI and Claude Code? Both are terminal-first coding agents with MCP support and an OS-level sandbox. Codex runs OpenAI models and is Apache-2.0 open source; Claude Code runs Anthropic models and is proprietary. The practical difference is which model you want driving your repository. ### Does Codex run my code without asking? Not by default. The default sandbox mode is workspace-write with network access disabled, and the approval policy prompts before anything escalates out of the workspace. danger-full-access removes both, which is why it is named that way. ### What is AGENTS.md? A Markdown file in your repository holding standing instructions for the agent — build commands, conventions, things not to touch. Run /init and Codex generates a starting version by reading the project. ### Do the CLI and the web version share usage limits? Yes. Local messages and cloud chats draw on the same rolling five-hour window, so a heavy CLI session eats into the allowance you would otherwise spend on cloud tasks. ## Related ### Related tools - [Claude Code](https://howaiworks.ai/ai-tools/claude-code) - [Cursor](https://howaiworks.ai/ai-tools/cursor) - [GitHub Copilot](https://howaiworks.ai/ai-tools/github-copilot) - [Aider](https://howaiworks.ai/ai-tools/aider) - [Cline](https://howaiworks.ai/ai-tools/cline) --- Source: https://howaiworks.ai/ai-tools/openai-codex — HowAIWorks.ai