# How to Configure HTTP/HTTPS Proxy for CodeWhale Installation

> Learn to configure HTTP/HTTPS proxy for CodeWhale installation by exporting shell environment variables. Route network traffic through your corporate proxy seamlessly.

- Repository: [Hunter Bown/CodeWhale](https://github.com/Hmbown/CodeWhale)
- Tags: how-to-guide
- Published: 2026-06-02

---

**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`](https://github.com/Hmbown/CodeWhale/blob/main/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.

```bash
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`](https://github.com/Hmbown/CodeWhale/blob/main/docs/CONFIGURATION.md) (lines 391-393), set `SSL_CERT_FILE` to point to a PEM bundle containing your corporate CA:

```bash
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`](https://github.com/Hmbown/CodeWhale/blob/main/docs/INSTALL.md) Rustup mirror section (lines 54-60) describes these environment variables:

```bash
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`](https://github.com/Hmbown/CodeWhale/blob/main/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)

```bash
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:

```bash
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:

```bash
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:

```bash
env | grep -i proxy

```

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

```bash
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`](https://github.com/Hmbown/CodeWhale/blob/main/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`](https://github.com/Hmbown/CodeWhale/blob/main/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`](https://github.com/Hmbown/CodeWhale/blob/main/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.