Exec Server

Relevant source files

• codex-rs/core/src/tools/sandboxing_tests.rs
• codex-rs/exec-server/Cargo.toml
• codex-rs/exec-server/README.md
• codex-rs/exec-server/src/client.rs
• codex-rs/exec-server/src/client/tests/network_policy_tests.rs
• codex-rs/exec-server/src/client_api.rs
• codex-rs/exec-server/src/client_recovery.rs
• codex-rs/exec-server/src/client_transport.rs
• codex-rs/exec-server/src/connection.rs
• codex-rs/exec-server/src/environment.rs
• codex-rs/exec-server/src/environment_provider.rs
• codex-rs/exec-server/src/environment_toml.rs
• codex-rs/exec-server/src/fs_helper.rs
• codex-rs/exec-server/src/fs_sandbox.rs
• codex-rs/exec-server/src/lib.rs
• codex-rs/exec-server/src/local_file_system.rs
• codex-rs/exec-server/src/local_process.rs
• codex-rs/exec-server/src/network_policy_decisions.rs
• codex-rs/exec-server/src/network_policy_decisions_tests.rs
• codex-rs/exec-server/src/process_sandbox.rs
• codex-rs/exec-server/src/process_sandbox_tests.rs
• codex-rs/exec-server/src/relay.rs
• codex-rs/exec-server/src/remote.rs
• codex-rs/exec-server/src/remote_file_system.rs
• codex-rs/exec-server/src/rpc.rs
• codex-rs/exec-server/src/rpc_server_requests.rs
• codex-rs/exec-server/src/sandboxed_file_system.rs
• codex-rs/exec-server/src/server.rs
• codex-rs/exec-server/src/server/file_system_handler.rs
• codex-rs/exec-server/src/server/handler.rs
• codex-rs/exec-server/src/server/handler/tests.rs
• codex-rs/exec-server/src/server/processor.rs
• codex-rs/exec-server/src/server/registry.rs
• codex-rs/exec-server/src/server/transport.rs
• codex-rs/exec-server/src/server/transport_tests.rs
• codex-rs/exec-server/tests/common/exec_server.rs
• codex-rs/exec-server/tests/deferred_environment.rs
• codex-rs/exec-server/tests/exec_process.rs
• codex-rs/exec-server/tests/file_system/shared.rs
• codex-rs/exec-server/tests/file_system_unix.rs
• codex-rs/exec-server/tests/initialize.rs
• codex-rs/exec-server/tests/relay.rs
• codex-rs/exec-server/tests/websocket.rs
• codex-rs/file-system/src/lib.rs
• codex-rs/network-proxy/src/remote_config.rs
• codex-rs/network-proxy/src/remote_config_tests.rs
• codex-rs/sandboxing/src/windows.rs

The codex-exec-server crate provides a standalone JSON-RPC server designed to manage subprocess execution and filesystem operations. It acts as a bridge between a Codex session and a potentially remote or sandboxed execution environment. By leveraging codex-utils-pty, it supports both interactive PTY-based sessions and non-interactive piped execution across different operating systems codex-rs/exec-server/Cargo.toml21-29

Overview and Architecture

The Exec Server decouples the Codex agent's logic from the environment where code is executed. This is essential for supporting remote execution environments (e.g., cloud-based sandboxes) or local execution with strict security boundaries.

Key Components

• ExecServerClient: The primary interface for clients to interact with a remote execution server via WebSockets codex-rs/exec-server/src/lib.rs47
• EnvironmentManager: A shared registry that manages the lifecycle of execution environments, creating local or remote Environment instances based on CODEX_EXEC_SERVER_URL or an environments.toml configuration codex-rs/exec-server/src/environment.rs78-84
• ExecBackend: A trait that abstracts the process of spawning and managing subprocesses, implemented by LocalProcess and RemoteProcess codex-rs/exec-server/src/lib.rs106-112
• ExecutorFileSystem: A trait providing filesystem operations (read, write, metadata), implemented locally or via RPC for remote servers codex-rs/exec-server/src/lib.rs61

Natural Language to Code Entity Mapping: Execution Flow

The following diagram maps the conceptual "Run Command" request to the specific code entities involved in the dispatch and execution.

Execution Dispatch Path

Sources: codex-rs/exec-server/src/environment.rs78-84 codex-rs/exec-server/src/client.rs181-189 codex-rs/exec-server/src/connection.rs228-231 codex-rs/exec-server/src/local_process.rs175-197

Wire Protocol and Handshake

Communication with the server occurs over WebSockets or Stdio using a JSON-RPC 2.0 compatible protocol managed by JsonRpcConnection codex-rs/exec-server/src/connection.rs228-231

1. Initialize Handshake

Before any commands are executed, the client must send an initialize request. This establishes client identity and allows for session resumption codex-rs/exec-server/src/client.rs102-105

• Request: InitializeParams containing client_name and optional resume_session_id codex-rs/exec-server/src/lib.rs166
• Response: InitializeResponse containing environment details codex-rs/exec-server/src/lib.rs167
• Acknowledgement: The client sends an initialized notification after receiving the response codex-rs/exec-server/src/client.rs103

