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

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

When operating behind corporate firewalls or restrictive network policies, the open-source Panniantong/Agent-Reach framework requires explicit proxy configuration to reach external services like Twitter, Reddit, and YouTube. The tool persists proxy credentials locally and automatically applies them to all spawned channel processes at runtime.

Where Proxy Settings Are Stored

Configuration values reside in the user’s home directory at ~/.agent-reach/config.yaml. The Config class in agent_reach/config.py manages persistence and treats any key containing “proxy” as sensitive data, masking it in logs and console output.

# From 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 ensures that proxy credentials containing authentication tokens are never fully displayed when viewing configuration dumps.

Setting the Proxy During Installation

You can define the network 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.

# From agent_reach/cli.py – install handler

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

Execute the following to configure the proxy in one step:

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

Updating Proxy Configuration After Installation

If the network environment changes or you need to rotate credentials after installation, use the configure proxy sub-command. This updates the stored values without requiring a full reinstallation.

# From agent_reach/cli.py – configure handler

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

Run this command to update your settings:

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

How the Proxy Is Applied at Runtime

Agent-Reach does not use the proxy for its own internal logic; instead, it exports the stored value as standard HTTP_PROXY and HTTPS_PROXY environment variables before invoking external binaries. This pattern appears throughout the codebase, particularly in channel implementations that spawn subprocesses for tools like twitter-cli, rdt-cli, or Node.js fetch operations.

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, ...)

Because the proxy is injected into the environment of every spawned process, upstream tools that respect standard environment variables automatically route traffic through your specified proxy.

Legacy Key Compatibility

Older versions of Agent-Reach stored proxy settings exclusively under the key bilibili_proxy. The current installer synchronizes both proxy and bilibili_proxy to ensure legacy channel code continues to function while newer implementations read from the canonical proxy key. Maintaining both keys prevents breaking changes for existing installations that may still reference the legacy name.

Practical Configuration Examples

Install with Proxy in One Step

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

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

Update Proxy After Installation

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

Verify the configuration file contents:

cat ~/.agent-reach/config.yaml

Expected output:

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

Verify with Dry-Run Mode

Test the installation logic without writing changes:

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

Output:

[dry-run] Would save network proxy

Runtime Verification

Run the diagnostic command to ensure all channels inherit the proxy environment:

agent-reach doctor

The doctor command invokes each channel’s health check, and because the subprocess environment includes HTTP_PROXY/HTTPS_PROXY, any network-dependent validations will route through your configured proxy.

Summary

• Configuration Location: Proxy URLs are stored in ~/.agent-reach/config.yaml under the proxy key (and legacy bilibili_proxy).
• CLI Commands: Use agent-reach install --proxy <url> during setup or agent-reach configure proxy <url> to update later.
• Runtime Behavior: The stored URL is injected into HTTP_PROXY and HTTPS_PROXY for every subprocess spawned by channel tools.
• Security: The Config class in agent_reach/config.py automatically masks proxy values to prevent credential leakage in logs.
• Backward Compatibility: Both proxy and bilibili_proxy keys are maintained in sync to support legacy channel implementations.

Frequently Asked Questions

What URL format should I use for the proxy?

Agent-Reach passes the proxy URL directly to the underlying tools, so any format supported by your external binaries works. Typically, use http://user:pass@host:port for authenticated HTTP proxies or http://host:port for unauthenticated ones. The URL is written verbatim to the config file and exported as HTTP_PROXY/HTTPS_PROXY.

Does Agent-Reach support SOCKS5 proxies?

Support depends entirely on the external tools (Node.js fetch, Python requests, etc.) invoked by each channel. Agent-Reach itself only stores and exports the proxy URL; it does not modify or validate the protocol. If your downstream tools support SOCKS5 via HTTP_PROXY (or require ALL_PROXY), specify that URL format when running agent-reach configure proxy.

Why does my config file contain both proxy and bilibili_proxy keys?

The bilibili_proxy key exists for backward compatibility with older Agent-Reach versions that stored network settings under that specific name. The current CLI in agent_reach/cli.py writes to both keys simultaneously to ensure legacy channel code continues to function while newer code uses the canonical proxy key.

How can I verify the proxy is actually being used?

Run agent-reach doctor after configuring the proxy. This command executes health checks for all channels, and because the runtime injects HTTP_PROXY/HTTPS_PROXY into each subprocess, network-dependent validations will fail if the proxy is unreachable. You can also inspect the environment of running Agent-Reach processes to confirm the variables are present.

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