OpenAI Codex — Administrator & Developer Guide

1. Architecture Overview

OpenAI Codex is a locally-running agentic coding assistant built primarily in Rust, with TypeScript and Python SDK wrappers. The system is structured as a multi-crate Cargo workspace (codex-rs/) containing 100+ crates, with a thin npm CLI wrapper (codex-cli/) and SDKs (sdk/typescript, sdk/python).

The architecture follows a layered model: a core agent engine processes prompts through the OpenAI Responses API, a sandboxed execution layer runs commands and applies file changes, a protocol layer defines the typed message contract between components, and multiple surface layers (TUI, CLI exec, app server, MCP server) expose the agent to different contexts.

┌─────────────────────────────────────────────────┐
│                   User Surfaces                  │
│  ┌──────┐  ┌──────┐  ┌──────────┐  ┌─────────┐ │
│  │ TUI  │  │ Exec │  │App Server│  │MCP Server│ │
│  └──┬───┘  └──┬───┘  └────┬─────┘  └────┬────┘ │
│     └────┬────┘           │              │      │
│          ▼                ▼              ▼      │
│  ┌───────────────────────────────────────────┐  │
│  │           App Server Protocol             │  │
│  │        (JSON-RPC over stdio/WS)           │  │
│  └───────────────────┬───────────────────────┘  │
│                      ▼                          │
│  ┌───────────────────────────────────────────┐  │
│  │              codex-core                   │  │
│  │  Session │ Agent │ Tools │ Config │ Memory │  │
│  └────────┬──────────┬───────────────────────┘  │
│           │          │                          │
│     ┌─────▼────┐ ┌───▼──────┐                  │
│     │ Exec     │ │ Sandbox  │                  │
│     │ Server   │ │ Layer    │                  │
│     └──────────┘ └──────────┘                  │
│  ┌───────────────────────────────────────────┐  │
│  │         Model Providers                   │  │
│  │   OpenAI │ Ollama │ LM Studio            │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

Component Inventory

Technology Stack

Note

The codex-rs/arg0 crate enables a single binary to serve multiple entry points. The binary detects how it was invoked by name (e.g., codex, codex-exec, codex-linux-sandbox, codex-mcp-server) and dispatches to the correct sub-entry-point. This powers the platform-specific sandbox helpers without requiring separate binaries.

Data Flow: Interactive Session

1. User launches codex → codex-cli parses args → dispatches to codex-tui
2. TUI initializes codex-app-server (in-process or via stdio/WebSocket)
3. App server creates a codex-core session with the user's config
4. User types a prompt → app server forwards to core session
5. Core session sends the prompt to the OpenAI Responses API
6. Model response may include tool calls (shell, apply-patch, MCP, web search)
7. For shell commands: codex-exec-server executes inside codex-sandboxing
8. Approval flow: TUI presents approval dialog → user accepts/declines
9. Tool output feeds back into the conversation → model continues
10. Session state persists to codex-state SQLite DB

2. System Requirements

Runtime Requirements

Build Requirements

Important

The Linux sandbox requires kernel 5.13+ for Landlock LSM support. On older kernels, the sandbox falls back to a more permissive mode with a warning. WSL1 is explicitly unsupported — WSL2 is required.

3. Configuration Reference

Config File Locations

Config Layering (Precedence: highest wins)

1. CLI/Session overrides (-c key=value) — highest precedence
2. MDM managed preferences (macOS only)
3. System managed config (managed_config.toml)
4. Project config (.codex/config.toml)
5. User config (~/.codex/config.toml) — lowest precedence

Note

The merge strategy is "first writer wins" via merge_unset_fields — higher-precedence layers fill in values, lower layers only fill gaps. The apps field uses a special union-with-disable-propagation: if any layer sets enabled = false for an app, it stays disabled regardless of higher layers.

Complete Configuration Keys

Core Settings

Approval and Sandbox

Sandbox Workspace-Write Settings

[sandbox_workspace_write]
writable_roots = ["/path/to/extra/dir"]
network_access = true
exclude_tmpdir_env_var = false
exclude_slash_tmp = false

MCP Server Configuration

[mcp_servers.my-server]
# Stdio transport
command = "node"
args = ["path/to/server.js"]

# OR HTTP transport
# url = "https://mcp.example.com"

Model Providers

[model_providers.my-provider]
# Custom provider configuration
# Built-in IDs (openai, ollama, lmstudio) cannot be overridden

Agent Configuration

[agents]
max_threads = 4
max_depth = 3
job_max_runtime_seconds = 300

Web Search

Session and History

