How to Configure a Network Proxy for Agent Reach in Restricted Networks

Agent Reach supports HTTP(S) proxy configuration via the --proxy flag during installation or the configure proxy command, storing the URL in ~/.agent-reach/config.yaml and injecting it as environment variables for downstream agent subprocesses.

When operating behind corporate firewalls or restricted networks, Agent Reach (from the Panniantong/Agent-Reach repository) allows you to configure a generic HTTP(S) proxy that automatically applies to all external network requests made by agents. The proxy URL is persisted in a local configuration file and exported as HTTP_PROXY and HTTPS_PROXY environment variables whenever agents invoke external commands like yt-dlp or feedparser.

Installation-Time Proxy Configuration

Using the --proxy Flag

You can configure a proxy immediately when installing Agent Reach by passing the --proxy flag to the install command. The CLI parses this argument in agent_reach/cli.py (lines 68-71) and persists it to your configuration file (lines 36-44).

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

This command stores the proxy credentials securely in ~/.agent-reach/config.yaml with restricted file permissions, ensuring subsequent agent operations automatically traverse the network restriction.

Post-Installation Proxy Management

If you need to add or modify a proxy after the initial setup, Agent Reach provides a dedicated configuration sub-command.

Setting or Updating the Proxy

The configure proxy sub-command (implemented in agent_reach/cli.py lines 81-86) updates the stored proxy value without requiring a full reinstallation:

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

Verifying the Current Configuration

To inspect the currently stored proxy value without exposing credentials in shell history, run the command without arguments:

agent-reach configure proxy

This retrieves the value using Config.get("proxy") as implemented in agent_reach/config.py (lines 86-90).

Removing the Proxy

To clear the proxy configuration and return to direct network connections:

agent-reach configure proxy ""

How the Proxy Configuration Works Internally

Understanding the architecture helps troubleshoot connectivity issues in restricted environments.

CLI Parsing and Persistence

When you specify --proxy, the CLI installer in agent_reach/cli.py validates the URL format and writes it to persistent storage. The configuration manager handles the actual file operations, using Config.set("proxy", value) to update the YAML structure while maintaining safe file permissions via make_private_dir in agent_reach/utils/paths.py.

Configuration Storage

The Config class in agent_reach/config.py manages the ~/.agent-reach/config.yaml file. Sensitive values like proxy credentials are stored with appropriate file system permissions, and the proxy key is accessed consistently across the application via Config.get("proxy").

Runtime Injection

When agents execute commands requiring external network access, Agent Reach retrieves the proxy setting and injects it into the subprocess environment. For example, in agent_reach/channels/bilibili.py and other channel implementations, the tool forwards the proxy to underlying utilities like yt-dlp using the --proxy flag or via the HTTP_PROXY environment variable, allowing seamless traversal of restricted networks.

Practical Usage Examples

Passing Proxy to Manual Tool Invocations

For manual debugging or when invoking tools directly outside of Agent Reach, extract the stored proxy and export it:

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

Dry-Run Installation

To verify your proxy configuration before committing changes, use the --dry-run flag:

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

This simulates the installation process without modifying your system, allowing you to confirm the proxy URL parses correctly.

Summary

• Install with proxy: Use agent-reach install --proxy="http://user:pass@host:port" to configure during setup.
• Update anytime: Use agent-reach configure proxy "URL" to modify settings without reinstallation.
• Storage location: Configuration persists in ~/.agent-reach/config.yaml managed by agent_reach/config.py.
• Automatic injection: Saved proxy values export as HTTP_PROXY and HTTPS_PROXY for all agent subprocesses.
• Clear settings: Pass an empty string to configure proxy to remove the configuration.

Frequently Asked Questions

What authentication formats does the Agent Reach proxy support?

Agent Reach accepts standard HTTP(S) proxy URLs including embedded credentials, such as http://user:pass@proxy.host:3128. The URL is stored as-is in the configuration file and passed directly to downstream tools that support proxy authentication.

Where does Agent Reach store the proxy configuration?

The proxy URL is stored in ~/.agent-reach/config.yaml on your local filesystem. The Config class in agent_reach/config.py handles reading and writing these values, while agent_reach/utils/paths.py ensures the directory is created with restricted permissions to protect sensitive credentials.

Do I need to restart agents after changing the proxy configuration?

No, configuration changes take effect immediately for new agent processes. The configure proxy command updates the YAML file instantly, and each subsequent agent invocation reads the current value via Config.get("proxy"). Running agents must be restarted to pick up the new environment variables.

How do I troubleshoot proxy connectivity issues in Agent Reach?

First, verify the stored configuration with agent-reach configure proxy. Then, test the proxy manually using the export method shown above with yt-dlp or curl. Check that your proxy URL includes the correct scheme (http vs https) and that credentials are properly URL-encoded if they contain special characters.

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