Network Proxy

Relevant source files

• codex-rs/cli/tests/sandbox_network_proxy.rs
• codex-rs/core/src/config/network_proxy_spec.rs
• codex-rs/network-proxy/Cargo.toml
• codex-rs/network-proxy/README.md
• codex-rs/network-proxy/src/certs.rs
• codex-rs/network-proxy/src/config.rs
• codex-rs/network-proxy/src/connect_policy.rs
• codex-rs/network-proxy/src/http_proxy.rs
• codex-rs/network-proxy/src/lib.rs
• codex-rs/network-proxy/src/mitm.rs
• codex-rs/network-proxy/src/native_certs.rs
• codex-rs/network-proxy/src/network_policy.rs
• codex-rs/network-proxy/src/proxy.rs
• codex-rs/network-proxy/src/reasons.rs
• codex-rs/network-proxy/src/responses.rs
• codex-rs/network-proxy/src/runtime.rs
• codex-rs/network-proxy/src/socks5.rs
• codex-rs/network-proxy/src/state.rs
• codex-rs/network-proxy/src/upstream.rs
• codex-rs/network-proxy/src/upstream_tests.rs

The codex-network-proxy crate is a local network policy enforcement engine designed to sandbox agent processes. It acts as a gatekeeper for all outbound network traffic initiated by tools or shell commands within the Codex environment. By providing both HTTP and SOCKS5 proxy interfaces, it ensures that sandboxed processes comply with the security constraints defined in the active Permissions Profile

Overview and Purpose

The proxy serves three primary functions:

1. Policy Enforcement: Implements an allow/deny model for hostnames and IP addresses codex-rs/network-proxy/README.md52-55
2. Traffic Isolation: Clamps network listeners to loopback by default to prevent unauthorized external access to the proxy itself codex-rs/network-proxy/README.md32-34
3. Auditing: Emits structured OpenTelemetry (OTEL) events for every policy decision and tracks violations in a BlockedRequest buffer codex-rs/network-proxy/src/runtime.rs175-176

Key Capabilities

• Proxy Modes: Supports Full (read/write) and Limited (read-only) network modes codex-rs/network-proxy/src/config.rs130
• MITM Termination: Optional Man-in-the-Middle (MITM) capability to inspect HTTPS CONNECT tunnels and enforce method-level policies (e.g., blocking POST in limited mode) codex-rs/network-proxy/README.md36-39
• MITM Hooks: Allows fine-grained manipulation of HTTPS traffic, such as stripping or injecting headers based on host and path matches codex-rs/network-proxy/src/mitm_hook.rs1-10
• Unix Socket Proxying: (macOS-only) Supports proxying to local unix sockets via the x-unix-socket header codex-rs/network-proxy/README.md75-77
• Credential Broker: Integrates with a credential management system to inject API keys into intercepted HTTPS requests securely codex-rs/network-proxy/src/state.rs65-68

---

Architecture and Data Flow

The proxy is typically managed by codex-core, which initializes the proxy using NetworkProxyBuilder and configuration derived from the session's permissions profile via NetworkProxySpec codex-rs/core/src/config/network_proxy_spec.rs100-132

System Architecture Diagram

This diagram shows how a sandboxed process interacts with the proxy and how the proxy validates requests against the ConfigState.

Title: Network Proxy Data Flow

Sources: codex-rs/network-proxy/src/proxy.rs189-224 codex-rs/network-proxy/src/http_proxy.rs92-110 codex-rs/network-proxy/src/runtime.rs230-240 codex-rs/network-proxy/src/socks5.rs64-87

---

Configuration and Policy

The proxy configuration is nested within the permissions table of config.toml. Policies are compiled into GlobSet structures for high-performance matching during initialization in build_config_state codex-rs/network-proxy/src/state.rs60-93

Policy Configuration Example

Sources: codex-rs/network-proxy/README.md18-77 codex-rs/network-proxy/src/config.rs115-144

Policy Logic

The policy evaluation determines the fate of a request based on the following hierarchy:

