codex

OpenAI Codex CLI is a lightweight, locally-running AI coding agent built by OpenAI and written primarily in Rust. It runs entirely on your machine, accepts plain-language instructions, and autonomously reads files, writes code, runs shell commands, and iterates until the task is complete — all without leaving your terminal.

The agent integrates with OpenAI’s models (including GPT-4.1 and the dedicated Codex model family) and exposes both an interactive TUI mode and a non-interactive exec mode suitable for scripting and CI pipelines. A multi-transport app-server protocol lets IDE extensions (VS Code, Cursor, Windsurf) embed the same agent engine through a structured WebSocket or stdio API.

Security is a first-class design goal. Codex isolates each command execution using platform-native sandboxing — macOS Seatbelt, Linux Landlock + bubblewrap, and Windows restricted tokens — so the agent cannot access the network or filesystem paths you did not grant. An exec-policy engine lets teams define fine-grained allow/deny rules for which shell commands the agent may run without requesting approval.

Beyond single-machine use, Codex supports Codex Cloud tasks, where work is dispatched to remote execution environments and the resulting diff is pulled back locally. Session management lets you resume, fork, or archive conversations across terminals and IDE extensions, preserving the full context of prior interactions.

What You Get

• Interactive TUI with a full terminal user interface for conversational coding sessions that retain context across turns
• Non-interactive exec mode (codex exec) for running agent tasks from scripts, CI pipelines, or shell one-liners
• Platform-native sandboxing via macOS Seatbelt, Linux Landlock + bubblewrap, and Windows restricted tokens to isolate agent-spawned processes
• Exec-policy engine with a declarative allow/deny rule file controlling which shell commands the agent can run autonomously
• App-server protocol (stdio, Unix socket, WebSocket) enabling VS Code, Cursor, and Windsurf IDE extensions to embed the same agent
• Session persistence — save, resume, fork, archive, and delete conversations by UUID or name across terminals
• MCP (Model Context Protocol) client support for connecting external tools and resources to the agent
• Codex Cloud integration for dispatching tasks to remote execution environments and applying the resulting diffs locally

Common Use Cases

• Automated refactoring — describe a structural change in plain English and let the agent rewrite the affected files while you review the diff
• Bug fixing pipelines — pipe a failing test output into codex exec to diagnose and patch the failure non-interactively
• IDE-embedded assistance — use the VS Code or Cursor extension backed by the same local agent for inline coding help without a separate chat window
• Exploratory code review — open an interactive session on an unfamiliar codebase and ask the agent to walk you through architecture, dependencies, and entry points
• Task automation in CI — run codex exec in a GitHub Actions step to apply routine code-generation tasks and commit the output
• Remote cloud tasks — queue work in Codex Cloud and apply the finished diff to a local checkout via codex cloud

Under The Hood

Architecture Codex is structured as a layered Rust workspace where a thin CLI binary composes a network of loosely coupled crates rather than a single monolith. The codex-core crate owns the conversation thread, prompt construction, model streaming, and tool-call dispatch; the codex-exec crate handles non-interactive mode; codex-tui owns the terminal UI; and codex-app-server exposes a multi-transport API consumed by IDE extensions. Sandboxing is kept in a dedicated codex-sandboxing crate that the execution layer calls through a stable policy interface, so platform sandboxes (Seatbelt, Landlock, Windows restricted tokens) can evolve independently. The exec-policy engine lives in its own codex-execpolicy crate with parser, evaluator, and rule types fully isolated from the rest of the agent. This separation means a change to sandboxing does not ripple into the conversation layer, and adding a new transport to the app-server does not touch the TUI.

Tech Stack The primary implementation language is Rust, using Tokio as the async runtime with multi-thread scheduling throughout. The CLI is built with Clap (derive macros), and the TUI uses Crossterm for cross-platform terminal control. Model communication goes through OpenAI’s Responses API; the codebase includes a first-party codex-responses-api-proxy for routing and a codex-rmcp-client for MCP protocol connections. Build tooling supports both Cargo and Bazel (via MODULE.bazel), with a Nix flake for reproducible dev environments. The SDK layer ships TypeScript and Python bindings generated from the app-server protocol schema. Platform sandboxing uses macOS Seatbelt policy files (.sbpl), Linux Landlock syscall interface via the landlock crate, and bubblewrap for namespace isolation on Linux.

Code Quality The codebase has extensive inline test coverage: dedicated _tests.rs files accompany nearly every core module (safety, connectors, compact, exec_env, event_mapping, codex_delegate, client, apply_patch, agents_md, and more), and integration tests run through Wiremock for API mocking and assert_cmd for CLI subprocess testing. Error handling uses anyhow for contextual propagation throughout, with typed Result aliases in domain-specific crates (execpolicy, sandboxing). The workspace enforces Clippy lints via a root clippy.toml, rustfmt.toml for formatting, and Cargo Deny for dependency auditing. CI runs on all three target platforms. Snapshot testing via insta is used for prompt and output regression coverage. The overall quality signal is strong: typed, linted, tested, and CI-gated across platforms.

What Makes It Unique The combination of a sandboxed, policy-driven execution engine with a multi-transport app-server protocol is the distinguishing technical choice. Most terminal coding agents treat sandboxing as an optional afterthought; Codex makes it a required, platform-specific implementation in a dedicated crate. The exec-policy rule language lets teams codify exactly which shell commands the agent may run autonomously versus which require approval — a capability designed for enterprise and team deployments rather than solo use. Additionally, the app-server protocol with TypeScript schema generation means IDE vendors get a versioned, typed contract for embedding the agent rather than scraping terminal output. The session fork and resume model, backed by persistent SQLite state, also sets it apart from stateless agent tools.

Self-Hosting

OpenAI Codex CLI is released under the Apache License 2.0, which is a permissive open-source license. You can use it commercially, modify the source, distribute it in proprietary products, and sublicense it without any copyleft obligations — meaning you are not required to open-source derivative works. The only conditions are attribution (preserving the Apache copyright notice) and that modified files carry a notice of changes. There is no network-use clause or server-side public license, so running Codex on your own infrastructure imposes no additional license requirements.

Running Codex yourself means you are responsible for API key management, network access to OpenAI’s endpoints, and keeping the binary up to date via codex update or your package manager. The tool stores session state locally in SQLite under ~/.codex/ and writes credentials to the system keyring. Infrastructure needs are minimal — it is a single statically linked binary — but you will need a valid OpenAI API key or ChatGPT account to authenticate, and your machines must be able to reach api.openai.com. The sandboxing subsystem (Seatbelt on macOS, Landlock + bubblewrap on Linux) is set up automatically, though Linux users may need to ensure bwrap is installed on their system.

The self-hosted open-source CLI gives full control over which model you target and how sessions are stored, but it does not include the managed infrastructure behind Codex Web (chatgpt.com/codex) — the cloud-based agent that runs in an OpenAI-managed execution environment with its own compute, persistent repos, and team collaboration features. If you need those capabilities (parallel cloud tasks, managed compute, team-level task queues), you would need a ChatGPT Pro or Enterprise subscription and access to Codex Cloud. The open-source CLI does integrate with Codex Cloud via codex cloud commands, but the compute and scheduling layer itself is OpenAI-operated.