How to Configure Proxy Settings for Restricted Networks in Agent Reach

Agent Reach supports corporate firewalls by accepting a --proxy flag during installation or via the configure proxy command, which stores the URL in ~/.agent-reach/config.yaml and exports it as HTTP_PROXY/HTTPS_PROXY for all downstream agent subprocesses.

Agent Reach is an open-source automation framework that enables AI agents to interact with external platforms like YouTube and Bilibili. When operating behind corporate firewalls or restricted networks, you must configure proxy settings to ensure agents can reach external APIs and download resources. According to the Panniantong/Agent-Reach source code, the tool implements a centralized proxy configuration system that automatically injects credentials into subprocess environments.

Understanding the Proxy Architecture

The proxy implementation spans two core components in the Agent Reach codebase.

CLI Configuration Layer

The command-line interface in agent_reach/cli.py handles proxy arguments during installation and provides a dedicated configuration sub-command. The parsing logic resides at lines 68-71, where the --proxy flag is extracted from the command arguments. The persistence logic at lines 36-44 writes the validated URL to the configuration file. Additionally, lines 81-86 implement the configure proxy sub-command, which allows you to update settings after the initial installation.

Configuration Persistence Layer

The Config class in agent_reach/config.py manages persistent storage in ~/.agent-reach/config.yaml. The implementation at lines 86-90 provides Config.set("proxy", ...) and Config.get("proxy") methods that securely handle the proxy URL. The configuration directory is created with restricted permissions using make_private_dir from agent_reach/utils/paths.py, ensuring that credentials are not accessible to other system users.

Configuring Proxy Settings Step-by-Step

Initial Installation with Proxy

During the initial setup, pass the proxy URL directly to the install command:

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

The --proxy flag accepts standard HTTP(S) proxy URLs including authentication credentials. The CLI parser in agent_reach/cli.py processes this value and immediately persists it to the configuration file via the Config class.

Updating Proxy Settings Post-Installation

To modify or add a proxy after installation, use the dedicated configuration command:

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

This command updates the stored value without requiring a full reinstall. To view the currently configured proxy without changing it, omit the value argument:

agent-reach configure proxy

Removing Proxy Configuration

Clear the proxy setting by passing an empty string:

agent-reach configure proxy ""

This removes the key from ~/.agent-reach/config.yaml and prevents environment variable injection in subsequent agent runs.

How Agent Reach Applies Proxy Settings

When agents execute commands requiring network access, Agent Reach retrieves the proxy URL via Config.get("proxy") from agent_reach/config.py and exports it as HTTP_PROXY and HTTPS_PROXY environment variables. This mechanism ensures that downstream tools like yt-dlp, feedparser, or curl traverse the restricted network transparently without requiring manual configuration for each subprocess.

Channel implementations demonstrate this pattern concretely. For example, in agent_reach/channels/bilibili.py, the configuration retrieves the global proxy value and passes it to the underlying download tool. This architecture ensures consistent proxy application across all supported platforms.

For manual verification or ad-hoc commands, you can export the stored proxy directly from the configuration:

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

Summary

• Agent Reach stores proxy URLs in ~/.agent-reach/config.yaml via the Config class in agent_reach/config.py (lines 86-90).
• Use --proxy during installation or agent-reach configure proxy afterward to set credentials.
• Proxy values are automatically exported as HTTP_PROXY and HTTPS_PROXY for all agent subprocesses.
• Channel implementations like agent_reach/channels/bilibili.py retrieve settings via Config.get("proxy").
• Remove proxy settings by passing an empty string to the configure command.

Frequently Asked Questions

Where does Agent Reach store proxy credentials?

Agent Reach persists proxy settings in the YAML configuration file at ~/.agent-reach/config.yaml. The Config class in agent_reach/config.py (lines 86-90) handles read/write operations with Config.set("proxy", ...) and Config.get("proxy"), while agent_reach/utils/paths.py ensures the directory is created with restricted permissions using make_private_dir.

Does Agent Reach support authenticated proxies?

Yes. The proxy URL format supports standard HTTP(S) authentication syntax: http://username:password@proxy.host:port. Both the CLI parser in agent_reach/cli.py (lines 68-71) and the configuration manager accept URLs containing credentials, which are then injected into subprocess environments.

How do I troubleshoot proxy connectivity issues?

First, verify the stored configuration by running agent-reach configure proxy without arguments to confirm the URL is correct. Test connectivity by manually exporting the proxy to your shell environment with export HTTP_PROXY="$(agent-reach configure proxy)" and attempting a direct request with tools like curl. Check that your proxy supports the HTTPS connections required by Agent Reach channels.

Can I use different proxies for different channels?

Currently, Agent Reach implements a global proxy configuration. The Config.get("proxy") method returns a single value used across all channels, as seen in agent_reach/channels/bilibili.py and other channel implementations. For channel-specific routing, you must configure your proxy server to handle destination-based routing or temporarily update the global setting before running specific agents.

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