Authentication

Analytics and Telemetry

[analytics]
enabled = true

[feedback]
enabled = true

[otel]
# OpenTelemetry configuration

check_for_update_on_startup = true

Named Profiles

[profiles.fast]
model = "gpt-4o"
service_tier = "fast"

[profiles.secure]
sandbox_mode = "read-only"
approval_policy = "untrusted"

Activate with profile = "fast" or --profile fast.

Windows-Specific

[windows]
# Windows-specific settings

Audio (Realtime)

[audio]
microphone = "default"
speaker = "default"

Environment Variables

Important

CODEX_HOME determines the root for all persistent state: config, auth credentials, SQLite databases, session logs, and plugin cache. Changing it redirects all state.

Requirements Enforcement

The requirements.toml file (deployed via MDM or system management) constrains which config values are valid:

allowed_sandbox_modes = ["read-only", "workspace-write"]
allowed_approval_policies = ["on-request", "untrusted"]
allowed_approvals_reviewers = ["user"]

Caution

Any allowed_sandbox_modes list must include read-only or the config is rejected at startup. This is a safety invariant enforced in the config loader.

4. Deployment & Scaling

Distribution Methods

npm Package Structure

The @openai/codex npm package is a meta-package that depends on platform-specific optional packages:

• @openai/codex-linux-x64
• @openai/codex-linux-arm64
• @openai/codex-darwin-x64
• @openai/codex-darwin-arm64
• @openai/codex-win32-x64
• @openai/codex-win32-arm64

The staging script (scripts/stage_npm_packages.py) downloads native artifacts, hydrates vendor/ for each package, and writes tarballs to dist/npm/.

Enterprise Deployment

For managed environments, deploy configuration via:

1. Managed config file: Place managed_config.toml at the system config path
2. MDM (macOS): Deploy managed preferences via MDM profile
3. Requirements: Deploy requirements.toml to enforce policy constraints (allowed sandbox modes, approval policies, etc.)
4. Environment variables: Set CODEX_HOME and OPENAI_API_KEY via system environment

App Server Modes

The app server (codex-app-server) supports three transport modes:

# Run as stdio server (for IDE extensions)
codex app-server --listen stdio://

# Run as WebSocket server
codex app-server --listen ws://0.0.0.0:4222

# With authentication
codex app-server --listen ws://0.0.0.0:4222 --auth-token-env MY_SECRET

Warning

WebSocket transport without authentication exposes the agent to the network. Always use --auth-token-env in production.

5. Operations

Session Management

Sessions are persisted in a SQLite database (WAL mode) under CODEX_HOME. Each session is a "thread" with:

• Unique thread ID
• Conversation history
• Working directory context
• Git info (branch, repo)
• Token usage counters

List sessions:

codex resume --all

Clear memories:

codex debug clear-memories

Memory Pipeline

Codex implements a two-phase memory pipeline that extracts and consolidates learnings across sessions:

Phase 1 (Rollout Extraction): Runs at session start. Claims recent rollouts from the state DB, sends each to the model for structured memory extraction, stores outputs as stage-1 records.

Phase 2 (Global Consolidation): Serialized — only one consolidation runs at a time. Loads stage-1 outputs, computes a diff against the previous selection, syncs raw_memories.md and rollout_summaries/ under the memories root, then spawns a consolidation sub-agent.

Note

The memory pipeline only runs for non-ephemeral, non-sub-agent root sessions with memory enabled and a state DB available.

Monitoring and Health

Session recording:

CODEX_TUI_RECORD_SESSION=1 codex

Session logs are written to CODEX_HOME/log/ or the path specified by CODEX_TUI_SESSION_LOG_PATH.

Update checking: Codex checks for updates at startup by default. Disable with:

check_for_update_on_startup = false

Sandbox debug logging (Windows):

SBX_DEBUG=1 codex

Tip

On macOS, use codex sandbox macos --log-denials -- <command> to capture and print Seatbelt sandbox denial events after the command exits.

Token Usage Tracking

Token usage is tracked per session and reported on exit. The TUI shows live rate limit snapshots in the status bar. Configure compaction thresholds to manage token budgets:

model_auto_compact_token_limit = 50000
tool_output_token_limit = 10000

6. Performance

Context Window Management

Codex automatically compacts conversation history when approaching the context window limit. The model_auto_compact_token_limit setting controls the threshold.

Manual compaction is available in the TUI as the /compact command.

Background Terminal Timeout

Long-running background commands are terminated after background_terminal_max_timeout (default: 300000 ms / 5 minutes). Adjust for CI or build tasks:

