How to Configure Network Proxy for Agent-Reach Agents

Agent-Reach routes all agent traffic through standard HTTP proxies by reading HTTP_PROXY environment variables or proxy keys stored in ~/.agent-reach/config.yaml, with the underlying Python HTTP clients automatically picking up these settings.

Agent-Reach is an open-source automation framework that enables agents to interact with platforms like Twitter, Reddit, and YouTube. When deploying agents behind corporate firewalls or in restricted network environments, you must configure network proxy settings to ensure outbound connectivity. This guide explains the two supported methods for configuring proxies based on the actual implementation in the Panniantong/Agent-Reach repository.

Setting Up Proxy via Environment Variables

The simplest way to configure a network proxy for agents is to set standard environment variables before invoking the CLI or importing the Python library. Agent-Reach relies on underlying HTTP libraries that automatically detect and use these variables.

Set the following variables in your shell:

export HTTP_PROXY="http://proxy.example.com:3128"
export HTTPS_PROXY="http://proxy.example.com:3128"
export ALL_PROXY="http://proxy.example.com:3128"

Once exported, all subsequent agent-reach commands and Python API calls will route traffic through the specified proxy server. This method works immediately without modifying any configuration files.

Configuring Proxy in the Agent-Reach Config File

Alternatively, you can persist proxy settings in the YAML configuration file located at ~/.agent-reach/config.yaml. The Config class in agent_reach/config.py specifically handles keys containing the substring "proxy" and makes them available to all agent components.

Manual Configuration

Edit ~/.agent-reach/config.yaml directly to add proxy entries:

# ~/.agent-reach/config.yaml

http_proxy: "http://proxy.example.com:3128"
https_proxy: "http://proxy.example.com:3128"
proxy_url: "http://proxy.example.com:3128"

Any key name containing the word "proxy" (such as http_proxy, https_proxy, or proxy_url) will be recognized by the configuration system.

Using the CLI

You can also set these values programmatically using the CLI entry point implemented in agent_reach/cli.py:

agent-reach config set http_proxy "http://proxy.example.com:3128"
agent-reach config set https_proxy "http://proxy.example.com:3128"

This command writes the key-value pair to ~/.agent-reach/config.yaml and ensures proper formatting.

How Proxy Configuration Works Under the Hood

The Config class in agent_reach/config.py implements a fallback mechanism that prioritizes configuration file values while falling back to environment variables. When you call Config.get(), the method first checks the YAML data, then checks for an uppercase environment variable:

def get(self, key: str, default: Any = None) -> Any:
    # Config file first

    if key in self.data:
        return self.data[key]
    # Then env var (uppercase)

    env_val = os.environ.get(key.upper())
    if env_val:
        return env_val
    return default

Consequently, a proxy defined in config.yaml is effectively a shortcut for setting the matching environment variable. Both mechanisms are functionally equivalent because the underlying HTTP libraries first consult the environment, and the Config helper bridges the two sources.

Additionally, the configuration system masks sensitive values when printing. In agent_reach/config.py, any key containing "proxy" is automatically obfuscated to prevent credential leakage:

for k, v in self.data.items():
    if any(s in k.lower() for s in ("key", "token", "password", "proxy")):
        masked[k] = f"{str(v)[:8]}..." if v else None

This security feature explains why your proxy URL appears truncated when viewing the configuration.

Verifying Your Proxy Configuration

To confirm that your network proxy is properly configured, retrieve the value using the Python API:

from agent_reach.config import Config

cfg = Config()
http_proxy = cfg.get("http_proxy")  # Returns value from config.yaml or HTTP_PROXY env var

https_proxy = cfg.get("https_proxy")

print(f"HTTP Proxy: {http_proxy}")
print(f"HTTPS Proxy: {https_proxy}")

If the returned values match your intended proxy server, all Agent-Reach agents will route their traffic accordingly. This applies universally across all supported platforms (Twitter, Reddit, YouTube, etc.) because the underlying HTTP clients respect the standard proxy environment variables.

Summary

• Environment variables (HTTP_PROXY, HTTPS_PROXY) provide immediate, session-based proxy configuration without file modifications.
• Configuration file (~/.agent-reach/config.yaml) offers persistent storage for proxy settings, with keys containing "proxy" automatically masked for security.
• The Config class in agent_reach/config.py implements a fallback chain: config file values take precedence, followed by uppercase environment variables.
• Proxy settings apply globally to all agents because the underlying HTTP libraries inherit these standard Python proxy conventions.

Frequently Asked Questions

Does Agent-Reach support authenticated proxies?

Yes. You can include credentials directly in the URL using the standard format http://username:password@proxy.example.com:3128. Whether set via environment variables or the configuration file, the underlying HTTP clients will parse and use the authentication credentials automatically.

Why is my proxy URL masked when I print the configuration?

The Config class in agent_reach/config.py treats any key containing the substring "proxy" as sensitive. When the configuration is displayed, these values are truncated to the first 8 characters followed by ellipses to prevent accidental exposure of internal network addresses in logs or terminal output.

Can I use different proxies for different agents?

Agent-Reach currently uses a global configuration system. While you cannot assign different proxies to individual agents through the configuration file, you can achieve this by setting specific environment variables in separate shell sessions or process environments before launching each agent instance.

Which proxy settings take precedence?

Configuration file values in ~/.agent-reach/config.yaml take precedence over environment variables. However, if a key exists only as an environment variable (e.g., HTTP_PROXY exists but http_proxy is not in the config file), the Config.get() method will return the environment variable value. The underlying HTTP libraries ultimately decide precedence, but they typically honor the standard HTTP_PROXY and HTTPS_PROXY variables when no explicit proxy is configured in the request.

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