How to Configure Proxy Settings for Networks Blocking Agent Reach Platforms

Agent Reach provides built-in HTTP(S) proxy support via the agent-reach configure proxy command, which stores credentials in ~/.config/agent-reach/config.yml and automatically routes all platform requests through the specified server.

Agent Reach is a Python-based CLI and library that enables AI agents to read and search 13 Internet platforms. Because many corporate and educational networks block direct access to these platforms, the tool includes comprehensive proxy configuration capabilities that allow it to operate within restricted network environments.

Understanding the Proxy Configuration Workflow

The proxy implementation follows a three-stage pipeline that separates user input from runtime execution.

CLI Argument Processing

The configuration begins in agent_reach/cli.py, where the configure command defines a --proxy argument (lines 68-69). When you run the configuration command, the CLI validates the proxy URL and delegates persistent storage to the configuration helper.

Persistent Storage with Backward Compatibility

The agent_reach/config.py module handles all YAML read/write operations. When saving a proxy, the code writes to two keys: proxy (the modern key) and bilibili_proxy (maintained for backward compatibility, lines 232-233). During loading, any configuration key containing the substring proxy is recognized as a network proxy setting (line 106), ensuring flexible key matching.

Runtime HTTP Injection

Individual platform channels do not implement proxy logic directly. Instead, the generic HTTP request helper in agent_reach/core.py reads the proxy value from the loaded configuration and injects it into request headers or environment variables as needed. This abstraction ensures consistent proxy behavior across all 13 supported platforms.

Configuring Proxy Settings via Command Line

The simplest method uses the CLI configuration command to persist settings globally.

# Configure proxy with authentication

python -m agent_reach.cli configure proxy http://user:pass@proxy.mycorp.com:3128

This command writes the URL to your user configuration directory at ~/.config/agent-reach/config.yml. The proxy string supports standard HTTP and HTTPS schemes with optional username/password authentication.

Programmatic Proxy Configuration

You can also modify proxy settings within Python scripts using the Config class.

from agent_reach.config import Config

# Initialize configuration handler

cfg = Config()

# Set proxy for all platforms

cfg.set("proxy", "http://proxy.example.com:8080")
cfg.save()  # Persists to ~/.config/agent-reach/config.yml

# Verify current settings

print("Active proxy:", cfg.get("proxy"))

The Config.set() method automatically synchronizes the legacy bilibili_proxy key, ensuring compatibility with older Agent Reach versions.

Proxy Support for Subprocess and Node.js Clients

For agents that spawn subprocesses or use Node.js-based tools, Agent Reach provides export commands that align with undici proxy requirements (lines 599-609 in cli.py).

# Export proxy environment variables for downstream tools

export HTTP_PROXY=$(agent-reach config get proxy)
export HTTPS_PROXY=$HTTP_PROXY

# Subsequent curl or Node requests will route through the proxy

curl https://api.twitter.com/2/tweets

This ensures that external processes inherit the same proxy configuration without requiring separate manual setup.

Configuration File Location and Format

Agent Reach stores proxy credentials as plain text in the YAML configuration file. The system automatically creates ~/.config/agent-reach/config.yml on first run. Because the proxy value is stored as a standard URI string, you can manually edit this file to update credentials without using the CLI.

Summary

• CLI Configuration: Use agent-reach configure proxy <url> to save settings via agent_reach/cli.py (lines 68-69).
• Dual Key Storage: The system writes to both proxy and bilibili_proxy keys in agent_reach/config.py (lines 232-233) for backward compatibility.
• Automatic Routing: The core.py HTTP helper reads configuration and applies proxies to all platform requests without channel-specific code.
• Subprocess Support: Environment variable exports ensure Node.js clients using undici (lines 599-609) and shell tools inherit proxy settings.
• Flexible Authentication: Supports standard HTTP(S) proxy URLs with embedded credentials (e.g., http://user:pass@host:port).

Frequently Asked Questions

Where does Agent Reach store proxy configuration?

Agent Reach writes proxy settings to ~/.config/agent-reach/config.yml as handled by agent_reach/config.py. The configuration is stored in plain YAML format, making it human-readable and editable with standard text editors.

Does Agent Reach support authenticated proxies?

Yes. The proxy configuration accepts any valid HTTP or HTTPS URL, including those with embedded authentication credentials in the format http://username:password@proxy.example.com:port. Both the CLI and programmatic Config.set() methods preserve these credentials in the configuration file.

How do I use Agent Reach behind a corporate firewall?

First, obtain your corporate proxy URL from your network administrator. Then run agent-reach configure proxy <url> to persist the setting. Agent Reach will automatically route all platform requests through this proxy, including traffic to the 13 Internet platforms it supports. For tools spawned by Agent Reach, export the HTTP_PROXY and HTTPS_PROXY environment variables using the configuration value.

Can I set different proxies for different platforms?

The current implementation uses a single global proxy key that applies to all platforms. However, agent_reach/config.py treats any key containing "proxy" as a potential proxy setting (line 106). While the base core.py implementation uses the global setting, individual channel implementations in agent_reach/channels/base.py could theoretically be extended to check for platform-specific proxy keys (e.g., twitter_proxy) in custom implementations.

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