How to Set Up Agent Reach Proxy for Restricted Networks: Complete Configuration Guide

Agent Reach supports HTTP(S) proxy configuration via the --proxy flag during installation or the configure proxy command, storing credentials in ~/.agent-reach/config.yaml and injecting them into subprocess environment variables for seamless restricted network access.

Agent Reach is an open-source automation framework that enables AI agents to interact with external platforms, but corporate firewalls and restricted networks often block these connections. Setting up a proxy for Agent Reach ensures that agent subprocesses—whether downloading YouTube content with yt-dlp or fetching RSS feeds—can traverse network restrictions transparently. This guide covers the complete proxy configuration based on the actual implementation in the Panniantong/Agent-Reach repository.

How Agent Reach Handles Proxy Configuration

The proxy system operates through two core components: the CLI interface that captures user input and the configuration manager that persists settings securely.

CLI Argument Parsing

In agent_reach/cli.py, the installation command parses the --proxy flag between lines 68-71, accepting standard HTTP(S) proxy URLs including authentication credentials. The configure proxy sub-command at lines 81-86 provides a dedicated interface for updating proxy settings after initial setup, writing values via the Config class.

Secure Configuration Storage

The Config class in agent_reach/config.py (lines 86-90) handles persistent storage in ~/.agent-reach/config.yaml. The implementation uses agent_reach/utils/paths.py to create the configuration directory with restricted permissions via make_private_dir, ensuring that proxy credentials remain accessible only to the file owner.

Installing Agent Reach Behind a Corporate Proxy

Configure the proxy during initial setup to ensure all subsequent agent operations respect network restrictions.

Use the --proxy flag with the install command:

agent-reach install --env=auto --proxy="http://user:pass@proxy.example.com:3128"

For testing the configuration without applying changes, add the --dry-run flag:

agent-reach install --dry-run --proxy="http://proxy:3128"

The CLI validates the URL format and immediately stores the value using Config.set("proxy", url), persisting to your user-specific configuration file with safe file permissions.

Updating and Verifying Proxy Settings

After installation, modify the proxy configuration without reinstalling the entire framework.

Set or update the proxy using the dedicated sub-command:

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

To view the currently stored proxy value for debugging:

agent-reach configure proxy

This retrieves the value via Config.get("proxy") and outputs the URL, helping verify that authentication credentials persisted correctly.

Remove the proxy configuration entirely by passing an empty string:

agent-reach configure proxy ""

Runtime Proxy Injection for Agent Commands

When agents execute external commands requiring network access, Agent Reach retrieves the stored proxy from ~/.agent-reach/config.yaml and exports it as HTTP_PROXY and HTTPS_PROXY environment variables for child subprocesses.

Channel implementations demonstrate this pattern consistently. For example, in agent_reach/channels/bilibili.py, the code accesses the proxy via Config.get("proxy") and passes it to underlying tools. External utilities like yt-dlp receive the proxy through their native --proxy arguments, while standard HTTP clients use the injected environment variables automatically.

To manually invoke a tool with the configured proxy:

export HTTP_PROXY="$(agent-reach configure proxy)"
yt-dlp --proxy "$HTTP_PROXY" "https://youtu.be/example"

Summary

• Agent Reach supports HTTP(S) proxies via the --proxy installation flag and configure proxy command, storing values in ~/.agent-reach/config.yaml.
• The CLI parser in agent_reach/cli.py (lines 68-71) handles proxy URL validation during installation, while lines 81-86 manage post-install updates.
• The Config class in agent_reach/config.py (lines 86-90) provides secure storage with restricted file permissions via agent_reach/utils/paths.py.
• Agents automatically inject the configured proxy into subprocess environment variables, enabling restricted network traversal without code modifications.

Frequently Asked Questions

What proxy formats does Agent Reach support?

Agent Reach accepts standard HTTP and HTTPS proxy URLs, including optional authentication credentials in the format http://user:pass@host:port or https://host:port. The CLI parser in agent_reach/cli.py validates these URLs before storing them in the configuration file.

Where does Agent Reach store the proxy configuration?

The proxy URL is saved in ~/.agent-reach/config.yaml under the proxy key. The configuration directory is created with restricted permissions using make_private_dir in agent_reach/utils/paths.py to protect credentials containing passwords.

Do I need to restart agents after changing the proxy?

No restart is required. Agent Reach reads the proxy configuration fresh from ~/.agent-reach/config.yaml using Config.get("proxy") each time it spawns a subprocess. Changes made via agent-reach configure proxy take effect immediately for the next agent operation.

How do I troubleshoot proxy connectivity issues?

Verify the stored configuration by running agent-reach configure proxy without arguments to echo the current URL. Check that the proxy format includes the correct scheme and port number. For authenticated proxies, ensure special characters in passwords are properly URL-encoded.

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