Introducing a new way to review your PRs.

Read the announcement

openai / codex

Lightweight coding agent that runs in your terminal

View on GitHub

13 documents · Updated Nov 16, 2026

docs / backend-model-and-network-clients

Backend/model and network clients

Overview

This area owns the transport stack used to reach OpenAI-compatible model APIs, ChatGPT/Codex backend endpoints, Codex cloud services, local OSS providers, WebSocket/realtime transports, the managed network proxy, and OTEL export paths. The layering is intentionally split by responsibility:

  • codex-rs/…/lib.rs is the lowest HTTP layer. It wraps reqwest with HttpClient, RequestBuilder, RouteAwareClientPool, HttpClientFactory, destination NetworkPolicy, proxy routing, custom CA/TLS setup, redirect handling, trace-header injection, and OpenAI/ChatGPT header constants.
  • codex-rs/…/provider.rs and codex-rs/…/retry.rs provide generic API request construction and retry policy. Provider combines a base URL, default headers/query params, stream idle timeout, and retry settings; run_with_retry retries only configured 429/5xx/transport errors and honors Retry-After.
  • codex-rs/…/session.rs is the common API session wrapper. Endpoint clients build a codex-client request from Provider, merge endpoint headers/body, apply a SharedAuthProvider, then execute or stream through an injected HttpTransport. codex-rs/…/responses.rs is the HTTP Responses stream client, which sets Accept: text/event-stream, applies session/thread/subagent headers from codex-rs/…/headers.rs, and turns the response body into ResponseStream via codex-rs/…/responses.rs.
  • codex-rs/…/provider.rs is the runtime abstraction above API endpoints. ModelProvider hides provider-specific auth, model catalog ownership, preferred internal models, capability bounds, account state, error mapping, auth recovery, gateway credentials, runtime auth, and workspace routing. codex-rs/…/request_setup.rs resolves a full request context: provider URL/headers, selected credentials, redirect policy, bound HTTP factory, runtime ID, and SharedAuthProvider. It rejects redirects for account-routed and credential-export gateway cases.
  • codex-rs/…/lib.rs defines serialized provider configuration and built-ins. The only wire API is Responses; provider records include base/model-catalog URLs, env/header auth, command auth, gateway OAuth, AWS/GCP config, query/header additions, retry/timeout knobs, WebSocket support, and capabilities. It also applies the process-wide residency header policy. codex-rs/…/gateway_oauth.rs validates gateway token delivery so gateway credentials do not conflict with provider credentials or move to a different catalog origin.
  • codex-rs/…/manager.rs owns catalog refresh and caching. ModelsEndpointClient is the network boundary; stateful managers decide when to use memory, disk cache (models_cache.json), offline mode, or network refresh, then merge provider catalogs with bundled model metadata and filter visible presets. codex-rs/…/models_endpoint.rs implements the OpenAI/Codex model-catalog endpoint with a 5s refresh timeout, provider/gateway/runtime auth selection, route-aware transport, custom catalog URL handling, and telemetry.
  • codex-rs/…/lib.rs is generated backend schema surface only; handwritten backend clients import these generated models rather than defining their own copies.

The ChatGPT/Codex backend client in codex-rs/…/client.rs talks to non-model backend APIs such as profiles, analytics, task usage, plan history, thread/turn cost, account checks, config bundles, and Codex cloud task details. It uses a RouteAwareClientPool with ChatGPT Cloudflare cookie sharing, a ClientAuth resolver, optional user-agent and ChatGPT account headers, and two path styles: /api/codex/... for Codex API origins and /wham/... when the base URL contains /backend-api. codex-rs/…/http.rs adapts this backend client behind the CloudBackend trait from codex-rs/…/api.rs; codex-rs/…/env_detect.rs separately autodetects cloud task environments with backend auth and the same path-style split. codex-rs/…/new_task.rs and adjacent UI files are the terminal flow for creating/listing/applying tasks, while codex-rs/…/mock.rs is the in-memory test/mock implementation.

