Inbound Codex Passthrough
Relevant source files
The following files were used as context for generating this wiki page:
Inbound Codex Passthrough is an opt-in feature of shunt that allows the Codex CLI (or similar OpenAI-protocol clients) to communicate directly with the gateway. Unlike the primary request path which translates Anthropic Messages to other protocols, this module provides a byte-for-byte relay for OpenAI Responses. It enables the Codex CLI to point its base_url at shunt and benefit from the gateway's managed account pooling and load balancing across multiple ChatGPT/Codex subscriptions.
Sources: README.md:104-109, ARCHITECTURE.md:213-219
Architectural Overview
The Inbound Codex Passthrough is implemented as a set of dedicated routes within the Axum server. When enabled via the [server.codex_endpoint] configuration, the gateway registers endpoints that mirror the ChatGPT/Codex backend structure. This subsystem includes a privacy-preserving analytics sink that records sanitized event counters while discarding sensitive payloads.
Sources: README.md:107-112, ARCHITECTURE.md:88-91
Data Flow and Request Handling
The following sequence diagram illustrates how an inbound request from a Codex CLI client is handled by the gateway when the Codex Passthrough is active.
The diagram shows the direct relay mechanism where shunt acts as a load-balancing transparent proxy.
Sources: README.md:104-112, ARCHITECTURE.md:21-26
Configuration and Activation
The Codex Passthrough is disabled by default. To activate it, the [server.codex_endpoint] table must be present in the configuration file (shunt.toml or shunt.yaml).
Configuration Table
| Field | Type | Description | Default |
|---|---|---|---|
[server.codex_endpoint] | Table | Presence of this table activates the inbound Codex routes. | None (Off) |
provider | String | The name of the provider (defined in [[upstreams]]) to use for the relay. | Required |
Sources: README.md:107-112, src/config.rs:185-195
Route Registration
When active, the following routes are registered in the server's router:
- Inference Relay:
/responses,/v1/responses, and/backend-api/codex/responses. - Analytics Sink: Privacy-preserving endpoints for client telemetry.
Sources: README.md:107-109, src/server.rs:142-158
Components and Logic
Analytics Sink
The analytics paths act as discard sinks. While they do not forward data to the upstream provider, they increment internal counters for sanitized event names. This ensures that the Codex CLI can function normally (sending its expected telemetry) without leaking user data to external tracking services via the gateway.
Sources: README.md:109-111, ARCHITECTURE.md:118-120
Error Handling
Unlike the primary Anthropic-focused request path, the Inbound Codex Passthrough uses the OpenAI Responses error shape for gateway-owned errors. This ensures that Codex-protocol clients can correctly parse error messages through their native error-handling logic.
Sources: AGENTS.md:58-61, ARCHITECTURE.md:213-219
Integration with Account Pooling
The passthrough utilizes the same multi-account pooling logic as the translation path. It leverages x-codex-* response headers to track usage windows and proactively rotates accounts to avoid 429 rate-limit errors.
Sources: README.md:101-103, ARCHITECTURE.md:221-228
Conclusion
The Inbound Codex Passthrough extends shunt beyond being a simple Anthropic-to-OpenAI translator. By providing a direct, load-balanced relay for the Codex CLI, it allows developers to consolidate their LLM infrastructure and subscription management into a single gateway while preserving the native experience of OpenAI-protocol tools.