network_proxy docs do not explain dynamic listener ports or clients that ignore HTTPS_PROXY

What is the type of issue?

Documentation is missing

What is the issue?

The documentation describes features.network_proxy.proxy_url and features.network_proxy.socks_url as the HTTP and SOCKS5 listener addresses, with defaults of 127.0.0.1:3128 and 127.0.0.1:8081.

However, with Codex CLI 0.146.1 in a WSL2 Linux environment, codex sandbox in workspace-write mode does not listen on the documented default ports. Instead, it allocates ephemeral loopback ports and rewrites HTTPS_PROXY and ALL_PROXY to use the dynamically selected endpoints.

For example:

for i in 1 2 3; do
  codex sandbox \
    -c 'sandbox_mode="workspace-write"' \
    -c 'sandbox_workspace_write.network_access=true' \
    -c 'features.network_proxy=true' \
    -- sh -c \
      'printf "HTTPS_PROXY=%s\nALL_PROXY=%s\n" "$HTTPS_PROXY" "$ALL_PROXY"'
done

Based on the documented default listener addresses, the expected values would be:

HTTPS_PROXY=http://127.0.0.1:3128
ALL_PROXY=socks5h://127.0.0.1:8081

Instead, Codex injects different ephemeral loopback ports on each invocation.

This appears intentional in the current non-Windows implementation. For a Codex-managed proxy, the HTTP listener—and the SOCKS5 listener when SOCKS5 is enabled—is pre-bound to 127.0.0.1:0, so the actual proxy ports are selected by the operating system. The configured runtime SOCKS address is only retained as a fallback value when no SOCKS listener is enabled; it is not used to bind an active SOCKS listener in that case.

https://github.com/openai/codex/blob/rust-v0.146.1/codex-rs/network-proxy/src/proxy.rs#L203-L249
https://github.com/openai/codex/blob/rust-v0.146.1/codex-rs/network-proxy/src/proxy.rs#L290-L344

This undocumented behavior is especially important for clients that do not consume the standard proxy environment variables.

For example, Maven commonly requires proxy configuration through settings.xml or Java system properties rather than automatically using HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY.

Because the listener port changes on every invocation, users cannot prepare a static Maven proxy configuration in advance. They must read the runtime HTTPS_PROXY value and translate it into Maven-specific configuration, but the Codex documentation does not explain that this is necessary.

Please clarify:

1. Whether the use of ephemeral listener ports for Codex-managed proxies on Linux and macOS is intentional, and document this behavior if so.
2. On which platforms and in which execution modes, if any, features.network_proxy.proxy_url and features.network_proxy.socks_url are honored as fixed listener addresses.
3. How the dynamically selected proxy endpoints are communicated to sandboxed processes, including the role of the injected HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY environment variables.
4. Whether there is a supported way to request fixed listener ports, or a recommended integration pattern for tools that do not honor the standard proxy environment variables.

Where did you find it?

Official Codex configuration reference:

https://developers.openai.com/codex/config-reference/

The entries for:

• features.network_proxy.proxy_url
• features.network_proxy.socks_url

describe these values as the HTTP and SOCKS5 listener URLs, with defaults of http://127.0.0.1:3128 and http://127.0.0.1:8081, respectively. They do not mention that Codex-managed proxies may instead use ephemeral ports on Linux or macOS.

Repository documentation:

https://github.com/openai/codex/blob/rust-v0.146.1/codex-rs/network-proxy/README.md

The README likewise describes 127.0.0.1:3128 and 127.0.0.1:8081 as the default HTTP and SOCKS5 proxy endpoints. Its configuration example and client setup instructions also use those fixed ports, without explaining that an embedded Codex-managed proxy on non-Windows platforms may select ephemeral ports instead.