Agent Reach Proxy Configuration for Restricted Networks: A Complete Guide

Agent Reach supports corporate firewalls and restricted networks by accepting a generic HTTP(S) proxy URL that it persists to ~/.agent-reach/config.yaml and automatically injects into downstream agent subprocesses via the HTTP_PROXY and HTTPS_PROXY environment variables.

Agent Reach is an open-source automation framework that frequently operates in enterprise environments with strict egress controls. When running in restricted networks, you must configure proxy settings so that agent tools like yt-dlp and feedparser can reach external APIs. This guide covers the proxy architecture, CLI commands, and configuration file mechanics based on the latest source code in the Panniantong/Agent-Reach repository.

How Agent Reach Handles Proxy Configuration

Agent Reach implements a centralized proxy management system that bridges CLI input and runtime environment variables.

Architecture Overview

The proxy handling spans two core components:

1. CLI Interface – Parses the --proxy flag during installation and the configure proxy sub-command for updates. The argument parsing logic resides in agent_reach/cli.py around lines 68-71, while the saving logic is implemented at lines 36-44.
2. Configuration Manager – Persists settings securely in ~/.agent-reach/config.yaml with restricted permissions. The Config class in agent_reach/config.py (lines 86-90) provides Config.set("proxy", ...) for writing and Config.get("proxy") for retrieval, with sensitive values masked in logs.

When an agent triggers a subprocess that requires network access—such as yt-dlp for YouTube subtitles or feedparser for RSS feeds—Agent Reach automatically exports the stored proxy URL as HTTP_PROXY and HTTPS_PROXY environment variables, allowing seamless traversal of restricted networks without code changes.

Setting the Proxy During Installation

Configure a proxy at install time using the --proxy flag. This is the most efficient method for initial setup behind corporate firewalls.

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

The CLI validates the URL format and immediately persists the value to the config file. For a dry run to verify the configuration without applying changes:

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

The parsing logic in agent_reach/cli.py handles the argument, while agent_reach/utils/paths.py ensures the configuration directory is created with safe permissions via make_private_dir.

Updating Proxy Settings After Installation

Use the configure proxy sub-command to modify or inspect proxy settings without reinstalling.

Set or update a proxy:

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

Display the currently stored proxy:

agent-reach configure proxy

Remove the proxy configuration:

agent-reach configure proxy ""

Each command invokes Config.set("proxy", value) or Config.get("proxy") from agent_reach/config.py, ensuring the YAML file remains the single source of truth.

Proxy Propagation to Channel Executions

Channel implementations automatically inherit proxy settings. For example, in agent_reach/channels/bilibili.py, the system retrieves the proxy via Config.get("proxy") and passes it to underlying tools. This pattern is consistent across all channel files—agents invoke external commands with the proxy environment variables pre-populated, so tools like curl or yt-dlp receive the --proxy flag or HTTP_PROXY variable transparently.

If you need to manually invoke a downstream tool with the same proxy:

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

Practical Configuration Examples

One-shot installation with authentication:

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

Post-install reconfiguration:

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

Verification and debugging:

agent-reach configure proxy  # Prints current value

Clearing credentials (empty string):

agent-reach configure proxy ""

Summary

• Configuration storage: Proxy URLs are stored in ~/.agent-reach/config.yaml with restricted file permissions.
• CLI entry points: Use --proxy during installation or configure proxy afterward; both update the same config key via agent_reach/cli.py.
• Runtime injection: Subprocesses receive HTTP_PROXY and HTTPS_PROXY automatically, enabling restricted network access for tools like yt-dlp and feedparser.
• API methods: The Config class in agent_reach/config.py handles persistence through Config.set("proxy", ...) and Config.get("proxy").

Frequently Asked Questions

What proxy formats does Agent Reach support?

Agent Reach accepts standard HTTP(S) proxy URLs with optional authentication, following the format http://user:pass@host:port or https://host:port. The URL is stored as a string and exported directly to environment variables without modification.

Where is the proxy configuration stored?

The configuration is saved in ~/.agent-reach/config.yaml. The Config class in agent_reach/config.py manages this file, using make_private_dir from agent_reach/utils/paths.py to ensure the directory has safe permissions (typically 0o700) before writing sensitive credentials.

How do I remove a configured proxy?

Pass an empty string to the configure command: agent-reach configure proxy "". This clears the stored value, and subsequent agent commands will run without proxy environment variables unless your shell already exports them.

Do all channels automatically use the proxy?

Yes. All channel implementations retrieve the proxy via Config.get("proxy") and forward it to underlying tools. For example, agent_reach/channels/bilibili.py syncs the global proxy setting with channel-specific logic, ensuring consistent network access across all agent operations.

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