System breakdown

Inside OpenAI Codex: TUI, App Server, and Execution Boundaries

A commit-pinned examination of the documented Codex rich-client protocol, terminal event loop, approval exchange, and platform sandbox boundary.

14 min read Verified 2026-07-21 3 primary sources

Canonical System Breakdown

OpenAI Codex rust-v0.95.0 architecture evidence

RELEASE rust-v0.95.0

2 CHAPTERS · 8 NODES · 7 EDGES

Ingress Security

HMAC SHA256

Constant-time verify (<50ms)

Async Queueing

Sidekiq + Redis

Multi-queue priority isolation

Real-time Fanout

ActionCable Pub/Sub

Redis backplane state broadcast

AI Action Engine

ActionService LLM

Streaming copilot replies (SSE)

Core Stack:Rails 7.1•Sidekiq 7•Redis 7.2•PostgreSQL 16•Vue.js 3

3 Verified Architectural Claims

rust-v0.95.0

Commit 12dbb76

Review 2026-10-19

Verified: 2026-07-21·openai/codex

Step 1 of 3 · Rich-client protocol

Architectural Pillars Taxonomy2 of 2 chapters

Chapter 1 of 2

The documented app-server boundary between a rich client and Codex session execution.

100%

Step Execution TraceStep 1 of 3

#1Initialize the protocol

The client sends initialize and then the initialized notification.

Architecture Specification4 signals— Initialize the protocol

Data in Transit

InitReq→ payload

PID

1234

Data in Transit

CLIENT_STATE

INITIALIZING

PROTOCOL_VERSION

1.0

CONNECTION_STATUS

PENDING

Evidence — 1 source

verified

codex-v095-app-server

README.md lines 45-55

verified 2026-07-21

codex-rs/tui/src/app.rs(L50-L80)

rustGitHub

client.initialize(InitializeParams {
    process_id: std::process::id(),
})

Component Inspector

Click any component node in the diagram above to inspect its source code location, evidence classification, and implementation details.

Verified System Claims

#app-server-protocol

verified

The app-server exposes a bidirectional JSON-RPC protocol over streaming JSONL and organizes work as threads, turns, and items.

↳ codex-v095-app-server › README.md lines 22-45 and 433-455

#tui-event-loop

verified

The terminal interface receives TUI events, dispatches application events, handles Codex events, and renders the active chat widget.

↳ codex-v095-tui › codex-rs/tui/src/app.rs App::handle_event and render paths

#sandbox-boundary

verified

Command execution is constrained by platform-specific sandbox implementations and may require an explicit approval exchange.

↳ codex-v095-app-server › README.md approval requests around line 515

↳ codex-v095-sandbox › codex-rs/linux-sandbox/src

SYSTEM DESIGN THEORY & PATTERNS

4 Core Engineering Patterns

How to Build This System: Architectural Patterns & Theory

Deep-dive into the foundational distributed systems principles, security proofs, concurrency models, and failure modes required to build an enterprise real-time engagement platform from scratch.

1. Multi-Channel Webhook Ingress & HMAC-SHA256 Security

Authenticate incoming HTTP webhooks from external channels (Meta WhatsApp, Telegram, Twilio) without exposed state or session cookies.

The Architectural Problem

Public HTTP webhook endpoints are exposed to spoofing attacks, replay attacks, and parameter tampering. Naive string comparison (`==`) creates timing attack vulnerabilities where attackers determine secret characters by measuring sub-nanosecond comparison responses.

The System Solution

Compute an HMAC-SHA256 digest of the raw request payload using the tenant's channel secret key, then verify the payload signature using constant-time comparison (`ActiveSupport::SecurityUtils.secure_compare`).

Constant-Time Comparison Theory

Standard string equality tests terminate as soon as the first byte mismatch occurs ($O(k)$ where $k$ is matching prefix length). Timing attacks measure variance in microsecond execution times to iteratively forge valid signatures. Constant-time comparison ($O(n)$ where $n$ is length) processes all bytes regardless of mismatches.

