Configure network proxy for Agent Reach in restricted environments

Agent Reach routes all external API calls through a network proxy by persisting the proxy URL in ~/.agent-reach/config.yaml and automatically injecting HTTP_PROXY and HTTPS_PROXY into subprocess environments whenever tools access Twitter, Reddit, or YouTube.

Agent Reach, maintained in the Panniantong/Agent-Reach repository, orchestrates external platform interactions through various CLI tools. When running in restricted network environments, configuring proxy support ensures that underlying fetch operations can traverse firewalls without manual environment variable management.

Where Agent Reach stores proxy credentials

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

# 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

Setting the proxy during installation

During initial setup, the agent-reach install command accepts a --proxy flag that captures the proxy URL and writes it to both the modern proxy key and the legacy bilibili_proxy key for backward compatibility.

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

You can perform a dry‑run to verify what would be saved:

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

Updating proxy settings after installation

To configure or change the proxy without reinstalling, use the configure proxy sub‑command. The CLI writes the values to the config file, and agents read these settings back at runtime to populate environment variables.

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

Example command:

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

Runtime proxy injection

When Agent Reach spawns subprocesses to interact with external platforms (e.g., calling twitter-cli or rdt-cli), it reads the stored proxy from ~/.agent-reach/config.yaml and exports standard HTTP_PROXY and HTTPS_PROXY variables into the subprocess environment, as implemented in agent_reach/cli.py.

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 ensures that any command executed on the host inherits the proxy settings automatically.

Legacy key synchronization

Agent Reach maintains backward compatibility by writing the proxy URL to both the proxy key (current) and bilibili_proxy key (legacy). Older versions of the codebase stored the proxy exclusively under bilibili_proxy. Keeping them synchronized ensures that legacy channel implementations continue to function while newer code migrates to the standardized key.

Practical configuration examples

1. Install with a proxy in one step

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

2. Add or change the proxy after installation

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

3. Verify the saved configuration

   cat ~/.agent-reach/config.yaml
   # → proxy: http://user:pass@proxy.example.com:3128
   
   #   bilibili_proxy: http://user:pass@proxy.example.com:3128
   

4. Validate connectivity through the proxy

   agent-reach doctor

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

Summary

• Agent Reach stores proxy credentials in ~/.agent-reach/config.yaml, masking them as sensitive values.
• Use agent-reach install --proxy <url> during setup or agent-reach configure proxy <url> for updates.
• The system writes the proxy to both proxy and bilibili_proxy keys for backward compatibility.
• At runtime, Agent Reach injects HTTP_PROXY and HTTPS_PROXY into subprocess environments before invoking external tools like twitter-cli or rdt-cli.

Frequently Asked Questions

Where does Agent Reach store the proxy configuration?

Agent Reach persists the proxy URL in ~/.agent-reach/config.yaml under the keys proxy and bilibili_proxy. The Config class in agent_reach/config.py treats these as sensitive values and masks them when displaying configuration to prevent credential leakage.

How do I update the proxy URL after installation?

Run the agent-reach configure proxy <url> command to update the stored proxy without reinstalling. The CLI writes the new value to the configuration file, and subsequent agent operations will automatically export the updated HTTP_PROXY and HTTPS_PROXY variables to subprocesses.

Does Agent Reach support authenticated proxies?

Yes, the proxy configuration accepts standard URL formats including credentials, such as http://user:pass@proxy.example.com:3128. These values are stored securely in the config file and injected into the environment variables that upstream CLI tools respect.

Why are there two proxy keys in the config file?

The bilibili_proxy key exists for backward compatibility with older versions of Agent Reach that stored the proxy exclusively under that name. Modern code uses the proxy key, but the CLI synchronizes both keys during any write operation to ensure legacy channel implementations continue to function correctly.

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