How to Configure a Proxy for Agent-Reach in Restricted Network Environments

To configure a proxy for Agent-Reach, use the --proxy flag during installation or the configure proxy sub-command, which stores the URL in ~/.agent-reach/config.yaml and exports it as HTTP_PROXY/HTTPS_PROXY for downstream agent commands.

Agent-Reach is an open-source automation framework that enables agents to interact with external platforms like YouTube and Bilibili. When operating behind corporate firewalls or restricted networks, you must configure a generic HTTP(S) proxy to allow these agents to reach external APIs and download resources. The proxy configuration is handled natively by the CLI and applied transparently to all subprocesses invoked by agents.

Installation-Time Proxy Configuration

Using the --proxy Flag

During initial setup, pass the proxy URL directly to the installer. This captures the credentials and endpoint in a single command.

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

The CLI parses this argument in agent_reach/cli.py around lines 68-71, validating the URL format before passing it to the configuration layer. For a dry run to preview the configuration without applying changes, append the --dry-run flag:

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

Persistent Storage in config.yaml

Upon installation, Agent-Reach writes the proxy value to ~/.agent-reach/config.yaml with restricted file permissions. The storage operation occurs in agent_reach/cli.py at lines 36-44, utilizing the Config class to ensure sensitive values are masked in logs.

Post-Installation Proxy Management

Setting or Updating the Proxy

If the network environment changes or you skipped the flag during installation, use the dedicated sub-command to persist a new proxy URL:

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

This command is implemented in agent_reach/cli.py between lines 81-86 and provides a shortcut to update the configuration without re-running the full installer.

Verifying and Removing Proxy Settings

To inspect the currently stored proxy value, invoke the command without arguments:

agent-reach configure proxy

This prints the saved URL to stdout, which you can capture into environment variables for manual debugging:

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

To clear the configuration and disable proxy routing entirely, pass an empty string:

agent-reach configure proxy ""

How the Proxy is Applied to Agent Operations

When an agent executes a command requiring network access (such as yt-dlp for YouTube subtitles or feedparser for RSS feeds), Agent-Reach retrieves the proxy setting via Config.get("proxy") and injects it into the subprocess environment as HTTP_PROXY and HTTPS_PROXY. This mechanism allows external tools to traverse the restricted network transparently without code modifications.

Channels like agent_reach/channels/bilibili.py demonstrate this pattern by syncing the global proxy value into tool-specific arguments (e.g., passing --proxy to yt-dlp).

Code Implementation Details

CLI Parsing Logic in cli.py

The CLI installer handles argument parsing for the --proxy flag and the configure proxy sub-command. In agent_reach/cli.py, lines 68-71 define the argument structure, while lines 36-44 handle the persistence logic that writes the value to disk.

Configuration Manager in config.py

The Config class in agent_reach/config.py (lines 86-90) manages the YAML configuration file. It provides Config.set("proxy", value) for writes and Config.get("proxy") for reads, ensuring that proxy credentials are stored securely and accessed consistently across the application.

Directory Permissions in paths.py

Before writing the configuration, Agent-Reach creates the user config directory using make_private_dir from agent_reach/utils/paths.py. This ensures that ~/.agent-reach/ and its contents are created with strict permissions to prevent credential leakage.

Channel Integration

Each channel implementation retrieves the proxy configuration independently. For example, agent_reach/channels/bilibili.py accesses the proxy via the Config singleton and forwards it to any underlying HTTP clients or command-line tools, maintaining consistent network behavior across all agent activities.

Summary

• Set during install: Use agent-reach install --proxy="http://..." to configure the proxy initially.
• Update anytime: Use agent-reach configure proxy "http://..." to change settings without reinstalling.
• Storage location: Values are saved in ~/.agent-reach/config.yaml via the Config class in agent_reach/config.py.
• Transparent application: The proxy is exported as HTTP_PROXY/HTTPS_PROXY environment variables for all agent subprocesses.
• Security: Configuration directories are created with restricted permissions via make_private_dir in agent_reach/utils/paths.py.

Frequently Asked Questions

How do I check if Agent-Reach is using my configured proxy?

Run agent-reach configure proxy without arguments to print the stored URL. Additionally, you can verify environment variable injection by running an agent in verbose mode and inspecting the subprocess environment, or by checking network logs on your proxy server for requests originating from Agent-Reach tools like yt-dlp.

Can I use an authenticated proxy with special characters in the password?

Yes. When passing the URL via --proxy or configure proxy, ensure special characters in the username or password are URL-encoded (e.g., @ becomes %40). The Config class in agent_reach/config.py stores the string literal and passes it directly to subprocesses, preserving your credentials as provided.

Why does Agent-Reach store the proxy in a YAML file instead of using system environment variables?

Storing the proxy in ~/.agent-reach/config.yaml provides persistence across terminal sessions and reboots. While you can manually export HTTP_PROXY in your shell, the YAML approach ensures that agents launched via cron jobs, systemd services, or IDEs automatically inherit the correct proxy settings without requiring global system configuration changes.

Where is the proxy configuration file located, and is it secure?

The configuration resides at ~/.agent-reach/config.yaml. The directory is created by make_private_dir in agent_reach/utils/paths.py with mode 0o700 (owner read/write/execute only), ensuring other users on the system cannot read your proxy credentials or other sensitive settings.

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