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

> Learn to configure proxy support for Agent Reach in restricted networks. Store your proxy URL in config.yaml and set environment variables for seamless API access.

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

---

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

Agent Reach is a multi-channel agent framework that interacts with external services like Twitter, Reddit, and YouTube. When operating behind corporate firewalls or restrictive networks, you must configure proxy support to ensure agents can reach these external APIs.

## Setting the Proxy During Installation

Configure proxy support during initial setup using the `--proxy` flag with the `install` command. According to [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the installer captures the proxy URL and writes it to your configuration file:

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

```

Install with proxy support in one step:

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

```

This persists the proxy URL to `~/.agent-reach/config.yaml` and ensures all subsequent channel operations route through the specified proxy.

You can preview the configuration changes without applying them using the `--dry-run` flag:

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

```

This outputs `[dry-run] Would save network proxy` without modifying your configuration.

## Updating Proxy Settings After Installation

Change or add a proxy configuration after installation using the `configure proxy` sub-command. As implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), this updates the configuration file without reinstalling dependencies:

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

```

Update your proxy configuration with:

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

```

Verify the configuration by viewing the config 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

```

## Runtime Proxy Injection

Agent Reach does not use the proxy configuration directly for its own HTTP requests. Instead, as implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and channel helpers, it injects standard `HTTP_PROXY` and `HTTPS_PROXY` environment variables into subprocess calls when invoking external tools like `twitter-cli`, `rdt-cli`, or Node.js fetch implementations:

```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, used throughout the codebase including [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), ensures that any upstream tool respecting standard proxy environment variables automatically routes traffic through your configured proxy.

## Testing Your Proxy Configuration

Verify that your proxy configuration works correctly using the `doctor` command. This runs health checks across all channels via [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), with each check receiving the proxy environment variables:

```bash
agent-reach doctor

```

If you are using Node.js-based channels that require `undici` for proxy support, ensure it is installed:

```bash
agent-reach install

```

The installer automatically detects Node.js presence and installs `undici` if needed.

## Configuration Security and Sensitive Data Masking

The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) masks proxy-related values when displaying configuration to prevent credential leakage. The system automatically masks any key containing "proxy" along with other sensitive tokens:

```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 security measure ensures that partial proxy URLs are visible for verification while protecting the full credentials from shoulder surfing or log exposure.

## Legacy Key Synchronization

Agent Reach maintains both `proxy` and `bilibili_proxy` configuration keys for backward compatibility. Older versions stored proxy settings exclusively under `bilibili_proxy` (specifically for the Bilibili channel), while newer versions use the generic `proxy` key. The CLI synchronizes both keys during every write operation to ensure existing installations remain compatible after updates.

You should always use the modern `proxy` key when manually editing configuration, as the CLI handles synchronization automatically.

## Summary

- **Initial configuration**: Use `agent-reach install --proxy <url>` to set proxy support during setup
- **Runtime mechanism**: Agent Reach injects `HTTP_PROXY` and `HTTPS_PROXY` into subprocess environments for external tools
- **Configuration location**: Proxy settings persist in `~/.agent-reach/config.yaml` under both `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 exposure
- **Updates**: Change proxy settings anytime with `agent-reach configure proxy <url>`
- **Verification**: Use `agent-reach doctor` to test connectivity through the configured proxy

## Frequently Asked Questions

### Does Agent Reach support authenticated proxies?

Yes, Agent Reach supports authenticated proxies using standard URL format. Include credentials directly in the URL when configuring: `http://username:password@proxy.example.com:3128`. The CLI stores this URL as-is in `~/.agent-reach/config.yaml`, and the authentication credentials are passed to upstream tools through the `HTTP_PROXY` and `HTTPS_PROXY` environment variables.

### Can I use different proxies for HTTP and HTTPS traffic?

Currently, Agent Reach uses a single proxy configuration for both protocols. When you set the proxy via `agent-reach configure proxy`, the system populates both `HTTP_PROXY` and `HTTPS_PROXY` environment variables with the same URL. For protocol-specific proxy separation, you would need to manually export these environment variables before running Agent Reach commands.

### Why does my proxy configuration show only the first 8 characters?

This is a security feature implemented in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). When displaying configuration values, the system masks any key containing "proxy", "password", "token", or "key" to prevent sensitive credential exposure. The full proxy URL remains functional in the configuration file; only the displayed output is truncated.

### How do I verify that the proxy is actually being used?

Run `agent-reach doctor` to execute health checks across all configured channels. If the proxy is correctly configured, channel tests will route through your proxy server. You can also check your proxy server's access logs for requests from Agent Reach processes, or temporarily set an invalid proxy URL to confirm that external connections fail when the proxy is unreachable.