background_terminal_max_timeout = 600000  # 10 minutes

Agent Concurrency

Multi-agent orchestration is controlled by:

[agents]
max_threads = 4       # Max concurrent agent threads
max_depth = 3         # Max agent nesting depth
job_max_runtime_seconds = 300  # Max runtime per agent job

Model Provider Latency

• service_tier = "fast" routes to lower-latency infrastructure
• service_tier = "flex" routes to higher-availability but potentially slower infrastructure
• Local providers (ollama, lmstudio) eliminate network latency but depend on local GPU

7. Security

Sandbox Architecture

Codex implements defense-in-depth sandboxing across all supported platforms:

Linux (Landlock + bubblewrap + seccomp):

• Creates isolated user namespaces via bubblewrap (--unshare-user --unshare-net)
• Applies Landlock LSM rules for filesystem access control
• Seccomp filters restrict system calls
• Network isolation via namespace separation; managed proxy for approved traffic
• Falls back to vendored bubblewrap if system copy is not available
• WSL1 is explicitly blocked (cannot create user namespaces)

macOS (Seatbelt):

• Uses sandbox-exec with custom Seatbelt profiles
• Filesystem restrictions based on sandbox mode
• Network control per sandbox policy

Windows (Restricted Tokens + ACLs):

• Creates restricted process tokens with dropped privileges
• ACL-based filesystem access control via Windows security APIs
• ConPTY for terminal interaction within sandbox
• Three levels: disabled (default), restricted_token, elevated

Caution

On Windows without the experimental sandbox enabled, workspace-write mode is silently downgraded to read-only. Check the TUI status bar to verify the effective sandbox level.

Execution Policy

The codex-execpolicy crate implements a Starlark-based policy engine that determines which commands are auto-approved vs. escalated for user approval. Policies are defined as Starlark scripts with pattern matching rules.

# Check a command against policy rules
codex execpolicy check -r rules.star -- bash -c "rm -rf /"

Secret Detection

The codex-secrets crate provides regex-based secret detection and sanitization. Patterns are compiled at initialization and applied to:

• Memory pipeline outputs (Phase 1 extraction)
• Tool outputs before display
• Session logs

Authentication Security

Warning

The login flow writes a debug log to CODEX_HOME/log/codex-login.log with mode 0600 on Unix. Ensure this directory has appropriate permissions.

Network Security

When sandbox mode restricts network access, Codex uses a managed network proxy (codex-network-proxy) that:

• Generates per-session CA certificates for MITM inspection
• Applies domain-level allow/deny rules
• Supports HTTP, HTTPS (CONNECT), SOCKS5 protocols
• Routes traffic through the proxy only — direct connections are blocked in the sandbox namespace

Guardian Auto-Reviewer

The Guardian is an experimental automated approval system (approvals_reviewer = "guardian_subagent") that:

• Spawns a sub-agent to assess risk for each approval request
• Classifies risk as Low/Medium/High/Critical
• Evaluates user authorization level
• Auto-approves low-risk operations
• Escalates high-risk operations to the user
• Provides rationale for each decision

8. Developer Internals

Repository Structure

openai/codex/
├── codex-rs/                    # Rust workspace (100+ crates)
│   ├── cli/src/                 # CLI entry point and subcommands
│   ├── tui/src/                 # Terminal UI (Ratatui)
│   ├── core/                    # Agent engine, session, tools, config
│   │   ├── src/                 # Core logic
│   │   ├── templates/           # Prompt templates (memories, review, etc.)
│   │   └── tests/               # Integration tests
│   ├── app-server/src/          # WebSocket/stdio app server
│   ├── app-server-protocol/     # Protocol types + generated TS bindings
│   │   └── schema/              # JSON Schema + TypeScript exports
│   ├── exec/src/                # Non-interactive exec mode
│   ├── exec-server/src/         # Sandboxed command execution service
│   ├── protocol/src/            # Core protocol types
│   ├── config/src/              # TOML config schema + layering
│   ├── sandboxing/src/          # Cross-platform sandbox abstraction
│   ├── linux-sandbox/src/       # Linux sandbox (Landlock/bwrap)
│   ├── windows-sandbox-rs/src/  # Windows sandbox
│   ├── mcp-server/src/          # Codex as MCP server
│   ├── codex-mcp/src/           # MCP client
│   ├── rmcp-client/src/         # Low-level MCP client
│   ├── hooks/src/               # Event hook system
│   ├── execpolicy/src/          # Starlark execution policy
│   ├── apply-patch/src/         # Structured patch applicator
│   ├── state/src/               # SQLite state DB
│   ├── login/src/               # Authentication
│   ├── models-manager/src/      # Model catalog
│   ├── network-proxy/src/       # Managed network proxy
│   ├── secrets/src/             # Secret detection
│   ├── skills/src/              # Skills framework
│   ├── tools/src/               # Shared tool primitives
│   └── ...                      # 60+ utility crates
├── codex-cli/                   # npm CLI wrapper (JS shim)
├── sdk/
│   ├── typescript/src/          # TypeScript SDK
│   └── python/                  # Python SDK (runtime bootstrap)
├── scripts/
│   ├── install/                 # Standalone installers
│   └── stage_npm_packages.py    # npm packaging
├── patches/                     # Vendored patches
└── tools/                       # Dev tools (argument-comment-lint)

