# Configuring a Network Proxy in Agent Reach for Restricted Networks

> Learn how to configure a network proxy in Agent Reach for restricted networks. Easily set up proxy URLs to route API calls and inject environment variables for seamless integration.

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

---

**Agent Reach routes all external API calls through a configurable network proxy by storing the proxy URL in `~/.agent-reach/config.yaml` and automatically injecting `HTTP_PROXY` and `HTTPS_PROXY` environment variables into every subprocess invocation.**

Agent Reach is an open-source automation framework that interacts with external platforms like Twitter, Reddit, YouTube, and Bilibili. When operating behind corporate firewalls or restricted networks, you must configure proxy support to ensure agents can reach these services. This guide explains how to set up, update, and verify proxy configuration using the CLI and configuration files.

## Where Proxy Settings Are Stored

Proxy configuration persists in the YAML file located at `~/.agent-reach/config.yaml`. The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) manages this file and handles all read and write operations for the `proxy` and `bilibili_proxy` keys.

### Security Masking for Sensitive Values

The configuration manager treats proxy URLs as sensitive data to prevent credential leakage. When displaying configuration values, the system masks any key containing the substring "proxy" by truncating the value to eight characters and appending an ellipsis.

```python

# From agent_reach/config.py

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

```

This ensures that proxy authentication credentials remain secure in logs and terminal output while still allowing you to verify that a proxy is configured.

## Setting the Proxy During Installation

You can configure the proxy during the initial installation using the `--proxy` flag. This captures the proxy URL and persists it to the configuration file immediately.

### Using the --proxy Flag

When running `agent-reach install`, append the `--proxy` argument followed by your proxy URL:

```bash
agent-reach install --proxy http://user:pass@proxy.example.com:3128

```

According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), this command writes the proxy URL to both the `proxy` key and the legacy `bilibili_proxy` key:

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

        print(f"✅ 代理已保存（Agent 访问受限网络时使用）")

```

### Preview Changes with Dry-Run

To preview what the installer would configure without modifying the system, use the `--dry-run` flag:

```bash
agent-reach install --dry-run --proxy http://proxy:8080

```

This outputs `[dry-run] Would save network proxy` without writing to the configuration file.

## Updating Proxy Configuration After Installation

You can modify proxy settings at any time using the `configure` command without reinstalling the entire framework.

### The configure proxy Command

Update the stored proxy URL using the `configure proxy` sub-command:

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

```

As implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), this command updates both configuration keys to maintain backward compatibility:

```python
if args.key == "proxy":
    config.set("proxy", value)
    config.set("bilibili_proxy", value)  # keep legacy key in sync

    print("✅ 代理已保存（供 Agent 在访问 Reddit/Twitter 等需要代理的网络时设置 HTTP_PROXY/HTTPS_PROXY）")

```

Verify the configuration by viewing the YAML file:

```bash
cat ~/.agent-reach/config.yaml

```

The output shows both keys synchronized:

```yaml
proxy: http://user:pass@proxy.example.com:3128
bilibili_proxy: http://user:pass@proxy.example.com:3128

```

## How Agent Reach Applies Proxy Settings at Runtime

Agent Reach does not use the proxy configuration directly for its own HTTP requests. Instead, it injects the settings into the environment of subprocesses that execute external tools and channel binaries.

### Environment Variable Injection

Before invoking any external binary (such as `twitter-cli`, `rdt-cli`, or Node.js fetch implementations), the CLI reads the stored proxy and populates standard environment variables:

```python
env = os.environ.copy()
if config.get("proxy"):
    env["HTTP_PROXY"] = config.get("proxy")
    env["HTTPS_PROXY"] = config.get("proxy")
subprocess.run([binary, "..."], env=env, …)

```

This pattern, found in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and utilized by [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) and [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), ensures that upstream tools respect the proxy settings without requiring individual configuration.

### Legacy Key Support

Older versions of Agent Reach stored proxy settings exclusively under the `bilibili_proxy` key. The current implementation maintains both keys to ensure backward compatibility with legacy channel implementations while supporting new features that read the standardized `proxy` key.

## Verifying Proxy Configuration

After configuring the proxy, verify connectivity using the built-in diagnostic command:

```bash
agent-reach doctor

```

This command runs health checks across all configured channels, with each subprocess receiving the `HTTP_PROXY` and `HTTPS_PROXY` environment variables automatically.

For Node.js-based channels that use `undici` for HTTP requests, ensure the dependency is installed:

```bash
agent-reach install

```

The installer automatically detects Node.js and installs `undici` if present, enabling proper proxy support for modern fetch implementations.

## Summary

- **Storage Location**: Proxy settings reside in `~/.agent-reach/config.yaml` and are managed by the `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).
- **Configuration Methods**: Use `agent-reach install --proxy <url>` during setup or `agent-reach configure proxy <url>` for updates.
- **Environment Variables**: The runtime injects `HTTP_PROXY` and `HTTPS_PROXY` into every subprocess environment before invoking external tools.
- **Dual Key Storage**: Both `proxy` and `bilibili_proxy` keys are maintained for backward compatibility with legacy channel implementations.
- **Security**: Proxy values are masked in output to prevent credential leakage in logs and terminal sessions.

## Frequently Asked Questions

### What environment variables does Agent Reach use for proxy configuration?

Agent Reach reads the `proxy` value from its configuration file and exports it as both `HTTP_PROXY` and `HTTPS_PROXY` environment variables before spawning subprocesses. This follows the standard convention that most HTTP clients and CLI tools respect.

### Why does Agent Reach store both proxy and bilibili_proxy keys?

Older versions of the framework used only the `bilibili_proxy` key. The current implementation writes to both `proxy` and `bilibili_proxy` to maintain backward compatibility with legacy code while transitioning to a standardized key name used by newer channel implementations.

### How can I verify that my proxy configuration is active?

Run `cat ~/.agent-reach/config.yaml` to confirm the proxy URL appears in the file. Then execute `agent-reach doctor` to test connectivity across all channels. If the proxy is configured correctly, external API calls will succeed even in restricted network environments.

### Does Agent Reach support authenticated proxies?

Yes. Include the username and password directly in the proxy URL when configuring: `http://user:pass@proxy.example.com:3128`. The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) masks these credentials in display output to prevent exposure in logs or terminal sessions.