Skip to main content
Codex CLI is built as a native, zero-dependency executable with a hybrid architecture combining Rust and TypeScript components.

​
Monorepo Structure

The Codex repository is organized as a monorepo with two primary components:

Rust Workspace

Core business logic, TUI, and native execution (codex-rs/)

TypeScript CLI

Wrapper for distribution and platform-specific integration

​
Architecture Layers

The Codex architecture is structured in distinct layers:

​
1. Distribution Layer (TypeScript)

The TypeScript CLI wrapper provides:
  • npm packaging — Install via npm i -g @openai/codex
  • Platform detection — Routes to the correct native binary
  • Zero-dependency install — All native binaries are bundled

​
2. Core Implementation (Rust)

The codex-rs Rust workspace contains the complete implementation:
The codex-core crate implements all Codex business logic:
  • Conversation management and turn execution
  • Model interaction and streaming
  • Tool execution and sandboxing
  • Configuration and state management
  • Designed as a library crate for reuse across UIs
Multiple frontend options built on codex-core:
  • TUI (codex-tui) — Fullscreen terminal interface using Ratatui
  • Exec (codex-exec) — Headless CLI for automation and scripts
  • App Server (codex-app-server) — JSON-RPC server for IDEs and integrations
  • CLI (codex-cli) — Multitool that provides all above via subcommands
Platform-specific sandboxing and security:
  • macOS — Seatbelt sandbox profiles
  • Linux — Landlock and Bubblewrap isolation
  • Windows — Process isolation and restrictions
  • Cross-platform — Process hardening and security primitives

​
3. Integration Points

Codex integrates with external systems through multiple interfaces:

​
Key Design Principles

Native Performance

Built in Rust for fast startup and efficient resource usage

Platform Security

OS-specific sandboxing on macOS, Linux, and Windows

Modular Architecture

Shared core library with multiple interface options

Zero Dependencies

Self-contained binaries with no runtime requirements

​
Workspace Organization

The Rust workspace in codex-rs/ uses Cargo workspaces with 60+ crates organized by function:
  • Core crates — core, cli, tui, exec, app-server
  • Sandbox crates — linux-sandbox, process-hardening
  • Protocol crates — protocol, app-server-protocol, rmcp-client
  • Integration crates — mcp-server, lmstudio, ollama
  • Utility crates — utils/* for common functionality
All workspace crates are prefixed with codex-. For example, the core folder contains the codex-core crate.

​
Configuration Management

Codex uses a layered configuration system:
  • User config — ~/.codex/config.toml (TOML format)
  • Requirements — requirements.toml for constraints and policies
  • MDM integration — Enterprise management on supported platforms
The Rust implementation uses config.toml instead of the legacy config.json format.

​
Next Steps

Rust Crates

Explore the workspace structure and crate purposes

TUI Architecture

Learn about the terminal interface implementation

Sandboxing

Understand platform-specific security isolation

App Server

JSON-RPC protocol for IDE integration