# How to Set Up a Proxy for Agent Reach in Restricted Network Environments

> Learn how to set up a proxy for Agent Reach in restricted networks. Configure Agent Reach for proxying external API calls by modifying config.yaml and exporting environment variables.

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

---

**Agent Reach routes all external API calls through a network proxy by storing the configuration in `~/.agent-reach/config.yaml` and automatically exporting `HTTP_PROXY` and `HTTPS_PROXY` environment variables to subprocesses.**

When operating behind corporate firewalls or restrictive networks, Agent Reach requires proxy configuration to reach external services like Twitter, Reddit, and YouTube. The tool provides built-in support for HTTP and HTTPS proxies through both installation flags and runtime configuration commands. This guide explains how to set up a proxy for Agent Reach based on the actual source code implementation in the `Panniantong/Agent-Reach` repository.

## Where Agent Reach Stores Proxy Configuration

Proxy settings are persisted in the user's home directory 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) treats any key containing "proxy" as sensitive data, masking the value when displaying configuration to prevent credential leakage.

In [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the configuration manager identifies sensitive keys using this pattern:

```python

# mask proxy-related keys when showing the config

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 URLs containing authentication credentials are truncated in logs and UI output.

## Configuring the Proxy During Installation

The fastest way to set up a proxy is during the initial installation using the `--proxy` flag. The CLI handler in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) captures the URL and writes it to both the modern `proxy` key and the legacy `bilibili_proxy` key for backward compatibility.

Use this command to install with proxy support:

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

```

The installer executes this logic from [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py):

```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 访问受限网络时使用）")

```

## Updating Proxy Settings After Installation

If the network environment changes, use the `configure proxy` sub-command to update settings without reinstalling. The CLI writes the new value to the configuration file, which takes effect on the next tool invocation.

Update the proxy using:

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

```

The `configure` handler in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) processes this command:

```python
if args.key == "proxy":
    # Nothing reads this key at runtime — agents read it back

    # and export HTTP(S)_PROXY before invoking upstream tools.

    config.set("proxy", value)
    config.set("bilibili_proxy", value)  # keep legacy key in sync

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

```

## How the Proxy is Applied at Runtime

When Agent Reach spawns subprocesses to execute external tools like `twitter-cli`, `rdt-cli`, or Node.js fetch operations, it reads the stored proxy from config and injects it into the environment. This pattern is implemented throughout the codebase to ensure all external binaries inherit the proxy settings.

The runtime injection logic follows this pattern:

```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 applies to all channel operations, ensuring that tools receive the proxy configuration regardless of how they are invoked.

## Understanding the Dual Proxy Keys

The configuration maintains both `proxy` and `bilibili_proxy` keys because older versions of Agent Reach stored proxy settings under the Bilibili-specific key. The installer synchronizes both values to ensure compatibility with legacy code while supporting newer implementations.

When you set either key, the system automatically updates both to prevent configuration drift. You can verify this synchronization by inspecting the config file:

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

```

The output shows both keys populated with identical values:

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

```

## Configuration Examples

### Install with proxy in one step

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

```

This writes the proxy URL to `~/.agent-reach/config.yaml` and enables immediate use for all channel operations.

### Add or change the proxy after installation

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

```

### Verify the configuration

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

```

### Dry-run to preview changes

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

```

Output:

```

[dry-run] Would save network proxy

```

### Run diagnostics with proxy

```bash
agent-reach doctor

```

This runs all channel checks, with each tool receiving the `HTTP_PROXY` and `HTTPS_PROXY` environment variables automatically.

## Summary

- **Configuration location**: Proxy settings are stored in `~/.agent-reach/config.yaml` managed by the `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).
- **Installation setup**: Use `agent-reach install --proxy <url>` to configure during initial setup.
- **Runtime updates**: Use `agent-reach configure proxy <url>` to modify settings without reinstallation.
- **Environment injection**: The proxy is applied at runtime by setting `HTTP_PROXY` and `HTTPS_PROXY` in subprocess environments before invoking external tools.
- **Legacy compatibility**: The system maintains both `proxy` and `bilibili_proxy` keys in sync to support older Agent Reach versions.

## Frequently Asked Questions

### Does Agent Reach support authenticated proxies?

Yes. Include the username and password directly in the URL when configuring the proxy, such as `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) automatically masks these credentials in display output to prevent accidental exposure.

### Why does my configuration show two proxy entries?

Agent Reach writes the proxy URL to both the `proxy` key and the legacy `bilibili_proxy` key. This ensures backward compatibility with older versions of the software that relied on the Bilibili-specific key, while newer code references the generic `proxy` key.

### Do I need to restart Agent Reach after changing the proxy?

No. The `agent-reach configure proxy` command updates the configuration file immediately, and changes take effect on the next external tool invocation. The runtime reads the configuration fresh each time it spawns a subprocess, so no restart is required.

### What happens if the proxy is unreachable?

If the configured proxy is unavailable, external tools invoked by Agent Reach will fail to connect to their respective services (Twitter, Reddit, etc.). The error messages will come from the underlying tools rather than Agent Reach itself. Use `agent-reach doctor` to verify network connectivity and proxy configuration.