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

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

When operating behind corporate firewalls or restrictive networks, Agent Reach agents require explicit proxy configuration to access external platforms like Twitter, Reddit, and YouTube. The open-source tool Panniantong/Agent-Reach provides built-in support for configuring a network proxy for Agent Reach in restricted environments through its CLI and configuration management system. This guide covers the exact implementation details found in the source code, including where settings are stored and how they are injected into subprocess calls.

Where Agent Reach Stores Proxy Settings

The proxy configuration persists in the user's home directory at ~/.agent-reach/config.yaml. In agent_reach/config.py, the Config class treats any key containing "proxy" as sensitive data and masks the value when displaying configuration output.

# agent_reach/config.py

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 proxy credentials are not leaked in debug logs or terminal output, while the full URL remains stored in the YAML file for runtime use.

Setting the Proxy During Installation

You can configure the proxy immediately during the initial setup using the --proxy flag with the install command. 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.

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

The underlying Python implementation in agent_reach/cli.py handles this as follows:

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 Configuration Later

To change or add a proxy after installation, use the configure proxy sub-command. This updates the stored values without requiring a full reinstallation.

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

According to the source code in agent_reach/cli.py, this command synchronizes both configuration 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

Agent Reach does not use the proxy for its own internal Python HTTP requests. Instead, it injects the stored proxy URL into the environment variables of subprocess calls made to external binaries like twitter-cli, rdt-cli, or Node.js fetch implementations.

The runtime logic follows this pattern found throughout 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 ensures that any tool invoked by the channels—whether written in Python, Node.js, or another language—automatically respects the proxy settings via the standard HTTP_PROXY and HTTPS_PROXY variables.

Legacy Key Synchronization

Older versions of Agent Reach stored proxy settings exclusively under bilibili_proxy. The current implementation maintains both keys simultaneously to ensure compatibility with legacy channel code while modernizing the configuration schema. When you update the proxy using either method described above, both keys are written automatically, preventing breakage in existing installations.

Verification and Testing

To verify your configuration without executing actual network calls, use the dry-run flag during installation:

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

This outputs:

[dry-run] Would save network proxy

To test that the proxy is correctly passed to external tools, run the diagnostic command:

agent-reach doctor

This executes health checks across all configured channels, and each subprocess receives the HTTP_PROXY/HTTPS_PROXY variables from your config file. If a channel requires Node.js fetch (which uses undici), the installer automatically ensures undici is present to handle proxy connections properly.

Summary

• Storage Location: Proxy URLs are stored in ~/.agent-reach/config.yaml under the proxy and bilibili_proxy keys.
• Security: The Config class in agent_reach/config.py masks proxy values to prevent credential leakage.
• Installation: Use agent-reach install --proxy <url> to set the proxy during initial setup.
• Updates: Use agent-reach configure proxy <url> to modify settings later without reinstallation.
• Runtime Behavior: The proxy is exported as HTTP_PROXY and HTTPS_PROXY environment variables for all subprocess calls via the logic in agent_reach/cli.py.
• Compatibility: Both modern and legacy config keys are synchronized to support older channel implementations.

Frequently Asked Questions

What file stores the network proxy configuration for Agent Reach?

The configuration is stored in ~/.agent-reach/config.yaml in your home directory. This file is managed by the Config class in agent_reach/config.py, which treats proxy-related keys as sensitive and masks them when displaying configuration output.

Why does Agent Reach maintain both proxy and bilibili_proxy configuration keys?

The bilibili_proxy key is a legacy identifier from earlier versions of the software. Current implementations in agent_reach/cli.py write to both proxy (the modern key) and bilibili_proxy simultaneously to ensure backward compatibility with older channel code that may still reference the legacy key.

How do I verify that my proxy settings are active without making live API calls?

Run agent-reach install --dry-run --proxy <url> to preview configuration changes without writing them, or execute agent-reach doctor to perform health checks. The doctor command invokes channel binaries with the HTTP_PROXY and HTTPS_PROXY environment variables set from your config, allowing you to verify the setup is correct.

Does Agent Reach support authenticated proxies with username and password?

Yes. The configuration accepts standard proxy URLs containing credentials in the format http://user:pass@host:port. These URLs are stored as-is in ~/.agent-reach/config.yaml and exported to the environment variables, which upstream tools like curl, Node.js fetch, and Python requests all support.

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