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

Agent Reach routes all external API calls through a network proxy by storing the proxy URL in ~/.agent-reach/config.yaml and automatically injecting HTTP_PROXY and HTTPS_PROXY environment variables into subprocess calls.

Agent Reach is a multi-channel agent framework that interacts with external services like Twitter, Reddit, and YouTube. When operating behind corporate firewalls or restrictive networks, you must configure proxy support to ensure agents can reach these external APIs.

Setting the Proxy During Installation

Configure proxy support during initial setup using the --proxy flag with the install command. According to agent_reach/cli.py, the installer captures the proxy URL and writes it to your configuration file:

if args.proxy:
    if dry_run:
        print(f"[dry-run] Would save network proxy")
    else:
        config.set("proxy", args.proxy)
        config.set("bilibili_proxy", args.proxy)  # legacy key

        print(f"✅ 代理已保存（Agent 访问受限网络时使用）")

Install with proxy support in one step:

agent-reach install --proxy http://user:pass@proxy.example.com:3128

This persists the proxy URL to ~/.agent-reach/config.yaml and ensures all subsequent channel operations route through the specified proxy.

You can preview the configuration changes without applying them using the --dry-run flag:

agent-reach install --dry-run --proxy http://proxy:8080

This outputs [dry-run] Would save network proxy without modifying your configuration.

Updating Proxy Settings After Installation

Change or add a proxy configuration after installation using the configure proxy sub-command. As implemented in agent_reach/cli.py, this updates the configuration file without reinstalling dependencies:

if args.key == "proxy":
    config.set("proxy", value)
    config.set("bilibili_proxy", value)  # keep legacy key in sync

    print("✅ 代理已保存（供 Agent 在访问 Reddit/Twitter 等需要代理的网络时设置 HTTP_PROXY/HTTPS_PROXY）")

Update your proxy configuration with:

agent-reach configure proxy http://user:pass@proxy.example.com:3128

Verify the configuration by viewing the config file:

cat ~/.agent-reach/config.yaml

The output shows both keys synchronized:

proxy: http://user:pass@proxy.example.com:3128
bilibili_proxy: http://user:pass@proxy.example.com:3128

Runtime Proxy Injection

Agent Reach does not use the proxy configuration directly for its own HTTP requests. Instead, as implemented in agent_reach/cli.py and channel helpers, it injects standard HTTP_PROXY and HTTPS_PROXY environment variables into subprocess calls when invoking external tools like twitter-cli, rdt-cli, or Node.js fetch implementations:

env = os.environ.copy()
if config.get("proxy"):
    env["HTTP_PROXY"] = config.get("proxy")
    env["HTTPS_PROXY"] = config.get("proxy")
subprocess.run([binary, "..."], env=env, …)

This pattern, used throughout the codebase including agent_reach/doctor.py, ensures that any upstream tool respecting standard proxy environment variables automatically routes traffic through your configured proxy.

Testing Your Proxy Configuration

Verify that your proxy configuration works correctly using the doctor command. This runs health checks across all channels via agent_reach/doctor.py, with each check receiving the proxy environment variables:

agent-reach doctor

If you are using Node.js-based channels that require undici for proxy support, ensure it is installed:

agent-reach install

The installer automatically detects Node.js presence and installs undici if needed.

Configuration Security and Sensitive Data Masking

The Config class in agent_reach/config.py masks proxy-related values when displaying configuration to prevent credential leakage. The system automatically masks any key containing "proxy" along with other sensitive tokens:

# mask proxy-related keys when showing the config

if any(s in k.lower() for s in ("key", "token", "password", "proxy")):
    masked[k] = f"{str(v)[:8]}..." if v else None

This security measure ensures that partial proxy URLs are visible for verification while protecting the full credentials from shoulder surfing or log exposure.

Legacy Key Synchronization

Agent Reach maintains both proxy and bilibili_proxy configuration keys for backward compatibility. Older versions stored proxy settings exclusively under bilibili_proxy (specifically for the Bilibili channel), while newer versions use the generic proxy key. The CLI synchronizes both keys during every write operation to ensure existing installations remain compatible after updates.

You should always use the modern proxy key when manually editing configuration, as the CLI handles synchronization automatically.

Summary

• Initial configuration: Use agent-reach install --proxy <url> to set proxy support during setup
• Runtime mechanism: Agent Reach injects HTTP_PROXY and HTTPS_PROXY into subprocess environments for external tools
• Configuration location: Proxy settings persist in ~/.agent-reach/config.yaml under both proxy and bilibili_proxy keys
• Security: The Config class in agent_reach/config.py masks proxy values to prevent credential exposure
• Updates: Change proxy settings anytime with agent-reach configure proxy <url>
• Verification: Use agent-reach doctor to test connectivity through the configured proxy

Frequently Asked Questions

Does Agent Reach support authenticated proxies?

Yes, Agent Reach supports authenticated proxies using standard URL format. Include credentials directly in the URL when configuring: http://username:password@proxy.example.com:3128. The CLI stores this URL as-is in ~/.agent-reach/config.yaml, and the authentication credentials are passed to upstream tools through the HTTP_PROXY and HTTPS_PROXY environment variables.

Can I use different proxies for HTTP and HTTPS traffic?

Currently, Agent Reach uses a single proxy configuration for both protocols. When you set the proxy via agent-reach configure proxy, the system populates both HTTP_PROXY and HTTPS_PROXY environment variables with the same URL. For protocol-specific proxy separation, you would need to manually export these environment variables before running Agent Reach commands.

Why does my proxy configuration show only the first 8 characters?

This is a security feature implemented in agent_reach/config.py. When displaying configuration values, the system masks any key containing "proxy", "password", "token", or "key" to prevent sensitive credential exposure. The full proxy URL remains functional in the configuration file; only the displayed output is truncated.

How do I verify that the proxy is actually being used?

Run agent-reach doctor to execute health checks across all configured channels. If the proxy is correctly configured, channel tests will route through your proxy server. You can also check your proxy server's access logs for requests from Agent Reach processes, or temporarily set an invalid proxy URL to confirm that external connections fail when the proxy is unreachable.

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