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

> Learn how to configure a network proxy for Agent Reach in restricted environments. Easily set up HTTP_PROXY and HTTPS_PROXY for seamless API calls. Access the code on GitHub.

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

---

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

When operating behind corporate firewalls or restrictive networks, Agent Reach agents require explicit proxy configuration to access external platforms like Twitter, Reddit, and YouTube. The open-source tool [Panniantong/Agent-Reach](https://github.com/Panniantong/Agent-Reach) provides built-in support for configuring a network proxy for Agent Reach in restricted environments through its CLI and configuration management system. This guide covers the exact implementation details found in the source code, including where settings are stored and how they are injected into subprocess calls.

## Where Agent Reach Stores Proxy Settings

The proxy configuration persists in the user's home directory at `~/.agent-reach/config.yaml`. In [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the `Config` class treats any key containing "proxy" as sensitive data and masks the value when displaying configuration output.

```python

# 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 security measure ensures that proxy credentials are not leaked in debug logs or terminal output, while the full URL remains stored in the YAML file for runtime use.

## Setting the Proxy During Installation

You can configure the proxy immediately during the initial setup using the `--proxy` flag with the install command. 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.

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

```

The underlying Python implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) handles this as follows:

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

To change or add a proxy after installation, use the `configure proxy` sub-command. This updates the stored values without requiring a full reinstallation.

```bash
agent-reach configure 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 synchronizes both configuration 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

Agent Reach does not use the proxy for its own internal Python HTTP requests. Instead, it injects the stored proxy URL into the environment variables of subprocess calls made to external binaries like `twitter-cli`, `rdt-cli`, or Node.js fetch implementations.

The runtime logic follows this pattern found throughout [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py):

```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 ensures that any tool invoked by the channels—whether written in Python, Node.js, or another language—automatically respects the proxy settings via the standard `HTTP_PROXY` and `HTTPS_PROXY` variables.

## Legacy Key Synchronization

Older versions of Agent Reach stored proxy settings exclusively under `bilibili_proxy`. The current implementation maintains both keys simultaneously to ensure compatibility with legacy channel code while modernizing the configuration schema. When you update the proxy using either method described above, both keys are written automatically, preventing breakage in existing installations.

## Verification and Testing

To verify your configuration without executing actual network calls, use the dry-run flag during installation:

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

```

This outputs:

```

[dry-run] Would save network proxy

```

To test that the proxy is correctly passed to external tools, run the diagnostic command:

```bash
agent-reach doctor

```

This executes health checks across all configured channels, and each subprocess receives the `HTTP_PROXY`/`HTTPS_PROXY` variables from your config file. If a channel requires Node.js fetch (which uses `undici`), the installer automatically ensures `undici` is present to handle proxy connections properly.

## Summary

- **Storage Location**: Proxy URLs are stored in `~/.agent-reach/config.yaml` under the `proxy` and `bilibili_proxy` keys.
- **Security**: The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) masks proxy values to prevent credential leakage.
- **Installation**: Use `agent-reach install --proxy <url>` to set the proxy during initial setup.
- **Updates**: Use `agent-reach configure proxy <url>` to modify settings later without reinstallation.
- **Runtime Behavior**: The proxy is exported as `HTTP_PROXY` and `HTTPS_PROXY` environment variables for all subprocess calls via the logic in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).
- **Compatibility**: Both modern and legacy config keys are synchronized to support older channel implementations.

## Frequently Asked Questions

### What file stores the network proxy configuration for Agent Reach?

The configuration is stored in `~/.agent-reach/config.yaml` in your home directory. This file is managed by the `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), which treats proxy-related keys as sensitive and masks them when displaying configuration output.

### Why does Agent Reach maintain both `proxy` and `bilibili_proxy` configuration keys?

The `bilibili_proxy` key is a legacy identifier from earlier versions of the software. Current implementations in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) write to both `proxy` (the modern key) and `bilibili_proxy` simultaneously to ensure backward compatibility with older channel code that may still reference the legacy key.

### How do I verify that my proxy settings are active without making live API calls?

Run `agent-reach install --dry-run --proxy <url>` to preview configuration changes without writing them, or execute `agent-reach doctor` to perform health checks. The doctor command invokes channel binaries with the `HTTP_PROXY` and `HTTPS_PROXY` environment variables set from your config, allowing you to verify the setup is correct.

### Does Agent Reach support authenticated proxies with username and password?

Yes. The configuration accepts standard proxy URLs containing credentials in the format `http://user:pass@host:port`. These URLs are stored as-is in `~/.agent-reach/config.yaml` and exported to the environment variables, which upstream tools like `curl`, Node.js fetch, and Python `requests` all support.