Core Module Reference

codex-core (codex-rs/core/src/)

The central engine with 116 files and ~1.5M chars. Key internal modules:

• session/ — Session lifecycle, turn management, agent orchestration
• agent/ — Agent identity, builtins
• tools/handlers/ — Tool dispatch: apply_patch, shell exec, MCP, multi-agent, file search
• config/ — Runtime config processing (14 files, 533K chars)
• config_loader/ — Multi-layer config loading with merge and fingerprinting
• memories/ — Two-phase memory pipeline (extraction + consolidation)
• guardian/ — Automated approval assessment
• context_manager/ — Context window management
• sandboxing/ — Core sandbox coordination
• plugins/ — Plugin loading and marketplace integration
• instructions/ — AGENTS.md and user instruction loading
• unified_exec/ — Unified command execution abstraction
• state/ — State management helpers

codex-tui (codex-rs/tui/src/)

The TUI with 66 files and ~2.2M chars. Key modules:

• app/ — Application state machine, event loop, approval handling
• chatwidget/ — Chat input/display component
• bottom_pane/ — Approval dialogs, MCP elicitation, selection views
• streaming/ — Smooth per-frame streaming animation
• render/ — Terminal rendering pipeline
• markdown_stream/ — Incremental markdown parser
• onboarding/ — First-run experience and auth flows
• history_cell/ — Conversation history display
• status/ — Status bar with rate limits

codex-protocol (codex-rs/protocol/src/)

Protocol types with 28 files and ~553K chars:

• config_types.rs — Sandbox policy, approval policy, network policy types
• models.rs — Response items, content items, tool definitions
• permissions.rs — Permission system types and resolution
• protocol.rs — Session events, turn events, streaming events
• items.rs — Conversation item types
• prompts/ — Base instructions, sandbox mode prompts, permission prompts

codex-config (codex-rs/config/src/)

Configuration with 27 files and ~266K chars:

• config_types.rs — ConfigToml struct with all config fields
• config_requirements.rs — Requirements enforcement and validation
• config_loader/ — Multi-layer loading: state.rs, layer_io.rs, overrides.rs, merge.rs, fingerprint.rs, macos.rs

Hook System

Six hook event types provide extensibility at key lifecycle points:

All hooks share a common output wire format:

• continue (bool, default true) — whether to proceed
• stop_reason — human-readable abort reason
• suppress_output — hide tool output from transcript
• system_message — inject text into model context

Hooks are dispatched sequentially. If any hook returns should_abort_operation() == true, the chain short-circuits.

Apply-Patch Format

Codex uses a custom structured patch format (not unified diff). The codex-apply-patch crate handles parsing and application with operations:

• AddFile — create a new file
• UpdateFile — modify an existing file with context-aware hunks
• DeleteFile — remove a file
• MoveFile — rename/move a file (with optional content update)

Each operation is verified against the current filesystem state before application.

Code Patterns and Conventions

• Error handling: anyhow::Result for application errors, thiserror for library errors
• Async: Tokio-based async throughout; async_trait for trait async methods
• Testing: #[cfg(test)] modules with #[path = "foo_tests.rs"] sibling pattern
• Serialization: serde derive with #[serde(rename_all = "snake_case")] convention
• Config: TOML with Option<T> for all fields (no hardcoded defaults in the struct)
• CLI: clap derive with #[arg(...)] and #[command(...)] attributes
• Workspace dependencies: All external deps declared in root Cargo.toml [workspace.dependencies]
• Build: Hybrid Cargo + Bazel; BUILD.bazel files alongside Cargo.toml
• Linting: Workspace-level lint configuration via [lints] section
• Cross-platform: #[cfg(target_os = "...")] conditionals for platform-specific code

Testing Strategy

