App Server and Code Mode
Overview
The app-server stack is the long-lived JSON-RPC surface used by Codex UI clients, daemonized local clients, in-process embedders, and remote-control sessions. The standalone binary in codex-rs/…/main.rs parses startup flags, resolves the selected transport (stdio://, unix://, ws://IP:PORT, or off), configures code-mode host routing, websocket auth, session source, managed-daemon mode, and plugin launch options, then delegates to run_main_with_transport_options in codex-rs/…/lib.rs.
codex-rs/…/lib.rs owns process lifecycle. Startup loads config through ConfigManager, initializes auth, state/log databases, environment management, telemetry, model/plugin startup workers, optional runtime-agent auth, and the code-mode session provider. The server then starts acceptors from codex-rs/app-server-transport/src/transport/*: stdio for a single process-bound client, a private Unix/Windows control socket, a TCP websocket listener, and optional remote-control websocket enrollment. Incoming transport events are reduced to TransportEvent values and processed in the main processor loop; outgoing messages flow through a separate outbound router so slow writes do not block request dispatch.
Local shutdown is coordinated in codex-rs/…/lib.rs. In stdio mode, EOF closes the process. In socket/websocket modes, signal handling starts graceful restart drain: new connection-oriented clients can be disconnected, active turn admissions and running turns are watched, and managed-daemon shutdown snapshots loaded threads to the recovery file path from codex-rs/…/mod.rs. Unix managed-daemon processes additionally raise the file descriptor limit in codex-rs/…/managed_daemon.rs.
The app-server wire contract lives in codex-rs/app-server-protocol/src. codex-rs/…/rpc.rs defines the repository's JSON-RPC-shaped messages; the code intentionally does not require a jsonrpc: "2.0" field. codex-rs/…/mod.rs re-exports the large v2 request/response/notification namespace for accounts, config, threads, turns, MCP, plugins, processes, remote control, models, projects, filesystem operations, and diagnostics. codex-rs/…/lib.rs also re-exports selected v1 compatibility types, schema/export helpers, and test-only schema generation derives. Production protocol builds use the no-op derive macros in codex-rs/…/lib.rs; test/export builds use real schemars and ts-rs derives.
Request routing is centered in codex-rs/…/message_processor.rs. Each connection has a ConnectionSessionState with an initialize gate, capability flags, MCP event streams, and a per-connection RPC gate. process_request first deserializes raw JSONRPCRequest into ClientRequest, rejects obsolete fields such as permissionProfile for thread/turn methods, and special-cases initialize. After initialization, dispatch_initialized_client_request enforces experimental API opt-in, acquires turn-admission permits for thread/turn mutations, starts MCP event streams when requested, and either runs the request immediately or enqueues it in codex-rs/…/request_serialization.rs by serialization scope. handle_initialized_client_request then matches every ClientRequest variant and delegates to processors under codex-rs/app-server/src/request_processors/**.
Responses, server requests, and notifications are funneled through codex-rs/…/outgoing_message.rs. It tracks in-flight client requests, pending server callbacks, cancellation scopes, human-approval and user-verification recipients, and thread-scoped senders. Final routing to physical connections is in codex-rs/…/transport.rs: messages can target one connection or broadcast; per-connection state filters experimental notifications and client opt-outs, strips experimental approval fields for non-experimental clients, and disconnects slow websocket-like clients whose bounded outbound queues fill.
The app server has three local client shapes. Socket/stdio remote clients use codex-rs/…/remote.rs, which connects over TCP websockets or websocket-over-UDS, performs the initialize/initialized handshake, tracks pending request IDs, routes server requests back to callers, and exposes a uniform AppServerEvent stream. Compression negotiation and framed zstd message history are in codex-rs/…/remote_websocket.rs and mirror the server-side compression code in codex-rs/…/websocket_compression.rs. In-process embedders use codex-rs/…/in_process.rs, wrapped by codex-rs/…/lib.rs; this path preserves the same MessageProcessor semantics but replaces sockets with bounded channels, performs the initialize handshake internally, and exposes typed request helpers plus one-shot AppServerReplyHandles from codex-rs/…/server_request.rs. Cloud/native surfaces use codex-rs/…/cloud.rs and codex-rs/app-server-client/src/cloud_backend/** for operations that are not forwarded to another backend, such as scoped resume preparation, project-thread startup, user-message submission, and thread-title updates.
Daemon lifecycle is implemented by codex-rs/app-server-daemon/src. codex-rs/…/lib.rs defines lifecycle commands and state paths under app-server-daemon/, including pid files, update pid files, daemon.lock, and settings.json. codex-rs/…/launch.rs serializes start/restart feature overrides under the operation lock and verifies platform restrictions. codex-rs/…/client.rs probes the control socket by opening websocket-over-UDS, sending initialize, then parsing the app-server version from the returned user-agent. codex-rs/…/settings.rs stores remote-control enablement, feature overrides, auto-update settings, and shutdown grace. codex-rs/…/update_loop.rs owns scheduled/manual installs, daemon restarts, legacy migration, and updater replacement.
Remote-control transport is part of codex-rs/app-server-transport/src/transport/remote_control/**. mod.rs coordinates persisted enrollment, desired state, retry-after backoff, auth recovery, pairing, client tracking, and websocket channels. App-server startup chooses a RemoteControlStartupMode in codex-rs/…/main.rs; run_main_with_transport_options starts remote control only when policy, persisted/ephemeral preference, state DB availability, and runtime auth settings allow it. RPC methods such as remoteControl/enable, pairing, client listing, and revoke are handled in codex-rs/…/message_processor.rs via RemoteControlRequestProcessor.
Runtime-agent instances are an auth support layer for OpenAI runtimes. codex-rs/…/manager.rs binds one RuntimeAuthManager to login credentials and registration metadata, then lazily creates credential-specific RuntimeAuthBindings for login, provider, or explicit API-key sources. codex-rs/…/registration.rs posts bounded composite registration requests to the auth endpoint without redirects, reusing the pending registration's idempotency key across retries. codex-rs/…/runtime.rs keeps the generated Ed25519 signing key in memory and signs a fresh v1 assertion for each request attempt or connection handshake. codex-rs/…/auth.rs converts the selected runtime/credential pair into request-scoped auth headers, either dual Authorization plus x-openai-agent-assertion or assertion-only, while preserving account-bound network policy.
Code mode is the durable execution subsystem used by app-server threads. The protocol traits and wire types are in codex-rs/code-mode-protocol/src: session.rs defines CodeModeSessionProvider, CodeModeSession, delegates, cell IDs, output truncation ownership, and execution limits; runtime.rs defines exec/wait/terminate requests, runtime responses, pending outcomes, nested tool calls, and default yield/output budgets; host/message.rs defines the stdio host IPC handshake and request/response messages; host/codec.rs frames host IPC as 4-byte little-endian length-prefixed JSON with a 64 MiB payload cap. codex-rs/…/lib.rs re-exports this protocol and provides both process-owned stdio and gRPC session providers.
When the app-server starts without --code-mode-host, code mode uses ProcessOwnedCodeModeSessionProvider from codex-rs/…/remote_session.rs. It lazily spawns the configured codex-code-mode-host executable, shares one live connection across sessions, allocates unique session IDs, and caches connection failures by generation so concurrent callers observe the same failure instead of respawning repeatedly. The connection driver under codex-rs/…/driver*.rs sends framed ClientToHost messages, tracks request IDs, sessions, cells, cancellations, yielded observations, and delegate callbacks, and fails all pending requests if the host writer/reader or driver stops.
When --code-mode-host http(s)://... is supplied, codex-rs/…/code_mode_host.rs validates the origin-only URL and codex-rs/…/lib.rs requires the CodeModeHost feature before creating GrpcCodeModeSessionProvider. The gRPC provider in codex-rs/…/mod.rs lazily opens HTTP/2 clients with the app's configured HTTP client factory, requests a session lease, pins the output-truncation mode, and retries only admission failures before execution starts. codex-rs/…/transport.rs supports http://, https://, and unix: endpoints, sends requests with prior-knowledge HTTP/2, disables idle pooling timeouts, and bounds encode/decode size to the host frame limit. codex-rs/…/state.rs enforces execution IDs, callback UUID reuse checks, cell ownership, and delegate lifecycle.
The standalone code-mode host binary is in codex-rs/…/main.rs. It selects stdio, grpc+stdio://, or grpc://IP:PORT via codex-rs/…/transport.rs; hidden --codex-ui-plugin-process runs the UI sandbox entrypoint in codex-rs/…/mod.rs. Legacy stdio hosting is implemented in codex-rs/…/lib.rs: it negotiates protocol version/capabilities, creates HostPeer, applies request/cell/delegate semaphores, routes HostRequest variants to in-process runtime sessions, and shuts down all state when the peer disconnects. codex-rs/…/peer.rs owns framed writes, delegate request permits, per-cell routes, initial runtime responses, and cell closure notifications.
The gRPC host path is implemented in codex-rs/code-mode-host/src/grpc/**. grpc/mod.rs exposes GrpcCodeModeHost, open-session streaming, session close, tool-call subscription/completion, notification ack, exec, wait, terminate, metrics, routing, and heartbeat helpers. grpc/session.rs owns GrpcHostState and GrpcSession: sessions are UUID-keyed leases, each wraps InProcessCodeModeSession, publishes session/opened events through bounded channels, and is removed when its lease stream closes or close_session is called. Host-wide semaphores limit active cells, in-flight requests, control requests, and delegate callbacks.
The actual JavaScript runtime is in codex-rs/code-mode-runtime/src. service.rs is the protocol-facing InProcessCodeModeSession; it maps exec/wait/terminate requests into runtime observations, applies yield grace, converts missing cells into WaitOutcome::MissingCell, and chooses client-side or server-side output truncation. session_runtime/mod.rs owns stored values shared across cells in a session, cell handles, shutdown tokens, and task tracking. cell_actor/mod.rs bridges runtime events to observations: it starts a V8 runtime, pauses until observed, forwards nested tool calls and notifications through delegates, handles yield timers/signals, buffers pending output, and performs termination cleanup. runtime/mod.rs starts one supervised V8 isolate thread per cell, installs globals/tools, processes tool responses, timeouts, pending-frontier commands, dynamic imports, audio/content helpers, and reports results or panics back through the event channel. Output budgeting is in codex-rs/code-mode-runtime/src/output/**.
Covered testing and sample clients are path-scoped. codex-rs/…/lib.rs is a manual/debug CLI that can spawn codex app-server, connect to an existing websocket URL, initialize sessions, send v1/v2 thread and turn requests, answer request_user_input server requests through codex-rs/…/request_user_input.rs, and run plugin analytics smoke tests. codex-rs/…/main.rs bypasses app-server and demonstrates a one-shot direct ThreadManager integration while still mapping core events to app-server protocol notifications; it is useful for comparing app-server behavior against core thread-manager behavior.
Path routing for this doc: app-server lifecycle/request routing belongs under codex-rs/app-server/**; JSON-RPC/API shapes under codex-rs/app-server-protocol/** and codex-rs/app-server-protocol-noop-macros/**; physical transports and remote control under codex-rs/app-server-transport/**; daemon management under codex-rs/app-server-daemon/**; client facades under codex-rs/app-server-client/** and codex-rs/app-server-test-client/**; code-mode host/client/protocol/runtime under codex-rs/code-mode*/**; runtime-agent auth under codex-rs/runtime-agent-instance/**; and the direct ThreadManager comparison sample under codex-rs/thread-manager-sample/**.
Coupling
- If a method, params shape, notification, or server request is added in
codex-rs/app-server-protocol/src/protocol/v2/**, also update the match arms in codex-rs/…/message_processor.rs and any typed client helpers incodex-rs/app-server-client/src/**; raw transport deserialization succeeds before dispatch, so a missing processor arm becomes a runtime method-not-found or compile-time exhaustiveness issue depending on the enum change. - If JSON-RPC framing or
RequestIdsemantics change in codex-rs/…/rpc.rs, verify codex-rs/…/mod.rs, codex-rs/…/remote.rs, codex-rs/…/client.rs, and codex-rs/…/lib.rs; all of them serialize/deserialize the same message envelope outside a generated client. - If websocket compression headers or frame caps change in codex-rs/…/websocket_compression.rs or codex-rs/…/websocket.rs, update codex-rs/…/remote_websocket.rs and websocket-over-UDS negotiation in codex-rs/…/unix_socket.rs; compression history is connection-scoped and a failed partial write marks the client stream unusable.
- If remote-control persistence, pairing, or desired-state behavior changes under
codex-rs/app-server-transport/src/transport/remote_control/**, verify startup-mode handling in codex-rs/…/main.rs, policy/state DB gating in codex-rs/…/lib.rs, and RPC handlers in codex-rs/…/remote_control_processor.rs; these pieces jointly decide whether a process with--listen offis valid. - If daemon settings or lifecycle paths change in codex-rs/…/settings.rs or codex-rs/…/lib.rs, also check managed shutdown/recovery paths in codex-rs/…/lib.rs and path helpers in codex-rs/…/mod.rs; daemon start/stop/update and app-server shutdown agree through files under
app-server-daemon/and the control socket path. - If
CodeModeSession, output truncation, yield semantics, or delegate callbacks change in codex-rs/…/session.rs or runtime.rs, update both providers in codex-rs/…/remote_session.rs andcodex-rs/code-mode/src/grpc_session/**, both hosts in codex-rs/…/lib.rs andcodex-rs/code-mode-host/src/grpc/**, and runtime conversion in codex-rs/…/service.rs; stdio and gRPC code-mode are alternate transports for the same session contract. - If code-mode host IPC framing changes in codex-rs/…/codec.rs, verify the writer/reader in codex-rs/…/lib.rs and the process-owned client connection under
codex-rs/code-mode/src/remote_session/connection/**; they hand off pre-encoded frames through bounded queues and assume one complete length-prefixed JSON frame per message. - If runtime-agent auth modes or assertion headers change in codex-rs/…/auth.rs, verify app-server startup's
RuntimeAuthSlotcreation in codex-rs/…/lib.rs, analytics/auth consumers that callRuntimeAuthManager, and remote-control startup config in codex-rs/…/mod.rs; registration is lazy, but request auth selection is per attempt.
Risks
- codex-rs/…/lib.rs has two coupled loops: the processor loop mutates connection/session state and the outbound loop writes to per-connection queues. If an outgoing path bypasses
OutgoingEnvelope/route_outgoing_envelope, slow websocket clients can block request processing or miss experimental/opt-out filtering. - codex-rs/…/message_processor.rs gates most work on successful
initialize, but connection state is updated afterprocess_requestreturns in codex-rs/…/lib.rs. If initialize handling starts sending ordinary notifications beforeoutbound_initializedis set, they can be filtered or ordered incorrectly relative to initialize-time notifications. - codex-rs/…/stdio.rs uses blocking OS threads and a 45-second process watchdog for EOF/SIGTERM. If shutdown paths grow beyond the 30-second RPC drain plus runtime teardown allowance, stdio app-server processes can exit with code 1 even though cleanup would eventually finish.
- codex-rs/…/mod.rs retries only session admission and explicitly never retries Execute after a lease might have been granted. If new gRPC operations mutate runtime state before returning an error but are added to the retry path, duplicate cells or duplicate tool callbacks can occur.
- codex-rs/…/mod.rs coordinates V8 runtime events, observer replacement, callback tasks, and termination in one select loop. If a new event path fails to cancel callbacks or close
CellState, waits can hang or cells can keep V8 isolates alive after session shutdown. - codex-rs/…/runtime.rs keeps runtime signing keys only in memory and signs assertions with wall-clock
iat. If callers cache assertions fromRuntimeAgentInstance::assertion()instead of requesting a fresh one per attempt, retries or connection handshakes can reuse stale/non-unique assertion IDs.