# How Agent Reach Manages Proxy Configurations Using Environment Variables

> Learn how Agent Reach manages proxy configurations with environment variables. See how it automatically sets HTTP_PROXY and HTTPS_PROXY for seamless proxy integration.

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

---

**Agent Reach manages proxy configurations using environment variables by persisting a user-defined proxy URL in a YAML configuration file and automatically exporting it as `HTTP_PROXY` and `HTTPS_PROXY` at runtime.**

Agent Reach is an open-source framework that streamlines network proxy management for agents operating behind corporate firewalls or restricted networks. The system manages proxy configurations using environment variables through a centralized YAML config file, eliminating the need to hardcode proxy settings into individual channel modules. According to the Panniantong/Agent-Reach source code, this approach follows a three-step workflow: persistence via CLI command, retrieval from the config module, and injection into the process environment.

## Configuring the Proxy via the CLI

The entry point for proxy management is the `configure proxy` command. In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the argument parser captures the user-supplied URL and invokes the configuration helper to persist the value. Specifically, lines 237–242 handle the logic that writes the proxy setting to the configuration store using `config.set("proxy", args.proxy)`.

To set a proxy for all subsequent operations, users run:

```bash
agent-reach configure proxy http://user:pass@proxy.example.com:8080

```

The CLI accepts an empty string as the default value, allowing users to clear a previously configured proxy by passing an empty argument.

## Persisting Proxy Settings in YAML

The configuration module [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) defines valid configuration keys in the `ALLOWED_KEYS` list, which explicitly includes `"proxy"` at line 114. When the CLI executes, it calls `config.set("proxy", args.proxy)` to write the URL to the YAML configuration file.

To maintain backward compatibility, the framework simultaneously writes the same value to the legacy `bilibili_proxy` key. This dual-key strategy ensures that older deployments referencing the legacy name continue to function while newer implementations use the standardized `proxy` key.

## Runtime Environment Variable Injection

At startup, Agent Reach retrieves the stored proxy value and exports it to the process environment as **`HTTP_PROXY`** and **`HTTPS_PROXY`**. This injection enables standard HTTP clients—such as `requests`, `httpx`, or Node.js `undici`—to route traffic through the configured proxy transparently.

The framework only sets these variables if a proxy URL is present in the configuration, ensuring clean operation in environments without proxy requirements. This design allows all channel implementations to inherit proxy settings automatically without modifying their underlying network code.

## Practical Implementation Examples

Inspecting the stored configuration values programmatically:

```python
from agent_reach.config import Config

cfg = Config()
print(cfg.get("proxy"))           # → http://user:pass@proxy.example.com:8080

print(cfg.get("bilibili_proxy"))  # → same value (legacy key)

```

Excerpt from [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) demonstrating the configuration write logic:

```python
if args.proxy:
    print(f"[dry-run] Would save network proxy")
    config.set("proxy", args.proxy)
    config.set("bilibili_proxy", args.proxy)  # legacy key

```

Conceptual illustration of environment variable export during startup:

```python
import os

proxy = cfg.get("proxy")
if proxy:
    os.environ["HTTP_PROXY"] = proxy
    os.environ["HTTPS_PROXY"] = proxy

```

## Summary

- **CLI Configuration**: Use `agent-reach configure proxy <URL>` to persist settings via [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 237–242).
- **YAML Storage**: Values are stored under the `proxy` key in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), with legacy synchronization to `bilibili_proxy`.
- **Environment Injection**: The framework automatically exports the configured URL to `HTTP_PROXY` and `HTTPS_PROXY` environment variables at runtime.
- **Universal Compatibility**: Downstream HTTP clients inherit proxy settings transparently without code modifications.

## Frequently Asked Questions

### How do I set a proxy for Agent Reach using environment variables?

Agent Reach does not require manual export of environment variables. Instead, run `agent-reach configure proxy <PROXY_URL>` to store the URL in the configuration file. The framework automatically injects this value as `HTTP_PROXY` and `HTTPS_PROXY` when it starts, making the proxy active for all network operations.

### What is the difference between the `proxy` and `bilibili_proxy` configuration keys?

The `proxy` key is the current standard configuration entry defined in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), while `bilibili_proxy` is a legacy key maintained for backward compatibility. When you set a proxy via the CLI, Agent Reach writes the identical URL to both keys to ensure older installations continue to function correctly.

### Where does Agent Reach store the proxy configuration?

Agent Reach stores the proxy URL in a YAML configuration file managed by the [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) module. The CLI command in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) handles persistence, writing the value to the configuration using `config.set()` and validating it against the `ALLOWED_KEYS` list.

### Can I use Agent Reach behind a corporate firewall without modifying channel code?

Yes. By configuring the proxy via the CLI, Agent Reach manages proxy configurations using environment variables that are automatically supplied to every agent-run request. This design allows all channel implementations to route traffic through the specified proxy without requiring changes to their underlying network code.