Skip to content

Conversation

ibakaidov
Copy link

Motivation: Predictable Network Access for Codex in Proxy Environments

Many enterprise and academic environments route outbound traffic through HTTP proxies (e.g., Zscaler, PAC/explicit proxies, on-prem egress). Previously, Codex lacked native proxy support, which caused:

  • Unpredictable network request failures (to external APIs and the ChatGPT backend) and flakiness in CI/CD.
  • Divergence between local runs (no proxy) and pipeline runs (behind proxy).
  • Fragile, undocumented workarounds (manual HTTP_PROXY export or wrapper scripts) that increased complexity.

The goal of this PR is to make proxy usage an explicit and supported configuration so that Codex behaves consistently across local, CI, and sandboxed environments.


Summary of Changes

  • Configuration / TOML: Added an optional http_proxy field to Config and ConfigToml.
  • Profile: Exposed the http_proxy field in ConfigProfile.
  • Startup Environment Setup: If http_proxy is set, Codex now forwards its value to the HTTP_PROXY environment variable before the HTTP client initializes.
  • Test Coverage: Added http_proxy_from_config_sets_environment to verify that configuration and process environment are correctly updated.
  • Documentation: Introduced a new ## http_proxy section in docs/config.md with usage examples and sandbox behavior notes.

Key files:

  • codex-rs/core/src/config.rs — added the field, environment propagation, and test.
  • codex-rs/core/src/config_profile.rs — profile wiring.
  • docs/config.md — documentation and TOML examples.

Design Rationale

Single Source of Truth

By defining http_proxy declaratively in config.toml or the active profile, and then forwarding it to HTTP_PROXY, we unify behavior across:

  • Local dev machines: no manual export HTTP_PROXY.
  • CI/CD pipelines: reliable networking configuration through project config.
  • Future services: standardized approach for other HTTP clients.

Compatibility with the Rust ecosystem

Most HTTP stacks (reqwest/hyper) already respect the HTTP_PROXY environment variable. Leveraging this standard minimizes custom code and risk.

Priority Resolution

http_proxy follows the existing configuration merge order: Profile → Base Config → Defaults. This keeps behavior predictable and easy to debug.


Security & Operational Notes

  • Environment variable setup occurs before worker threads spawn — safe and race-free.
  • Proxy value is not logged and is excluded from error messages to avoid secret leakage.
  • When running in the seatbelt sandbox, proxies are intentionally disabled along with external network access (documented behavior).

Backward Compatibility

  • http_proxy is fully optional — if unset, Codex behaves exactly as before.
  • No breaking changes to public interfaces; CLI and environment contracts remain intact.

Alternatives Considered

  1. Rely solely on system environment variables: Too implicit and hard to reproduce across CI/CD and local setups.
  2. Per-request proxy control: More granular but adds complexity; unnecessary for first-class, global support.
  3. PAC/auto-detection: Too complex for an initial step and platform-dependent.

Testing

  • Unit: Verified env propagation with http_proxy_from_config_sets_environment.
  • Integration: Confirmed outbound requests route through the configured proxy (observed in proxy logs and blocked direct egress when proxy absent).
  • Regression: With http_proxy = None, behavior matches the previous default.

Developer Experience

Documentation now includes:

# ~/.config/codex/config.toml
http_proxy = "http://localhost:8080"

Copy link

github-actions bot commented Sep 25, 2025

All contributors have signed the CLA ✍️ ✅
Posted by the CLA Assistant Lite bot.

github-actions bot added a commit that referenced this pull request Sep 25, 2025
@ibakaidov
Copy link
Author

All contributors have signed the CLA ✍️ ✅Posted by the CLA Assistant Lite bot.

I have read the CLA Document and I hereby sign the CLA

@ibakaidov
Copy link
Author

@longouyang will some react for commit

@tiny1990
Copy link

LGTM

@ibakaidov
Copy link
Author

No any reaction from maintainers

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants