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

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 and HTTPS_PROXY environment variables before invoking any subprocess.

When operating behind corporate firewalls or restrictive networks, Agent Reach requires proxy configuration to access external services like Twitter, Reddit, and YouTube. The open-source tool Panniantong/Agent-Reach provides built-in proxy support that persists credentials in a local YAML file and automatically injects them into subprocess environments. This guide explains how to set up a network proxy for restricted environments in Agent Reach using the CLI configuration commands and the underlying Python implementation.

Where Proxy Settings Are Stored

Agent Reach centralizes configuration management in agent_reach/config.py. The Config class persists all settings to ~/.agent-reach/config.yaml, including proxy credentials. When displaying configuration values, the system masks any key containing "proxy" as sensitive data to prevent credential leakage in logs or terminal output.

In agent_reach/config.py, the masking logic appears as:

# 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 while the full proxy URL is stored in the YAML file, only the first eight characters are visible when running configuration diagnostics.

Setting the Proxy During Installation

The fastest way to configure proxy support is during the initial installation using the --proxy flag. The CLI handler in agent_reach/cli.py captures the proxy URL and writes it to two configuration keys: proxy (the current standard) and bilibili_proxy (for backward compatibility).

When running agent-reach install, the installation handler executes:

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

To install with proxy support in one command:

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

This writes the proxy URL to both keys in ~/.agent-reach/config.yaml, ensuring immediate compatibility with all channel implementations.

Updating Proxy Configuration After Installation

You can modify the proxy settings at any time without reinstalling the tool using the configure sub-command. The configure proxy handler in agent_reach/cli.py updates the configuration file directly:

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

Update your proxy configuration with:

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

Runtime Proxy Application

At runtime, Agent Reach reads the stored proxy value and injects it into the environment of any subprocess that requires external network access. This pattern is implemented throughout the codebase, particularly in channel handlers and dependency installation helpers.

Before invoking external binaries like twitter-cli or rdt-cli, the code prepares the environment:

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 all upstream tools respect the proxy settings without requiring individual configuration.

Legacy Bilibili Proxy Support

Older versions of Agent Reach stored proxy settings exclusively under the key bilibili_proxy. The current implementation maintains both keys simultaneously to ensure backward compatibility. When you set or update the proxy using modern CLI commands, both proxy and bilibili_proxy are synchronized to the same value, preventing breaking changes for legacy channel implementations.

Configuration Examples

Install with Proxy Authentication

Configure proxy support during installation, including credentials:

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

Result: The proxy URL is written to ~/.agent-reach/config.yaml under both proxy and bilibili_proxy keys.

Update Proxy After Installation

Change proxy settings without reinstalling:

agent-reach configure proxy http://new-proxy.company.com:8080

Verify Current Configuration

Inspect the stored configuration while respecting sensitive data masking:

cat ~/.agent-reach/config.yaml

Expected output:

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

Dry-Run Installation

Preview what would be saved without writing to disk:

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

Output:

[dry-run] Would save network proxy

Validate Proxy with Health Checks

Run the diagnostic tool to verify all channels can access external networks through the proxy:

agent-reach doctor

Each channel test receives the HTTP_PROXY and HTTPS_PROXY environment variables automatically.

Summary

• Storage Location: Proxy credentials are stored in ~/.agent-reach/config.yaml managed by agent_reach/config.py, with automatic masking of sensitive values.
• Dual Keys: The system writes to both proxy (current standard) and bilibili_proxy (legacy) for compatibility.
• CLI Commands: Use agent-reach install --proxy <url> during setup or agent-reach configure proxy <url> for updates.
• Runtime Injection: Before executing external tools, Agent Reach copies the environment, adds HTTP_PROXY and HTTPS_PROXY from the config, and passes this to subprocesses.
• Dry-Run Support: The --dry-run flag allows testing configuration changes without persisting them.

Frequently Asked Questions

Where does Agent Reach store proxy credentials?

Agent Reach stores proxy credentials in the YAML configuration file at ~/.agent-reach/config.yaml. The Config class in agent_reach/config.py handles persistence and automatically masks proxy values when displaying configuration to prevent credential exposure.

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

The bilibili_proxy key exists for backward compatibility with older versions of Agent Reach that stored proxy settings under that specific name. Modern implementations use the proxy key, but the CLI synchronizes both values to ensure legacy channel implementations continue functioning while newer code uses the standard key.

Can I update the proxy configuration without reinstalling Agent Reach?

Yes, use the agent-reach configure proxy <url> command to update proxy settings at any time. This command writes to agent_reach/cli.py updates both configuration keys immediately without requiring reinstallation or affecting other settings.

How does Agent Reach handle authenticated proxies?

Agent Reach stores the complete proxy URL including authentication credentials (e.g., http://user:pass@proxy.example.com:3128) in the configuration file. At runtime, the full URL is exported to HTTP_PROXY and HTTPS_PROXY environment variables, allowing underlying tools to handle the authentication protocol according to standard proxy conventions.

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