• Unit tests: Sibling *_tests.rs files with #[cfg(test)] modules
• Integration tests: tests/ directories in crates like core, app-server, exec-server, mcp-server
• Snapshot tests: Used in TUI (rendering), protocol (serialization), and guardian (assessment)
• End-to-end: codex-app-server-test-client crate provides a full test harness
• Apply-patch fixtures: codex-rs/apply-patch/tests/fixtures/scenarios/ contains 22+ scenario directories with input/expected/patch triplets
• Mock model server: Test infrastructure includes mock OpenAI Responses API servers

SDK Architecture

TypeScript SDK (@openai/codex-sdk):

• Wraps the Codex CLI binary as a subprocess
• Runs codex exec --experimental-json for JSONL streaming
• Parses JSONL events into typed ThreadItem and ThreadEvent objects
• Supports AbortSignal for cancellation
• Config overrides flattened to TOML dotted-key CLI flags

Python SDK (sdk/python):

• Runtime bootstrap only — not a user-facing API
• Downloads platform-specific Codex binary from GitHub Releases
• Installs as codex-cli-bin pip package
• Pinned to specific version (0.116.0-alpha.1 in source)
• Fallback chain: direct URL → GitHub API with token → gh CLI

Potential Improvements

Based on code analysis:

• codex-tools extraction: The codex-tools crate is intentionally minimal — extracting tool primitives from codex-core in reviewable increments. Full migration is planned but not yet complete.
• Config layer complexity: The 5-layer config merge with special apps union semantics and requirements enforcement is powerful but complex. Consider documenting the effective config resolution path for debugging.
• Windows sandbox maturity: Windows sandbox defaults to disabled. The restricted_token and elevated levels are functional but less tested than Linux/macOS equivalents.
• Memory pipeline observability: Phase 2 consolidation runs a sub-agent with no approvals and local write access. Consider adding observability hooks for enterprise deployments.
• Apply-patch error recovery: Partial application failures leave changes in place (015_failure_after_partial_success_leaves_changes). Consider a rollback-on-failure mode.

Contributing

The project uses Apache-2.0 license. Key conventions for contributors:

1. Tests: Place unit tests in sibling *_tests.rs files, not inline
2. Dependencies: Add to [workspace.dependencies] in root Cargo.toml, reference with { workspace = true }
3. New crates: Follow the codex-rs/ workspace pattern; keep src/lib.rs exports-only
4. CLI args: Use clap derive macros with descriptive value_name and help attributes
5. Config fields: All Option<T> — no hardcoded defaults in the struct
6. Platform code: Use #[cfg(target_os = "...")] guards; provide stubs for unsupported platforms
7. ToC updates: Run scripts/readme_toc.py --fix after modifying headings in README

9. Integration Points

App Server Protocol (JSON-RPC)

The app server protocol defines ~200+ typed messages across two versions:

V1 types: ClientRequest, ClientNotification, ServerRequest, ServerNotification — covering initialization, auth, fuzzy file search, conversation summaries, exec approval, patch approval.

V2 types: Extended protocol with threads, config management, MCP server management, plugins, skills, file system operations, command execution, model management, feature flags, and more.

Transport: JSON-RPC 2.0 over stdio or WebSocket.

MCP Integration

Codex supports MCP in both directions:

As MCP client (codex-codex-mcp): Connects to configured MCP servers, calls tools, handles OAuth authentication, manages elicitation forms.

As MCP server (codex-mcp-server): Exposes Codex capabilities as MCP tools over stdio transport. Other MCP clients can call Codex tools.

TypeScript SDK Integration

import { Codex } from "@openai/codex-sdk";

const codex = new Codex({
  config: {
    model: "gpt-5",
    sandbox_mode: "workspace-write",
  },
});

const thread = codex.startThread({
  workingDirectory: "/path/to/project",
});

// Structured output
const turn = await thread.run("Analyze codebase", {
  outputSchema: {
    type: "object",
    properties: {
      summary: { type: "string" },
      issues: { type: "array", items: { type: "string" } },
    },
    required: ["summary", "issues"],
  },
});

Responses API Proxy

The codex-responses-api-proxy binary proxies requests to the OpenAI Responses API:

codex-responses-api-proxy \
  --upstream https://api.openai.com/v1/responses \
  --api-key-file ~/.openai/key \
  --listen 0.0.0.0:8080

OpenTelemetry

Codex supports OpenTelemetry export via the codex-otel crate:

[otel]
# OpenTelemetry configuration

Metrics and traces cover session lifecycle, tool execution, model calls, and sandbox operations.