1. Denylist: If the host matches a pattern in the deny_set, it is immediately blocked with HostBlockReason::Denied codex-rs/network-proxy/src/runtime.rs67
2. Allowlist: If the host matches the allow_set, it is allowed codex-rs/network-proxy/src/runtime.rs90
3. Local Protection: If allow_local_binding is false, any request resolving to a non-public IP is blocked even if allowlisted by hostname codex-rs/network-proxy/README.md41-46
4. Method Guard: In Limited mode, non-safe methods (POST, PUT, DELETE) are blocked unless a MITM hook explicitly allows them codex-rs/network-proxy/src/socks5.rs122-127

---

Implementation Details

Core Entities and Classes

Entity	File Path	Role
NetworkProxy	codex-rs/network-proxy/src/proxy.rs224	Main handle for the proxy server; manages listener lifecycles.
ConfigState	codex-rs/network-proxy/src/runtime.rs168	Contains the compiled GlobSet for allow/deny rules, MITM state, and hook configs.
NetworkPolicyDecider	codex-rs/network-proxy/src/network_policy.rs50	Trait for custom logic to override allowlist misses (used for approval flows).
NetworkProxyBuilder	codex-rs/network-proxy/src/proxy.rs117	Builder for initializing NetworkProxy with specific listeners and policies.
BlockedRequest	codex-rs/network-proxy/src/runtime.rs95	Struct representing a policy violation, used for auditing and UI notifications.
NetworkProxyState	codex-rs/network-proxy/src/runtime.rs230	Thread-safe shared state holding the ConfigState and ConfigReloader.

Integration with Core System

codex-core manages the proxy via NetworkProxySpec, which handles the mapping of PermissionProfile to NetworkProxyConfig codex-rs/core/src/config/network_proxy_spec.rs100-132

Title: Code Entity Relationship: Core to Proxy

Sources: codex-rs/network-proxy/src/proxy.rs224-235 codex-rs/network-proxy/src/runtime.rs168-177 codex-rs/network-proxy/src/runtime.rs230-240 codex-rs/network-proxy/src/state.rs60-93

---

Proxy Modes and MITM

Limited Mode

In NetworkMode::Limited, the proxy enforces a read-only policy. Only GET, HEAD, and OPTIONS methods are permitted codex-rs/network-proxy/README.md104-111 SOCKS5 UDP and non-HTTPS SOCKS5 TCP are blocked in limited mode codex-rs/network-proxy/src/socks5.rs122-127 For HTTPS traffic, this requires mitm = true because the proxy cannot see the HTTP method inside an encrypted CONNECT tunnel without terminating the TLS connection codex-rs/network-proxy/src/http_proxy.rs152-172

MITM Implementation

The MITM system uses rustls via the rama framework to terminate TLS codex-rs/network-proxy/src/mitm.rs153-185

• Termination: The proxy terminates upgraded CONNECT streams when MITM is enabled or hooks are configured codex-rs/network-proxy/src/http_proxy.rs152-164
• Hook Evaluation: Before forwarding a request, the proxy evaluates mitm_hooks to determine if headers should be injected or the request modified codex-rs/network-proxy/src/runtime.rs9 codex-rs/network-proxy/src/mitm.rs88-93
• Certificates: The proxy generates a process-local CA (ManagedMitmCa) to issue per-host leaf certificates for TLS termination codex-rs/network-proxy/src/certs.rs51-64

---

Runtime Management

Startup Sequence

1. Resolution: NetworkProxyBuilder::build() begins by resolving the current configuration from the provided state codex-rs/network-proxy/src/proxy.rs189-198
2. Binding: The builder reserves loopback ports. On Windows, it uses WindowsProxyIngress codex-rs/network-proxy/src/proxy.rs207-219; on other platforms, it uses ephemeral listeners codex-rs/network-proxy/src/proxy.rs223-224
3. Execution: run_http_proxy and run_socks5 begin serving traffic on the reserved listeners codex-rs/network-proxy/src/http_proxy.rs92-110 codex-rs/network-proxy/src/socks5.rs64-87

Dynamic Reloading

The proxy supports dynamic policy updates without restarting the listeners via NetworkProxy::replace_config_state codex-rs/network-proxy/src/proxy.rs268 This is used by NetworkProxySpec to update proxy state when permission profiles change codex-rs/core/src/config/network_proxy_spec.rs191-203

Sources: codex-rs/network-proxy/src/proxy.rs189-224 codex-rs/network-proxy/src/proxy.rs268-275 codex-rs/core/src/config/network_proxy_spec.rs100-132