How to Configure HTTP/HTTPS Proxy for CodeWhale Installation

Export the standard environment variables HTTP_PROXY and HTTPS_PROXY in your shell before running any install command to route CodeWhale's network traffic through your corporate or external proxy.

CodeWhale is a Rust-based CLI and TUI application distributed through the Hmbown/CodeWhale repository. If you are operating behind a corporate firewall or strict network policies, you must configure HTTP/HTTPS proxy settings before installation to ensure the installer can download release assets, the Rust toolchain, and model dependencies.

Understanding CodeWhale's Proxy Architecture

The CodeWhale architecture relies on environment variable inheritance across process spawns. When you execute the installation command, the installer spawns a child process that inherits the current shell environment. The main CLI binary (codewhale) loads your user configuration, then spawns the TUI wrapper (codewhale-tui). Both binaries use the same process environment and rely on the underlying Rust HTTP client reqwest, which automatically respects standard proxy environment variables for all outbound HTTP(S) requests.

According to docs/INSTALL.md (lines 660-666), the installer reads these variables when running curl, npm, or cargo commands. This means any proxy settings you export in your shell automatically propagate to release-asset fetches, model-API calls, and web-search operations without requiring additional runtime flags.

Step-by-Step Proxy Configuration

Set Standard Proxy Environment Variables

Define HTTP_PROXY and HTTPS_PROXY to point to your proxy server endpoint. These variables must be exported before invoking any installation method.

export HTTP_PROXY="http://proxy.example.com:3128"
export HTTPS_PROXY="http://proxy.example.com:3128"

Handle Corporate TLS Inspection

Some corporate proxies perform TLS inspection (MITM), which requires the client to trust the proxy's custom Certificate Authority. As documented in docs/CONFIGURATION.md (lines 391-393), set SSL_CERT_FILE to point to a PEM bundle containing your corporate CA:

export SSL_CERT_FILE="/etc/ssl/certs/corporate-proxy-ca.pem"

Configure Rust Toolchain Mirrors

When your proxy blocks access to official Rust or GitHub release assets, redirect rustup and Cargo to internal mirrors before installation. The docs/INSTALL.md Rustup mirror section (lines 54-60) describes these environment variables:

export RUSTUP_DIST_SERVER="https://rsproxy.cn"
export RUSTUP_UPDATE_ROOT="https://rsproxy.cn/rustup"

Additionally, you can override the default GitHub endpoint for CodeWhale's update checks by setting CODEWHALE_RELEASE_BASE_URL to point to an internal mirror, as noted in the "Mirror the release assets" section of docs/INSTALL.md (lines 660-672).

Installation Commands Through a Proxy

Once your environment variables are exported, run your preferred installation method. The proxy settings will persist through the entire installation chain.

Install via npm (Recommended)

export HTTP_PROXY="http://proxy.example.com:3128"
export HTTPS_PROXY="http://proxy.example.com:3128"

npm install -g codewhale
codewhale  # First run downloads matching binaries through the proxy

Install via Cargo

For environments where npm is unavailable or blocked, install directly from crates.io:

export HTTPS_PROXY="http://proxy.example.com:3128"

cargo install codewhale-cli --locked
cargo install codewhale-tui --locked
codewhale --version

Manual Binary Download

If downloading binaries directly with curl, ensure the proxy variables are set in the same shell session:

export HTTP_PROXY="http://proxy.example.com:3128"
export SSL_CERT_FILE="/etc/ssl/certs/corporate-proxy-ca.pem"

curl -L -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-linux-x64
chmod +x codewhale-linux-x64
mv codewhale-linux-x64 ~/.local/bin/codewhale

Verifying Proxy Configuration

To confirm the proxy variables are active in your environment before installation, run:

env | grep -i proxy

For detailed debugging of HTTP requests during installation, enable debug logging for the underlying Rust HTTP client:

export RUST_LOG=debug
codewhale --version

Look for "Connecting through proxy" messages from reqwest in the output logs to verify traffic is routing correctly.

Summary

• Export HTTP_PROXY and HTTPS_PROXY in your shell before any install command to route all CodeWhale traffic through your proxy.
• Set SSL_CERT_FILE if your corporate proxy performs TLS inspection and requires a custom CA certificate.
• Use RUSTUP_DIST_SERVER and RUSTUP_UPDATE_ROOT to bypass blocked Rust toolchain downloads by pointing to internal mirrors.
• All components inherit the same environment: the CLI, TUI, and underlying reqwest client automatically use exported variables without additional configuration files.
• Verify with RUST_LOG=debug to confirm the proxy is actively handling connections during binary downloads and update checks.

Frequently Asked Questions

Does CodeWhale automatically detect system proxy settings?

No. CodeWhale does not read system proxy settings from macOS network preferences or Windows Internet Options. According to the Hmbown/CodeWhale source code, the application relies explicitly on the HTTP_PROXY and HTTPS_PROXY environment variables, which are read by the underlying Rust reqwest HTTP client and inherited by all spawned child processes during installation.

Can I configure proxy settings in the CodeWhale config file instead of environment variables?

While config.example.toml shows where proxy-related environment variables can be overridden, the primary and recommended method is to export HTTP_PROXY and HTTPS_PROXY in your shell before installation. The CLI (codewhale) and TUI (codewhale-tui) inherit these variables automatically, ensuring consistent behavior across release-asset downloads, model API calls, and toolchain updates without requiring per-configuration edits.

How do I troubleshoot when CodeWhale cannot connect through my proxy?

Enable debug logging by setting RUST_LOG=debug before running the installation command. This outputs detailed connection logs from the reqwest client, including "Connecting through proxy" messages. Additionally, verify your variables are correctly exported using env | grep -i proxy and ensure SSL_CERT_FILE is set if your corporate proxy performs TLS inspection, as documented in docs/CONFIGURATION.md (lines 391-393).

What should I do if my proxy blocks GitHub and Rustup servers?

Configure mirror-aware environment variables before installation. Set RUSTUP_DIST_SERVER and RUSTUP_UPDATE_ROOT to internal Rust toolchain mirrors, and set CODEWHALE_RELEASE_BASE_URL to an internal asset host, as described in docs/INSTALL.md (lines 660-672 and 54-60). These variables redirect all network requests away from the blocked official endpoints to your approved internal mirrors while still respecting your HTTP_PROXY settings for the outbound connection to those mirrors.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}