# How to Set Up Proxy Support in Agent-Reach for Restricted Networks

> Learn how to set up proxy support in Agent-Reach for restricted networks. Configure your proxy settings in config yaml to ensure smooth API calls.

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

---

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

When operating behind corporate firewalls or restricted networks, Agent-Reach requires proxy configuration to access external services like Twitter, Reddit, and YouTube. The Panniantong/Agent-Reach repository implements a centralized proxy system that persists settings in a local YAML file and automatically applies them to all subprocess calls. This guide explains how to configure proxy support using the CLI and how the runtime applies these settings to external tools.

## Where Proxy Configuration is Stored

The **Config** class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) manages the `~/.agent-reach/config.yaml` file. When displaying configuration values, the system treats any key containing "proxy" as sensitive data and masks the values to prevent credential leakage.

```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

```

The actual proxy URL remains stored in plaintext within the YAML file, ensuring the CLI can read it back when spawning subprocesses.

## Setting the Proxy During Installation

Configure proxy support immediately using the `--proxy` flag with the `install` command. This writes the URL to both the modern `proxy` key and the legacy `bilibili_proxy` key for backward compatibility.

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

```

In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the install handler processes this flag:

```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 the Proxy After Installation

Modify existing proxy settings without reinstallation using the `configure proxy` sub-command. This updates the configuration file directly and takes effect on the next tool invocation.

```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) synchronizes both keys:

```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）")

```

## How the Proxy is Applied at Runtime

When Agent-Reach invokes external binaries (such as `twitter-cli`, `rdt-cli`, or Node.js fetch implementations), it reads the stored proxy and injects it into the subprocess environment. This ensures upstream tools respect the network restrictions.

```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 appears throughout the codebase, including the various `_install_*_deps` helpers in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), guaranteeing that any command executed on the host inherits the proxy settings.

## Legacy Key Synchronization

Older versions of Agent-Reach stored proxy settings under the **bilibili_proxy** key. The current implementation maintains both `proxy` and `bilibili_proxy` in sync to ensure legacy code (particularly the Bilibili channel) continues functioning while newer implementations use the standardized `proxy` key. This dual-key strategy prevents breaking existing installations during upgrades.

## Practical Configuration Examples

1. **Install with proxy in one step**
   ```bash
   agent-reach install --proxy http://user:pass@proxy.example.com:3128
   ```

2. **Update proxy after installation**
   ```bash
   agent-reach configure proxy http://user:pass@proxy.example.com:3128
   ```

3. **Verify configuration file contents**
   ```bash
   cat ~/.agent-reach/config.yaml
   ```

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

4. **Test with dry-run**
   ```bash
   agent-reach install --dry-run --proxy http://proxy:8080
   ```

   
   Output:
   ```

   [dry-run] Would save network proxy
   ```

5. **Validate proxy functionality**
   ```bash
   agent-reach doctor
   ```

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

## Summary

- **Configuration location**: Proxy URLs are stored in `~/.agent-reach/config.yaml` under the `proxy` key, managed by the `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).
- **CLI commands**: Use `agent-reach install --proxy` for initial setup or `agent-reach configure proxy` to update existing settings.
- **Runtime injection**: The CLI reads the config and exports `HTTP_PROXY` and `HTTPS_PROXY` before spawning subprocesses, ensuring all external tools respect the proxy.
- **Backward compatibility**: The system maintains both `proxy` and `bilibili_proxy` keys in sync to support legacy channel implementations.

## Frequently Asked Questions

### What URL format should I use for the proxy configuration?

The CLI accepts standard HTTP proxy URLs that include authentication credentials when necessary. The example implementations in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) demonstrate the format `http://user:pass@proxy.example.com:3128`, which is stored directly in the configuration file and later exported to `HTTP_PROXY` and `HTTPS_PROXY` environment variables.

### Why does my configuration file contain both `proxy` and `bilibili_proxy` entries?

Older versions of Agent-Reach stored proxy settings exclusively under the `bilibili_proxy` key. The current implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) synchronizes both keys during write operations to maintain backward compatibility with legacy channel code while supporting the standardized `proxy` key used by newer implementations. Both entries contain identical values.

### How can I verify the proxy configuration without installing dependencies?

Use the `--dry-run` flag with the install command to preview configuration changes. When executing `agent-reach install --dry-run --proxy http://proxy:8080`, the CLI outputs `[dry-run] Would save network proxy` without actually modifying the configuration file, allowing you to validate the command structure.

### How does Agent-Reach ensure external tools use the configured proxy?

At runtime, the CLI reads the stored proxy from `~/.agent-reach/config.yaml` and injects it into the subprocess environment before executing external binaries. According to the implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the system copies the existing environment, sets `HTTP_PROXY` and `HTTPS_PROXY` to the configured value, and passes this modified environment to `subprocess.run()`, ensuring all upstream tools inherit the proxy settings automatically.