2. Process Management RPCs

The server implements several methods for controlling subprocesses codex-rs/exec-server/src/client.rs50-57:

Method	Protocol Constant	Description
process/start	EXEC_METHOD	Spawns a new process (PTY or Pipe) codex-rs/exec-server/src/client.rs52
process/read	EXEC_READ_METHOD	Long-polls for output from a specific process codex-rs/exec-server/src/client.rs54
process/write	EXEC_WRITE_METHOD	Writes data to the stdin of a running process codex-rs/exec-server/src/client.rs57
process/signal	EXEC_SIGNAL_METHOD	Sends a signal (e.g., SIGINT) to the process codex-rs/exec-server/src/client.rs55
process/terminate	EXEC_TERMINATE_METHOD	Kills a running process codex-rs/exec-server/src/client.rs56

3. Notifications (Server to Client)

The server streams process events back to the client codex-rs/exec-server/src/client.rs50-53:

• process/output: ExecOutputDeltaNotification containing raw bytes codex-rs/exec-server/src/client.rs53
• process/exited: ExecExitedNotification sent when the process terminates codex-rs/exec-server/src/client.rs51
• process/closed: ExecClosedNotification sent when output streams are drained codex-rs/exec-server/src/client.rs50

Sources: codex-rs/exec-server/src/client.rs37-115 codex-rs/exec-server/src/lib.rs113-181

Filesystem RPCs

The server provides filesystem operations via the ExecutorFileSystem trait, implemented locally or remotely codex-rs/exec-server/src/lib.rs61

RPC Method	Parameters	Description
fs/readFile	FsReadFileParams	Reads file contents codex-rs/exec-server/src/client.rs93
fs/writeFile	FsWriteFileParams	Writes data to a file codex-rs/exec-server/src/client.rs99
fs/createDirectory	FsCreateDirectoryParams	Creates directories codex-rs/exec-server/src/client.rs83
fs/getMetadata	FsGetMetadataParams	Retrieves file metadata codex-rs/exec-server/src/client.rs85
fs/readDirectory	FsReadDirectoryParams	Lists directory contents codex-rs/exec-server/src/client.rs91
fs/remove	FsRemoveParams	Deletes files or directories codex-rs/exec-server/src/client.rs95
fs/walk	FsWalkParams	Recursively walks a directory codex-rs/exec-server/src/client.rs97
fs/canonicalize	FsCanonicalizeParams	Resolves absolute paths codex-rs/exec-server/src/client.rs77

Sources: codex-rs/exec-server/src/client.rs65-100 codex-rs/exec-server/src/lib.rs136-160

Implementation Details

Environment Management

The EnvironmentManager tracks environments by ID (e.g., local, remote) codex-rs/exec-server/src/environment.rs104-105

• Local: Directly spawns processes using LocalProcess codex-rs/exec-server/src/environment.rs35
• Remote: Connects via ExecServerClient to a remote endpoint codex-rs/exec-server/src/environment.rs39-40

Sandboxing Integration

The FileSystemSandboxRunner prepares and executes filesystem operations within restricted environments codex-rs/exec-server/src/fs_sandbox.rs51-54

• Policy Enforcement: It transforms PermissionProfile into FileSystemSandboxPolicy and NetworkSandboxPolicy codex-rs/exec-server/src/fs_sandbox.rs82-98
• Direct Spawn: Uses SandboxManager to select and apply platform-specific sandboxes (Landlock, Seatbelt, etc.) before running the fs-helper codex-rs/exec-server/src/fs_sandbox.rs116-152

ExecServerClient Reliability

The client includes sophisticated recovery and ordering logic codex-rs/exec-server/src/client_recovery.rs66-73

• OrderedSessionEvents: Buffers incoming process events to ensure they are published in sequence number order, handling cases where exit notifications arrive before final output codex-rs/exec-server/src/client.rs197-200
• Session Recovery: Upon reconnection, the client uses process/read with the last known sequence number to fetch missing output and state codex-rs/exec-server/src/client_recovery.rs74-83

Entity Mapping: Client Recovery Flow

Sources: codex-rs/exec-server/src/client.rs181-196 codex-rs/exec-server/src/client_recovery.rs66-83 codex-rs/exec-server/src/rpc.rs42-53

Remote Relay and Noise

For remote environments, the server supports a Noise-encrypted relay codex-rs/exec-server/src/remote.rs42-45

• Registration: EnvironmentRegistryClient registers the executor's public key with a central registry codex-rs/exec-server/src/remote.rs110-114
• Rendezvous: The harness and environment connect to a rendezvous WebSocket to establish a multiplexed, encrypted stream codex-rs/exec-server/src/remote.rs182-186

Sources: codex-rs/exec-server/src/environment.rs54-130 codex-rs/exec-server/src/fs_sandbox.rs56-152 codex-rs/exec-server/src/remote.rs51-196