How to Configure a Network Proxy for Agent Reach in Restricted Environments

Agent Reach routes all HTTP/S traffic through a user-defined proxy by saving the URL to ~/.agent-reach/config.yaml and injecting it into HTTP_PROXY/HTTPS_PROXY environment variables for subprocesses.

When operating behind corporate firewalls or national internet restrictions such as mainland China's Great Firewall, Agent Reach requires explicit proxy configuration to reach external APIs and download dependencies. According to the Panniantong/Agent-Reach source code, the tool provides built-in CLI flags and persistent configuration storage to streamline proxy setup without manual environment management.

Where Agent Reach Stores Proxy Configuration

The Configuration File Structure

Agent Reach persists user settings in ~/.agent-reach/config.yaml. When you supply a proxy URL via command line or configuration commands, the system invokes Config.set("proxy", …) as implemented in agent_reach/cli.py (lines 227-235). The tool also maintains a legacy key bilibili_proxy for backward compatibility with older configurations.

Security Masking in Logs

In agent_reach/config.py (lines 106-110), the configuration renderer automatically masks any key containing "proxy" to prevent credential leakage. When running diagnostic commands, the proxy URL appears obfuscated, ensuring that authentication tokens in http://user:pass@host:port URLs remain hidden from logs and terminal output.

Configuring the Proxy via CLI

During Initial Installation

The install command accepts a --proxy flag defined in agent_reach/cli.py (lines 68-71). This immediately writes the proxy URL to your user configuration file:

agent-reach install \
    --env=auto \
    --proxy="http://user:pass@203.0.113.45:3128" \
    --channels=twitter,xiaoyuzhou

Post-Installation Updates

To modify or add proxy settings after installation, use the dedicated configure sub-command:

agent-reach configure proxy "http://user:pass@203.0.113.45:3128"

This command updates the proxy: key in ~/.agent-reach/config.yaml without requiring a full reinstall.

Runtime Proxy Injection

When Agent Reach launches subprocesses that require network access—such as platform-specific dependency installers—it reads config.get("proxy") and injects the value into the subprocess environment as both HTTP_PROXY and HTTPS_PROXY. This occurs in the installer helper functions (prefixed with _install_system_deps_*), ensuring that tools like curl, pip, or npm automatically route through your specified endpoint when reaching blocked resources like GitHub or OpenAI APIs.

Verifying Your Configuration

Confirm that your proxy is correctly saved and masked by running the diagnostic tool:

agent-reach doctor --json | jq .proxy

The JSON output displays the configured proxy URL, while the standard console output masks sensitive credentials. If the command returns your proxy URL, Agent Reach will use it for all subsequent network operations.

Manual Environment Export (Workaround)

If you need to bypass Agent Reach's internal injection or configure the proxy for external tools, manually export the environment variables:

export HTTP_PROXY=$(grep '^proxy:' ~/.agent-reach/config.yaml | awk '{print $2}')
export HTTPS_PROXY=$HTTP_PROXY

Note that while agent-reach configure get proxy is not yet implemented as a built-in sub-command, directly reading the YAML file provides the same functionality.

Best Practices for Restricted Environments

• Authentication: Use URL-encoded credentials in the format http://user:pass@host:port when the proxy requires basic authentication.
• Connectivity Testing: Verify proxy reachability before configuration with curl -I https://api.github.com --proxy http://your-proxy:port.
• Security: Never commit proxy URLs to version-controlled files; keep them exclusively in the per-user ~/.agent-reach/ directory.
• SELinux/AppArmor: On hardened systems, ensure the proxy binary has permissions to establish outbound connections.

Summary

• Agent Reach stores proxy URLs in ~/.agent-reach/config.yaml via the Config.set() method in agent_reach/cli.py.
• The --proxy flag during installation and the configure proxy command provide ergonomic CLI methods for setting the proxy.
• Runtime subprocesses automatically receive HTTP_PROXY and HTTPS_PROXY environment variables based on the stored configuration.
• Proxy credentials are masked in diagnostic output to prevent leaking sensitive information in logs.

Frequently Asked Questions

Does Agent Reach support SOCKS5 proxies?

The current implementation in agent_reach/cli.py accepts any URL string for the --proxy parameter, including socks5:// schemes. However, the actual connectivity depends on whether the underlying subprocess tools (such as curl or Python's requests) are configured to handle SOCKS5 protocols. For guaranteed compatibility in restricted environments like mainland China, HTTP/HTTPS proxies are recommended.

Why does agent-reach doctor hide my proxy credentials?

According to agent_reach/config.py (lines 106-110), the configuration display logic automatically masks any key containing the substring "proxy". This security feature prevents accidental exposure of authentication tokens in screenshots, log files, or shared terminal sessions while still allowing you to verify that a proxy is configured.

Can I use different proxies for HTTP and HTTPS traffic?

Currently, Agent Reach stores a single proxy key that is exported to both HTTP_PROXY and HTTPS_PROXY environment variables. If you require separate endpoints, you must manually set these environment variables before launching Agent Reach, as the tool does not yet support distinct configuration keys for protocol-specific proxies.

What is the bilibili_proxy legacy key mentioned in the source code?

The codebase maintains a bilibili_proxy configuration key for backward compatibility with earlier versions of Agent Reach. While the modern proxy key is now standard, existing configurations using the legacy key remain functional. New configurations should use the standard proxy key in ~/.agent-reach/config.yaml.

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