codex-rs/…/lib.rs is a native gRPC client for the Codex cloud ThreadService. It builds a tonic transport over codex-http-client instead of using tonic's own network stack, preserving proxy, TLS, and network-policy behavior. The client is bound to one trusted origin and one credential set; it validates HTTPS or loopback HTTP origins with no path/query/userinfo, disables redirects and request logging, uses HTTP/2 prior knowledge, sets credential headers as gRPC metadata, and exposes typed modules for activation, transcript, history/items, discovery, prewarm, and turn mutations. codex-rs/…/turns.rs documents that mutations are not retried because an unknown failure may already have admitted a message; callers must persist client_user_message_id and reconcile instead of blindly resubmitting. codex-rs/…/discovery.rs returns bounded paginated thread pages without automatic deduplication.

HTTP and WebSocket route handling share the same proxy/network-policy model. codex-rs/…/outbound_proxy.rs defines HttpClientFactory, OutboundProxyPolicy, route classes (Auth, Api, WebSocket, Other), and redacted OutboundProxyRoutes. With RespectSystemProxy, route resolution tries platform system/PAC/WPAD, environment proxy, then direct; with ReqwestDefault, the underlying transport keeps legacy behavior. codex-rs/…/route_aware_client_pool.rs resolves a route for each request and redirect hop, caches up to 16 route-specific transports, classifies route/TLS/proxy failures, and preserves sensitive headers when configured. codex-rs/…/network_policy.rs lets a config/account owner publish exact destination policy and revokes outstanding request permits when policy or account changes. codex-rs/…/request_builder.rs redacts debug URLs, marks bearer auth sensitive, and delays route selection until send().

codex-rs/…/lib.rs provides a proxy-aware WebSocketConnector using the same HttpClientFactory, network permits, custom CA roots, ChatGPT cookies, and optional account-policy binding. codex-rs/…/dialer.rs handles direct sockets, tungstenite's environment proxy path, explicit HTTP/HTTPS CONNECT proxies, Windows proxy auth fallback, loopback-direct WebSockets, TLS-to-proxy, and Happy Eyeballs-style TCP dialing. codex-rs/…/responses_websocket.rs builds on it for Responses WebSocket streams: it fragments large outbound turns, captures routing affinity, parses response events through the same SSE event machinery, handles server limits/close codes, and propagates session/thread/turn metadata. codex-rs/codex-api/src/endpoint/realtime_websocket/* owns Realtime WebSocket protocol versions and connection methods. codex-rs/…/lib.rs is for incoming app/exec server upgrades, supporting either constant-time SHA-256 capability tokens or HMAC JWT bearer validation with issuer/audience/skew controls; its default policy permits unauthenticated connections, and listeners decide whether that is allowed for their bind address.

Realtime voice uses two covered crates. codex-rs/…/session.rs is the UI-facing actor that starts the packaged voice helper, negotiates a WebRTC offer/answer, and sends ordered microphone/speaker controls through bounded channels; it uses a shared process-lifetime Tokio runtime so child reapers survive session shutdown. codex-rs/…/main.rs is the same-build helper process. It performs a framed stdin/stdout handshake with build-commit verification, owns GStreamer/WebRTC transport and local devices, prioritizes queued privacy controls over audio batches, exits with stage-specific codes, and keeps media device access in the child rather than the UI process.

codex-rs/…/lib.rs is a standalone loopback proxy for POST /v1/responses. It reads either a locked API key from stdin or, in GitHub Actions mode, a GitHub OIDC request credential that is exchanged for OpenAI workload identity credentials before server info is published. It forwards only the exact Responses path, can dump exchanges, has an optional HTTP shutdown endpoint, and disables redirects for federated credentials. codex-rs/…/auth.rs serializes federated renewal, uses a route-aware auth HTTP client with no redirects/request logging, caps token/response sizes, and fail-closes on renewal errors. codex-rs/…/package.json exposes this Rust binary as the @openai/codex-responses-api-proxy npm package with codex-responses-api-proxy as its bin.

codex-rs/…/lib.rs is the managed network sandbox proxy surface. codex-rs/…/proxy.rs reserves HTTP/SOCKS listeners or Windows shared ingress, exports managed proxy environment variables, attaches attribution and credential-broker metadata, and routes child process traffic through policy enforcement. codex-rs/…/credential_broker.rs replaces recognized credentials with dummy values in prepared environments, tracks provider/host bindings and aliases, and can warn, deny, or error on unmasked credential leakage. codex-rs/…/mitm.rs terminates CONNECT tunnels when HTTPS policy needs inner-request visibility, using a process-local or configured CA, per-host leaf certs, hook evaluation, and upstream TLS roots that exclude its own CA. The crate also owns host/domain policy, SOCKS/HTTP proxy handling, AWS SigV4 helpers, remote proxy config, secret substitution, cancellation/disconnect signals, and runtime blocked-request reporting.

