How to Set Up a Proxy for Agent Reach in Restricted Network Environments

Agent Reach routes all external API calls through a network proxy by storing the configuration in ~/.agent-reach/config.yaml and automatically exporting HTTP_PROXY and HTTPS_PROXY environment variables to subprocesses.

When operating behind corporate firewalls or restrictive networks, Agent Reach requires proxy configuration to reach external services like Twitter, Reddit, and YouTube. The tool provides built-in support for HTTP and HTTPS proxies through both installation flags and runtime configuration commands. This guide explains how to set up a proxy for Agent Reach based on the actual source code implementation in the Panniantong/Agent-Reach repository.

Where Agent Reach Stores Proxy Configuration

Proxy settings are persisted in the user's home directory at ~/.agent-reach/config.yaml. The Config class in agent_reach/config.py treats any key containing "proxy" as sensitive data, masking the value when displaying configuration to prevent credential leakage.

In agent_reach/config.py, the configuration manager identifies sensitive keys using this pattern:

# 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 ensures that proxy URLs containing authentication credentials are truncated in logs and UI output.

Configuring the Proxy During Installation

The fastest way to set up a proxy is during the initial installation using the --proxy flag. The CLI handler in agent_reach/cli.py captures the URL and writes it to both the modern proxy key and the legacy bilibili_proxy key for backward compatibility.

Use this command to install with proxy support:

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

The installer executes this logic from agent_reach/cli.py:

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 访问受限网络时使用）")

Updating Proxy Settings After Installation

If the network environment changes, use the configure proxy sub-command to update settings without reinstalling. The CLI writes the new value to the configuration file, which takes effect on the next tool invocation.

Update the proxy using:

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

The configure handler in agent_reach/cli.py processes this command:

if args.key == "proxy":
    # Nothing reads this key at runtime — agents read it back

    # and export HTTP(S)_PROXY before invoking upstream tools.

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

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

How the Proxy is Applied at Runtime

When Agent Reach spawns subprocesses to execute external tools like twitter-cli, rdt-cli, or Node.js fetch operations, it reads the stored proxy from config and injects it into the environment. This pattern is implemented throughout the codebase to ensure all external binaries inherit the proxy settings.

The runtime injection logic follows this pattern:

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 applies to all channel operations, ensuring that tools receive the proxy configuration regardless of how they are invoked.

Understanding the Dual Proxy Keys

The configuration maintains both proxy and bilibili_proxy keys because older versions of Agent Reach stored proxy settings under the Bilibili-specific key. The installer synchronizes both values to ensure compatibility with legacy code while supporting newer implementations.

When you set either key, the system automatically updates both to prevent configuration drift. You can verify this synchronization by inspecting the config file:

cat ~/.agent-reach/config.yaml

The output shows both keys populated with identical values:

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

Configuration Examples

Install with proxy in one step

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

This writes the proxy URL to ~/.agent-reach/config.yaml and enables immediate use for all channel operations.

Add or change the proxy after installation

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

Verify the configuration

cat ~/.agent-reach/config.yaml

Dry-run to preview changes

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

Output:

[dry-run] Would save network proxy

Run diagnostics with proxy

agent-reach doctor

This runs all channel checks, with each tool receiving the HTTP_PROXY and HTTPS_PROXY environment variables automatically.

Summary

• Configuration location: Proxy settings are stored in ~/.agent-reach/config.yaml managed by the Config class in agent_reach/config.py.
• Installation setup: Use agent-reach install --proxy <url> to configure during initial setup.
• Runtime updates: Use agent-reach configure proxy <url> to modify settings without reinstallation.
• Environment injection: The proxy is applied at runtime by setting HTTP_PROXY and HTTPS_PROXY in subprocess environments before invoking external tools.
• Legacy compatibility: The system maintains both proxy and bilibili_proxy keys in sync to support older Agent Reach versions.

Frequently Asked Questions

Does Agent Reach support authenticated proxies?

Yes. Include the username and password directly in the URL when configuring the proxy, such as http://user:pass@proxy.example.com:3128. The Config class in agent_reach/config.py automatically masks these credentials in display output to prevent accidental exposure.

Why does my configuration show two proxy entries?

Agent Reach writes the proxy URL to both the proxy key and the legacy bilibili_proxy key. This ensures backward compatibility with older versions of the software that relied on the Bilibili-specific key, while newer code references the generic proxy key.

Do I need to restart Agent Reach after changing the proxy?

No. The agent-reach configure proxy command updates the configuration file immediately, and changes take effect on the next external tool invocation. The runtime reads the configuration fresh each time it spawns a subprocess, so no restart is required.

What happens if the proxy is unreachable?

If the configured proxy is unavailable, external tools invoked by Agent Reach will fail to connect to their respective services (Twitter, Reddit, etc.). The error messages will come from the underlying tools rather than Agent Reach itself. Use agent-reach doctor to verify network connectivity and proxy configuration.

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