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

Agent-Reach stores proxy settings in ~/.agent-reach/config.yaml and automatically exports them as HTTP_PROXY and HTTPS_PROXY environment variables for all outbound channel traffic.

When operating behind corporate firewalls or regional restrictions, Agent-Reach requires explicit proxy configuration to access external platforms like Twitter, Reddit, and YouTube according to the Panniantong/Agent-Reach source code. The tool persists these settings in a per-user YAML configuration file managed by the Config class and transparently applies them to downstream binaries. Understanding how to configure a proxy for restricted network environments ensures seamless data collection even in server or VPS deployments with strict egress rules.

Configuration Storage and the Config Class

Agent-Reach centralizes all user-defined settings in ~/.agent-reach/config.yaml, parsed and persisted by the Config class defined in [agent_reach/config.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). When you supply a proxy URL, the system writes it to two keys in this file:

• proxy — The primary key used by current channel implementations
• bilibili_proxy — A legacy key maintained for backward compatibility

The Config.get() method (lines 69-77) implements a fallback hierarchy: it first checks the in-memory dictionary, then attempts to read an uppercase environment variable of the same name. This design allows temporary overrides via HTTP_PROXY or HTTPS_PROXY if you need to bypass the saved configuration for a single session.

CLI Methods for Proxy Configuration

The [agent_reach/cli.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) module provides two distinct entry points for proxy management depending on whether you are performing a fresh install or updating an existing configuration.

Setting Proxy During Installation

During the initial setup, pass the --proxy flag to the install command (lines 68-70). The CLI validates the URL format and immediately persists it via config.set("proxy", args.proxy) and config.set("bilibili_proxy", args.proxy) (lines 228-236).

agent-reach install --proxy http://user:pass@203.0.113.10:3128

This single command creates the configuration directory, writes the YAML file, and ensures all future channel invocations route through the specified proxy.

Updating Proxy After Installation

If you need to change or add a proxy to an existing installation, use the dedicated configure subcommand. The handler at lines 1040-1046 detects when args.key == "proxy" and triggers the same persistence logic as the installer.

agent-reach configure proxy http://user:pass@203.0.113.10:3128

Both methods accept standard proxy URLs including protocol, authentication credentials, IP address, and port.

Runtime Proxy Application

At runtime, Agent-Reach does not manually route HTTP requests through a custom socket layer. Instead, it relies on the standard Unix environment variable convention. Before invoking upstream tools like twitter-cli, rdt-cli, or yt-dlp, the application ensures that HTTP_PROXY and HTTPS_PROXY are set to the value retrieved from Config.get("proxy").

This approach offers two advantages for restricted network environments:

1. Transparency — Downstream binaries automatically detect and use the proxy without requiring additional command-line flags
2. Compatibility — Any subprocess spawned by Agent-Reach inherits the environment, ensuring consistency across Python, Node.js, or Go-based channel implementations

The export happens implicitly when channels initialize their network stacks, guaranteeing that Reddit, Twitter, and YouTube requests traverse the proxy even in headless server deployments.

Verifying and Testing Your Proxy Configuration

To confirm that your proxy settings were saved correctly, inspect the configuration file directly:

cat ~/.agent-reach/config.yaml

You should see output similar to:

proxy: http://user:pass@203.0.113.10:3128
bilibili_proxy: http://user:pass@203.0.113.10:3128

You can also verify programmatically using the Config class in a Python script:

from agent_reach.config import Config
import os

cfg = Config()
proxy = cfg.get("proxy")

if proxy:
    os.environ["HTTP_PROXY"] = proxy
    os.environ["HTTPS_PROXY"] = proxy
    print(f"Proxy configured: {proxy}")
else:
    print("No proxy configured")

This snippet mirrors the internal behavior of Agent-Reach channels, allowing you to test connectivity before running full data collection tasks.

Summary

• Storage Location: Proxy settings reside in ~/.agent-reach/config.yaml under the proxy key (with bilibili_proxy as legacy support)
• CLI Interfaces: Use agent-reach install --proxy <URL> for initial setup or agent-reach configure proxy <URL> for updates
• Runtime Mechanism: The Config class exports HTTP_PROXY and HTTPS_PROXY environment variables for automatic downstream tool consumption
• Override Capability: Config.get() checks environment variables first, enabling temporary overrides without modifying the YAML file
• Implementation Files: Core logic resides in agent_reach/config.py (persistence) and agent_reach/cli.py (argument parsing and commands)

Frequently Asked Questions

What file does Agent-Reach use to store proxy settings?

Agent-Reach stores all proxy configuration in ~/.agent-reach/config.yaml, a per-user YAML file managed by the Config class in agent_reach/config.py. This file contains the proxy key and the legacy bilibili_proxy key.

Can I override the configured proxy using environment variables?

Yes. The Config.get() method implements a fallback chain: it checks the in-memory configuration dictionary first, then looks for an uppercase environment variable of the same name. Setting HTTP_PROXY or HTTPS_PROXY in your shell will override the value saved in the YAML file for that session.

Does Agent-Reach support authenticated proxies?

Yes. The CLI accepts full proxy URLs including authentication credentials in the standard format http://user:pass@ip:port. This URL is stored verbatim in the configuration file and exported as the HTTP_PROXY/HTTPS_PROXY values, which downstream tools parse for authentication.

Which network channels respect the proxy configuration?

All channels that invoke external CLI tools respect the proxy configuration, including those interfacing with Twitter (twitter-cli), Reddit (rdt-cli), and YouTube (yt-dlp). Because Agent-Reach exports HTTP_PROXY and HTTPS_PROXY globally before spawning subprocesses, any tool that respects standard environment variable conventions will route traffic through the configured proxy automatically.

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