OTEL export has its own network paths. codex-rs/…/provider.rs installs global log/trace/metric exporters, validates trace metadata before mutating global state, owns shutdown with a prepared worker thread, and can build OTLP gRPC/HTTP exporters. codex-rs/…/otlp.rs handles OTLP TLS/mTLS config for tonic and reqwest, builds async HTTP clients through HttpClientFactory, and disables redirects when a headers helper supplies credential headers. codex-rs/…/headers_helper.rs periodically runs a local command through codex-rs/…/lib.rs; the helper output must be a bounded JSON object of unique string headers, marked sensitive, and the helper process is time/output limited and killed as a process tree. codex-rs/…/lib.rs is a best-effort bridge: it accepts loopback OTLP trace batches on /v1/traces, broadcasts them to a separate WebSocket listener, rejects WebSocket requests with an Origin header, and drops batches for disconnected or lagging clients.

Local provider integrations live under codex-rs/ollama and codex-rs/lmstudio. codex-rs/…/client.rs derives a host root from the configured OSS provider, probes either /v1/models for OpenAI-compatible base URLs or /api/tags for native Ollama, fetches tags/version, streams /api/pull newline-delimited progress through LineBuffer, and uses route-aware clients with a 5s connect timeout plus legacy custom-CA fallback. codex-rs/…/pull.rs defines pull progress events and CLI/TUI reporters. codex-rs/…/client.rs uses the LM Studio built-in provider base URL, checks /models, preloads via /responses with a one-token request, fetches model IDs, and shells out to lms get --yes when downloading models.

Path-routing notes: backend-client, cloud-tasks-client, and cloud-tasks/env_detect are ChatGPT/Codex backend HTTP clients; codex-client, codex-api, model-provider, model-provider-info, and models-manager are the model-provider/API abstraction stack; http-client, websocket-client, websocket-auth, network-proxy, and http-headers-helper are transport/auth/network policy infrastructure; cloud-client is native gRPC cloud thread transport; responses-api-proxy is a standalone/local Responses proxy and npm subpackage; realtime-webrtc and voice-host are voice transport/helper crates; otel and otel-trace-websocket are telemetry exporters/bridges; ollama and lmstudio are local OSS-provider clients; codex-backend-openapi-models is generated backend model schema.

Coupling

Risks

  • codex-rs/…/turns.rs sends mutations exactly once and treats transport failures as OutcomeUnknown; adding retries in codex-rs/…/lib.rs or in the caller can duplicate user submissions or interrupts because the server may already have admitted the original request.
  • codex-rs/…/request_setup.rs and codex-rs/…/request_preparation.rs bind requests to credential owner/revision while auth can rotate. If request preparation stops rechecking owner changes, a model request can be signed for one account and sent after another account becomes active.
  • codex-rs/…/route_aware_client_pool.rs and codex-rs/…/outbound_proxy.rs protect credentials across redirects and proxy route changes. If new clients bypass HttpClientFactory or use direct reqwest for credential-bearing calls, sensitive headers can be sent to redirect/proxy destinations without the repository's route and header protections.
  • codex-rs/…/mitm.rs generates or loads a CA and terminates TLS for policy inspection. If CA paths, upstream root-store handling, or hook allow/deny behavior are loosened, HTTPS sandbox traffic can either fail unexpectedly or be allowed without inner-request policy enforcement.
  • codex-rs/…/auth.rs serializes workload-identity renewal and disables redirects. If federated credential requests follow redirects or include credential-bearing URLs in diagnostics, the proxy can leak short-lived OpenAI or GitHub OIDC credentials.
  • codex-rs/…/session.rs and codex-rs/…/main.rs use bounded queues for privacy controls. Dropping controls on saturation instead of closing/failing the session would leave microphone mute or speaker suppression transitions unapplied while audio continues.