💡 HMAC(K, M) = H((K' ⊕ opad) ∥ H((K' ⊕ ipad) ∥ M))

Reference Implementationapp/controllers/concerns/webhook_verifier.rb

# Constant-time HMAC SHA256 Signature Verification
module WebhookVerifier
  def verify_signature
    signature = request.headers['X-Hub-Signature-256']
    secret = Current.account.webhook_verify_token
    
    # Compute digest over raw unparsed request stream
    expected = 'sha256=' + OpenSSL::HMAC.hexdigest('sha256', secret, request.raw_post)
    
    # Constant-time comparison prevents timing side-channel attacks
    unless ActiveSupport::SecurityUtils.secure_compare(signature, expected)
      head :unauthorized
    end
  end
end

Architectural Trade-offs & Choices

⚖️ Raw Request Body Buffering

+ Benefit: Enables exact byte digest matching even if JSON params are re-ordered by middleware.

- Downside: Requires reading raw POST stream into memory before Rails parameter parsing.

⚖️ Timing-Safe Comparison (`secure_compare`)

+ Benefit: Completely eliminates side-channel timing attack vectors.

- Downside: Slight CPU overhead ($O(N)$ comparisons for every request).

Production Failure Modes & Defense

⚠️ Risk: Replay Attacks with Stale Payloads

🛡️ Defense: Validate `X-Hub-Timestamp` or payload `timestamp` header; reject signatures older than 300 seconds.

⚠️ Risk: Middleware Payload Mutation

🛡️ Defense: Always compute digest on `request.raw_post` before Rack or Rails mutates body params.

Evidence boundary

This breakdown describes release rust-v0.95.0 at commit 12dbb76c812afaff8daf1f3a5acf1d5ef4a75cb1. It intentionally does not infer a hidden daemon database, universal build pipeline, mandatory module-size rule, or automatic workspace-context collection. Those claims were not supported by the pinned sources.

Architecture at a glance

Rich client

Initialize app-server

Start or resume thread

Start turn

Stream item lifecycle

Render and control

Conceptual teaching model synthesized from:lesson evidence registry

The app-server documentation defines a bidirectional JSON-RPC protocol transported as streaming JSONL. Its public mental model is a thread containing turns, with each turn producing items and lifecycle notifications. That boundary is useful because it lets clients render incremental progress without coupling the article to undocumented internal ownership.

Terminal event flow

The pinned TUI application receives terminal events and application events, handles Codex execution events, updates interface state, and renders the active chat widget into a terminal frame. The interactive inspector separates this verified source behavior from compressed arrows that are explicitly labeled as inferred.

Approval and sandboxing

The app-server protocol documents server-initiated approval requests for consequential actions. The repository also contains platform-specific sandbox implementations. The inspector presents their combined role as a conceptual control model, not as a claim that one undocumented function directly owns the entire sequence.

Alternatives and trade-offs

| Boundary | Benefit | Cost or risk | |---|---|---| | JSON-RPC app-server | Version-specific schemas and incremental events for rich clients | Clients must implement initialization, cancellation, approvals, and item state correctly | | Terminal TUI | Direct keyboard-driven workflow and visible execution state | High-frequency event and render paths require careful state coordination | | Platform sandbox | Limits command capabilities according to policy and OS support | Isolation semantics and setup differ across operating systems |

Failure modes

Treating an inferred diagram edge as a named runtime component.
Assuming every client uses the app-server in the same process topology.
Equating approval with containment; an approved command still needs an appropriate execution boundary.
Generalizing one platform sandbox implementation to every supported operating system.
Reading the current repository branch while claiming behavior for this pinned release.

Reflect before revealing the guide

Why should the app-server protocol, approval exchange, and platform sandbox be documented as separate boundaries?

Architectural takeaway

Codex is best understood through its public protocols and source-backed control boundaries. A reliable architecture explanation pins a release, traces named interfaces, and marks every compression or teaching abstraction instead of filling unknowns with plausible internals.