How to Set Up Proxy Support in Agent-Reach for Restricted Networks

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

When operating behind corporate firewalls or restricted networks, Agent-Reach requires proxy configuration to access external services like Twitter, Reddit, and YouTube. The Panniantong/Agent-Reach repository implements a centralized proxy system that persists settings in a local YAML file and automatically applies them to all subprocess calls. This guide explains how to configure proxy support using the CLI and how the runtime applies these settings to external tools.

Where Proxy Configuration is Stored

The Config class in agent_reach/config.py manages the ~/.agent-reach/config.yaml file. When displaying configuration values, the system treats any key containing "proxy" as sensitive data and masks the values to prevent credential leakage.

# 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

The actual proxy URL remains stored in plaintext within the YAML file, ensuring the CLI can read it back when spawning subprocesses.

Setting the Proxy During Installation

Configure proxy support immediately using the --proxy flag with the install command. This writes the URL to both the modern proxy key and the legacy bilibili_proxy key for backward compatibility.

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

In agent_reach/cli.py, the install handler processes this flag:

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 the Proxy After Installation

Modify existing proxy settings without reinstallation using the configure proxy sub-command. This updates the configuration file directly and takes effect on the next tool invocation.

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

The configure handler in agent_reach/cli.py synchronizes both keys:

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）")

How the Proxy is Applied at Runtime

When Agent-Reach invokes external binaries (such as twitter-cli, rdt-cli, or Node.js fetch implementations), it reads the stored proxy and injects it into the subprocess environment. This ensures upstream tools respect the network restrictions.

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 appears throughout the codebase, including the various _install_*_deps helpers in agent_reach/cli.py, guaranteeing that any command executed on the host inherits the proxy settings.

Legacy Key Synchronization

Older versions of Agent-Reach stored proxy settings under the bilibili_proxy key. The current implementation maintains both proxy and bilibili_proxy in sync to ensure legacy code (particularly the Bilibili channel) continues functioning while newer implementations use the standardized proxy key. This dual-key strategy prevents breaking existing installations during upgrades.

Practical Configuration Examples

1. Install with proxy in one step

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

2. Update proxy after installation

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

3. Verify configuration file contents

   cat ~/.agent-reach/config.yaml

   Output shows:

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

4. Test with dry-run

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

   Output:

   
   [dry-run] Would save network proxy
   

5. Validate proxy functionality

   agent-reach doctor

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

Summary

• Configuration location: Proxy URLs are stored in ~/.agent-reach/config.yaml under the proxy key, managed by the Config class in agent_reach/config.py.
• CLI commands: Use agent-reach install --proxy for initial setup or agent-reach configure proxy to update existing settings.
• Runtime injection: The CLI reads the config and exports HTTP_PROXY and HTTPS_PROXY before spawning subprocesses, ensuring all external tools respect the proxy.
• Backward compatibility: The system maintains both proxy and bilibili_proxy keys in sync to support legacy channel implementations.

Frequently Asked Questions

What URL format should I use for the proxy configuration?

The CLI accepts standard HTTP proxy URLs that include authentication credentials when necessary. The example implementations in agent_reach/cli.py demonstrate the format http://user:pass@proxy.example.com:3128, which is stored directly in the configuration file and later exported to HTTP_PROXY and HTTPS_PROXY environment variables.

Why does my configuration file contain both proxy and bilibili_proxy entries?

Older versions of Agent-Reach stored proxy settings exclusively under the bilibili_proxy key. The current implementation in agent_reach/cli.py synchronizes both keys during write operations to maintain backward compatibility with legacy channel code while supporting the standardized proxy key used by newer implementations. Both entries contain identical values.

How can I verify the proxy configuration without installing dependencies?

Use the --dry-run flag with the install command to preview configuration changes. When executing agent-reach install --dry-run --proxy http://proxy:8080, the CLI outputs [dry-run] Would save network proxy without actually modifying the configuration file, allowing you to validate the command structure.

How does Agent-Reach ensure external tools use the configured proxy?

At runtime, the CLI reads the stored proxy from ~/.agent-reach/config.yaml and injects it into the subprocess environment before executing external binaries. According to the implementation in agent_reach/cli.py, the system copies the existing environment, sets HTTP_PROXY and HTTPS_PROXY to the configured value, and passes this modified environment to subprocess.run(), ensuring all upstream tools inherit the proxy settings automatically.

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