How to Configure Proxy for Restricted Networks in Agent-Reach

TLDR: Agent-Reach routes external API calls through a proxy by storing the URL in ~/.agent-reach/config.yaml and injecting HTTP_PROXY/HTTPS_PROXY into subprocess environments when channels invoke external tools.

Agent-Reach is an open-source agent framework (Panniantong/Agent-Reach) that interacts with external services like Twitter, Reddit, and YouTube. When operating behind corporate firewalls or restrictive networks, you must configure proxy settings to allow these agents to reach external APIs. The framework supports this via CLI flags and configuration commands that persist settings to your local config file.

Where Proxy Configuration is Stored

All proxy settings are persisted in the user's configuration directory at ~/.agent-reach/config.yaml. The Config class in agent_reach/config.py handles read and write operations, treating any key containing "proxy" as sensitive data that requires masking when displayed.

Sensitive Value Masking

According to the source code in agent_reach/config.py, the configuration manager automatically masks proxy values to prevent credential leakage in logs or UI displays:

# 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 when you view your configuration, the proxy URL appears truncated (e.g., http://us...) rather than exposing the full credentials.

Setting the Proxy During Installation

You can configure the proxy during the initial setup using the --proxy flag with the install command. This captures the proxy URL and writes it to both the modern proxy key and the legacy bilibili_proxy key for backwards compatibility.

Using the Install Command

In agent_reach/cli.py, the install handler processes the --proxy argument and persists it to the config file:

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

Run this command to set your proxy during installation:

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

Dry-Run Mode

To verify what would be saved without actually modifying your configuration, use the --dry-run flag:

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

The CLI outputs [dry-run] Would save network proxy without writing to config.yaml.

Updating Proxy Settings After Installation

If you need to change or add a proxy after the initial installation, use the configure command. This updates the existing configuration without reinstalling dependencies.

In agent_reach/cli.py, the configure handler accepts a proxy key and updates both configuration entries:

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 with:

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

Verify the change by viewing your config file:

cat ~/.agent-reach/config.yaml

You should see both keys populated:

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

How Proxy Settings Are Applied at Runtime

Agent-Reach does not use the proxy configuration directly for its own HTTP requests. Instead, it acts as a passthrough layer for external tools like twitter-cli, rdt-cli, or Node.js fetch implementations.

Environment Variable Injection

When a channel invokes an external binary, the CLI reads the stored proxy and injects it into the subprocess 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 pattern ensures that any command executed on the host inherits the proxy settings, enabling seamless operation behind restrictive firewalls.

Legacy Key Synchronization

Older versions of Agent-Reach stored the proxy under bilibili_proxy specifically for Bilibili channel operations. The current implementation maintains both keys to ensure backwards compatibility:

• proxy: The modern key used by current channel implementations
• bilibili_proxy: Legacy key maintained for older code paths

The configure and install commands always update both keys simultaneously to prevent configuration drift.

Verifying Proxy Configuration

To confirm your proxy is active, run the diagnostic command:

agent-reach doctor

This executes health checks across all channels, and each external tool invoked during these checks receives the HTTP_PROXY and HTTPS_PROXY environment variables from your configuration.

If you encounter issues with Node.js-based channels, ensure undici is installed for proper proxy support:

agent-reach install

The installer automatically detects Node.js and installs undici if present, ensuring fetch operations respect the proxy configuration.

Summary

• Agent-Reach stores proxy URLs in ~/.agent-reach/config.yaml under the proxy key (and legacy bilibili_proxy key).
• Set during installation with agent-reach install --proxy <url> or update later with agent-reach configure proxy <url>.
• The Config class in agent_reach/config.py masks proxy values as sensitive data.
• At runtime, the CLI injects HTTP_PROXY and HTTPS_PROXY into subprocess environments before invoking external tools like twitter-cli or rdt-cli.
• Use --dry-run to test configuration changes without modifying files.
• Run agent-reach doctor to verify proxy settings across all channels.

Frequently Asked Questions

How does Agent-Reach handle authentication in proxy URLs?

Agent-Reach stores the complete proxy URL including credentials in ~/.agent-reach/config.yaml. The framework treats any key containing "proxy" as sensitive and masks the value in display outputs, showing only the first 8 characters. When executing subprocesses, the full URL (including username and password) is passed to the HTTP_PROXY and HTTPS_PROXY environment variables.

Can I use different proxies for different channels?

Currently, Agent-Reach supports a single global proxy configuration. The proxy and bilibili_proxy keys in config.yaml are synchronized to maintain backwards compatibility, but the framework does not support channel-specific proxy settings. All external tools invoked by any channel receive the same HTTP_PROXY and HTTPS_PROXY values.

Why are there two proxy keys in my config file?

The bilibili_proxy key exists for backwards compatibility with older versions of Agent-Reach that stored proxy settings specifically for Bilibili channel operations. Modern versions use the proxy key for all channels. The CLI automatically keeps both keys synchronized when you run agent-reach install --proxy or agent-reach configure proxy, ensuring legacy code continues to function while newer implementations use the standardized key.

What happens if no proxy is configured?

If the proxy configuration is absent or empty, Agent-Reach does not modify the subprocess environment. External tools inherit the system environment variables without proxy overrides, which may result in connection failures when operating behind restrictive firewalls.

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