hermes-ice/homelab/raw/articles/forge/reference/docs-proxy-configuration.md

type, agent, source, scraped, content_hash

type	agent	source	scraped	content_hash
agent-doc	ForgeCode	https://forgecode.dev/docs/proxy-configuration/	2026-04-28T21:02:25.451175+00:00	8f9989cc

$HTTP_PROXY

If you're behind a corporate firewall, a VPN exit node, or any network that requires outbound traffic to go through a proxy, ForgeCode respects the standard HTTP_PROXY and HTTPS_PROXY environment variables. Set them once, and every API call ForgeCode makes — to OpenAI, Anthropic, OpenRouter, or any custom provider — will flow through your proxy.

Setting the Proxy​

ForgeCode reads two standard environment variables:

Environment Variable	Protocol	Example Value
HTTP_PROXY	HTTP	http://proxy.company.com:8080
HTTPS_PROXY	HTTPS	http://proxy.company.com:8080
NO_PROXY	—	localhost,127.0.0.1,.internal.io

Both HTTP_PROXY and HTTPS_PROXY accept an HTTP proxy URL — even for HTTPS traffic. The connection to the target server is tunneled through the proxy using the CONNECT method, so the proxy itself doesn't see the encrypted payload.

There are three ways to set them, depending on how permanent you want the configuration to be.

~/.env — persistent, ForgeCode-only

The .env file in your home directory is loaded by ForgeCode on every run. This is the right choice when you want the proxy active for ForgeCode without affecting other tools on your system:

# ~/.envHTTP_PROXY=http://proxy.company.com:8080HTTPS_PROXY=http://proxy.company.com:8080NO_PROXY=localhost,127.0.0.1,.internal.company.com

~/.zshrc (or ~/.bashrc) — persistent, system-wide

Adding the variables to your shell profile makes them available to every process in your terminal, not just ForgeCode. Use this when all outbound tools on your machine need to go through the proxy:

# ~/.zshrcexport HTTP_PROXY=http://proxy.company.com:8080export HTTPS_PROXY=http://proxy.company.com:8080export NO_PROXY=localhost,127.0.0.1,.internal.company.com

Reload your shell after editing (source ~/.zshrc) or open a new terminal.

Current session — temporary

To route traffic through a proxy only for the duration of your current terminal session:

export HTTP_PROXY=http://proxy.company.com:8080export HTTPS_PROXY=http://proxy.company.com:8080

The variables are gone when the session ends.

Authenticated Proxies​

If your proxy requires a username and password, embed the credentials in the URL:

HTTP_PROXY=http://username:password@proxy.company.com:8080HTTPS_PROXY=http://username:password@proxy.company.com:8080

Proxy credentials embedded in URLs can appear in shell history, process listings, and log files. Prefer storing them in your ~/.env file with restricted permissions (chmod 600 ~/.env) rather than exporting them directly in your terminal.

How Traffic Flows​

ForgeCode makes HTTPS requests to AI provider APIs. When HTTPS_PROXY is set, the flow looks like this:

ForgeCode    |    | CONNECT api.openai.com:443    vProxy Server (proxy.company.com:8080)    |    | Tunnels encrypted TLS connection    vAI Provider API (api.openai.com)

The proxy only sees that a tunnel is being opened — the TLS handshake and all request/response content remain encrypted end-to-end between ForgeCode and the AI provider.

Bypassing the Proxy for Specific Hosts​

NO_PROXY accepts a comma-separated list of hostnames, IP addresses, and domain suffixes that should bypass the proxy:

# Bypass proxy for localhost, a specific IP, and anything under .internal.company.comNO_PROXY=localhost,127.0.0.1,192.168.1.0/24,.internal.company.com

Leading dots (.internal.company.com) match any subdomain of that domain.

Proxy with Custom Certificates​

Corporate proxies commonly perform TLS inspection — they intercept HTTPS connections, decrypt them, inspect the traffic, and re-encrypt using their own certificate authority. If ForgeCode fails to connect with certificate errors, your proxy is likely doing this.

The fix is to add your corporate CA certificate to ForgeCode's trusted roots:

# ~/.envHTTPS_PROXY=http://proxy.company.com:8080# Trust the corporate CA that signs the proxy's certificatesFORGE_HTTP__ROOT_CERT_PATHS=/etc/ssl/certs/corporate-ca.pem

ForgeCode accepts certificates in PEM, CRT, or CER format. For multiple certificates, provide a comma-separated list of paths.

If you cannot obtain the CA certificate and need to connect urgently in a controlled environment:

FORGE_HTTP__ACCEPT_INVALID_CERTS=true

FORGE_HTTP_ACCEPT_INVALID_CERTS=true disables all certificate validation. This removes protection against man-in-the-middle attacks. Only use it in isolated development environments where you control the network — never in production or on untrusted networks.