How Agent Reach Passes Proxy Configuration to Agents for Restricted Network Access

Agent Reach stores proxy settings in a masked YAML configuration file and automatically exports them to HTTP_PROXY and HTTPS_PROXY environment variables before launching agents, ensuring all HTTP traffic routes through corporate firewalls without manual intervention.

Agent Reach (Panniantong/Agent-Reach) deploys AI agents that frequently operate within restricted network environments. The toolkit implements a centralized proxy configuration system that transparently injects network settings into every agent subprocess, eliminating the need for users to manually configure environment variables for each session.

Configuring the Proxy via CLI

The Configure Command

Users save proxy settings through the CLI configuration interface defined in agent_reach/cli.py. The configure sub-command accepts a --proxy flag that validates and stores the URI for subsequent agent launches.

# Store proxy credentials for all future agent sessions

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

The command parser stores the value using config.set("proxy", args.proxy), simultaneously updating the legacy key bilibili_proxy to maintain backward compatibility with older channel implementations.

Secure Storage in the Config Manager

The Config Singleton

All configuration data persists in a YAML file managed by the Config class in agent_reach/config.py. The class implements a singleton pattern via Config.instance(), ensuring that configuration values load lazily whenever any module imports the configuration manager.

from agent_reach.config import Config

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

Sensitive Value Masking

The Config class treats proxy credentials as sensitive data. When displaying configuration contents via to_dict(), the method automatically masks any key containing the substring proxy to prevent credential leakage in logs or debug output.

print(cfg.to_dict())   # => {"proxy": "http://us..."}

Injecting Proxy Settings into Agent Environments

OpenCLI Backend Environment Preparation

When launching agents, the OpenCLI backend in agent_reach/backends/opencli.py reads the stored proxy configuration and exports it to standard environment variables. This ensures that the proxy configuration is passed to agents through the process environment before any network requests initiate.

import os
from agent_reach.config import Config

def prepare_env():
    cfg = Config.instance()
    proxy_url = cfg.get("proxy")
    if proxy_url:
        os.environ["HTTP_PROXY"] = proxy_url
        os.environ["HTTPS_PROXY"] = proxy_url

By setting HTTP_PROXY and HTTPS_PROXY, the system guarantees that any downstream networking library—including requests, httpx, or Node.js's undici fetch used by the OpenCLI backend—automatically routes traffic through the specified proxy.

Standard Environment Variable Compliance

This approach leverages the de facto standard for HTTP proxy configuration supported across virtually all modern HTTP clients. Agents require no code changes to respect the proxy settings, as the environment variables trigger automatic proxy routing at the library level.

import httpx

def fetch_json(url: str):
    # Automatically uses HTTP_PROXY/HTTPS_PROXY from environment

    resp = httpx.get(url, timeout=10)
    resp.raise_for_status()
    return resp.json()

Channel-Specific Network Handling

Base Channel Implementation

Most channel implementations rely on the shared base class in agent_reach/channels/base.py, which defers proxy handling to the underlying HTTP libraries. These channels automatically benefit from the HTTP_PROXY and HTTPS_PROXY variables set by the OpenCLI backend without requiring explicit proxy configuration in channel code.

Localhost Bypass in Xiaohongshu Channel

Certain channels implement specialized routing logic. The Xiaohongshu channel in agent_reach/channels/xiaohongshu.py explicitly bypasses the proxy for localhost traffic to prevent internal service calls from routing through the external proxy:

# localhost must never be routed through HTTP_PROXY

if target.startswith("http://127.0.0.1"):
    # bypass proxy handling

Legacy Configuration Support

For configurations created with earlier versions of Agent Reach, the system maintains the bilibili_proxy key in sync with the modern proxy key. This ensures that channels still referencing the legacy key continue to function without requiring users to reconfigure their proxy settings after upgrading.

Summary

• CLI Configuration: Use agent-reach configure proxy <url> to store credentials persistently in agent_reach/cli.py.
• Secure Storage: The Config class in agent_reach/config.py masks proxy values and manages the YAML configuration as a singleton.
• Environment Injection: The OpenCLI backend in agent_reach/backends/opencli.py exports HTTP_PROXY and HTTPS_PROXY before launching agents.
• Automatic Routing: Standard HTTP libraries automatically detect these variables, requiring no code changes in agents or channels.
• Specialized Handling: The Xiaohongshu channel demonstrates how to bypass proxies for localhost traffic while maintaining global proxy configuration for external requests.

Frequently Asked Questions

How do I configure a proxy for all Agent Reach agents?

Run the CLI configuration command: agent-reach configure proxy http://user:pass@proxy-host:3128. This stores the setting globally, and the OpenCLI backend automatically exports it to HTTP_PROXY and HTTPS_PROXY environment variables for every subsequent agent launch.

Where is the proxy configuration stored?

The proxy URL is stored in a YAML configuration file managed by the Config class in agent_reach/config.py. The configuration is treated as sensitive data and masked when displayed to prevent credential exposure.

Why does Agent Reach use environment variables instead of passing proxy settings directly to agents?

Agent Reach exports HTTP_PROXY and HTTPS_PROXY because these are standard variables recognized by virtually all HTTP libraries including requests, httpx, and Node.js's undici. This approach ensures universal compatibility without requiring agents to implement proxy-specific configuration code or API modifications.

Does the proxy configuration support authentication?

Yes, the CLI accepts proxy URLs containing credentials in the standard format http://username:password@proxy-host:port. The Config class stores these credentials securely and injects them into the environment variables, where libraries automatically parse and use them for proxy authentication.

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