# How Agent Reach Passes Proxy Configuration to Agents for Restricted Network Access

> Agent Reach automatically passes proxy settings to agents via environment variables for restricted network access. Learn how this ensures secure firewall traversal without manual setup.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-12

---

**Agent Reach stores proxy settings in a masked YAML configuration file and automatically exports them to `HTTP_PROXY` and `HTTPS_PROXY` environment variables before launching agents, ensuring all HTTP traffic routes through corporate firewalls without manual intervention.**

Agent Reach (Panniantong/Agent-Reach) deploys AI agents that frequently operate within restricted network environments. The toolkit implements a centralized proxy configuration system that transparently injects network settings into every agent subprocess, eliminating the need for users to manually configure environment variables for each session.

## Configuring the Proxy via CLI

### The Configure Command

Users save proxy settings through the CLI configuration interface defined in **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)**. The `configure` sub-command accepts a `--proxy` flag that validates and stores the URI for subsequent agent launches.

```bash

# Store proxy credentials for all future agent sessions

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

```

The command parser stores the value using `config.set("proxy", args.proxy)`, simultaneously updating the legacy key `bilibili_proxy` to maintain backward compatibility with older channel implementations.

## Secure Storage in the Config Manager

### The Config Singleton

All configuration data persists in a YAML file managed by the `Config` class in **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)**. The class implements a singleton pattern via `Config.instance()`, ensuring that configuration values load lazily whenever any module imports the configuration manager.

```python
from agent_reach.config import Config

cfg = Config.instance()
proxy_url = cfg.get("proxy")

```

### Sensitive Value Masking

The `Config` class treats proxy credentials as sensitive data. When displaying configuration contents via `to_dict()`, the method automatically masks any key containing the substring *proxy* to prevent credential leakage in logs or debug output.

```python
print(cfg.to_dict())   # => {"proxy": "http://us..."}

```

## Injecting Proxy Settings into Agent Environments

### OpenCLI Backend Environment Preparation

When launching agents, the OpenCLI backend in **[`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py)** reads the stored proxy configuration and exports it to standard environment variables. This ensures that the proxy configuration is passed to agents through the process environment before any network requests initiate.

```python
import os
from agent_reach.config import Config

def prepare_env():
    cfg = Config.instance()
    proxy_url = cfg.get("proxy")
    if proxy_url:
        os.environ["HTTP_PROXY"] = proxy_url
        os.environ["HTTPS_PROXY"] = proxy_url

```

By setting `HTTP_PROXY` and `HTTPS_PROXY`, the system guarantees that any downstream networking library—including `requests`, `httpx`, or Node.js's *undici* fetch used by the OpenCLI backend—automatically routes traffic through the specified proxy.

### Standard Environment Variable Compliance

This approach leverages the de facto standard for HTTP proxy configuration supported across virtually all modern HTTP clients. Agents require no code changes to respect the proxy settings, as the environment variables trigger automatic proxy routing at the library level.

```python
import httpx

def fetch_json(url: str):
    # Automatically uses HTTP_PROXY/HTTPS_PROXY from environment

    resp = httpx.get(url, timeout=10)
    resp.raise_for_status()
    return resp.json()

```

## Channel-Specific Network Handling

### Base Channel Implementation

Most channel implementations rely on the shared base class in **[`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py)**, which defers proxy handling to the underlying HTTP libraries. These channels automatically benefit from the `HTTP_PROXY` and `HTTPS_PROXY` variables set by the OpenCLI backend without requiring explicit proxy configuration in channel code.

### Localhost Bypass in Xiaohongshu Channel

Certain channels implement specialized routing logic. The Xiaohongshu channel in **[`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py)** explicitly bypasses the proxy for localhost traffic to prevent internal service calls from routing through the external proxy:

```python

# localhost must never be routed through HTTP_PROXY

if target.startswith("http://127.0.0.1"):
    # bypass proxy handling

```

## Legacy Configuration Support

For configurations created with earlier versions of Agent Reach, the system maintains the `bilibili_proxy` key in sync with the modern `proxy` key. This ensures that channels still referencing the legacy key continue to function without requiring users to reconfigure their proxy settings after upgrading.

## Summary

- **CLI Configuration**: Use `agent-reach configure proxy <url>` to store credentials persistently in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).
- **Secure Storage**: The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) masks proxy values and manages the YAML configuration as a singleton.
- **Environment Injection**: The OpenCLI backend in [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py) exports `HTTP_PROXY` and `HTTPS_PROXY` before launching agents.
- **Automatic Routing**: Standard HTTP libraries automatically detect these variables, requiring no code changes in agents or channels.
- **Specialized Handling**: The Xiaohongshu channel demonstrates how to bypass proxies for localhost traffic while maintaining global proxy configuration for external requests.

## Frequently Asked Questions

### How do I configure a proxy for all Agent Reach agents?

Run the CLI configuration command: `agent-reach configure proxy http://user:pass@proxy-host:3128`. This stores the setting globally, and the OpenCLI backend automatically exports it to `HTTP_PROXY` and `HTTPS_PROXY` environment variables for every subsequent agent launch.

### Where is the proxy configuration stored?

The proxy URL is stored in a YAML configuration file managed by the `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). The configuration is treated as sensitive data and masked when displayed to prevent credential exposure.

### Why does Agent Reach use environment variables instead of passing proxy settings directly to agents?

Agent Reach exports `HTTP_PROXY` and `HTTPS_PROXY` because these are standard variables recognized by virtually all HTTP libraries including `requests`, `httpx`, and Node.js's `undici`. This approach ensures universal compatibility without requiring agents to implement proxy-specific configuration code or API modifications.

### Does the proxy configuration support authentication?

Yes, the CLI accepts proxy URLs containing credentials in the standard format `http://username:password@proxy-host:port`. The `Config` class stores these credentials securely and injects them into the environment variables, where libraries automatically parse and use them for proxy authentication.