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

> Learn how to set up a network proxy for restricted environments in Agent Reach. Configure proxy settings and environment variables for seamless API calls.

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

---

**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` and `HTTPS_PROXY` environment variables before invoking any subprocess.**

When operating behind corporate firewalls or restrictive networks, Agent Reach requires proxy configuration to access external services like Twitter, Reddit, and YouTube. The open-source tool `Panniantong/Agent-Reach` provides built-in proxy support that persists credentials in a local YAML file and automatically injects them into subprocess environments. This guide explains how to set up a network proxy for restricted environments in Agent Reach using the CLI configuration commands and the underlying Python implementation.

## Where Proxy Settings Are Stored

Agent Reach centralizes configuration management in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). The `Config` class persists all settings to `~/.agent-reach/config.yaml`, including proxy credentials. When displaying configuration values, the system masks any key containing "proxy" as sensitive data to prevent credential leakage in logs or terminal output.

In [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the masking logic appears as:

```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 while the full proxy URL is stored in the YAML file, only the first eight characters are visible when running configuration diagnostics.

## Setting the Proxy During Installation

The fastest way to configure proxy support 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 proxy URL and writes it to two configuration keys: `proxy` (the current standard) and `bilibili_proxy` (for backward compatibility).

When running `agent-reach install`, the installation handler executes:

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

```

To install with proxy support in one command:

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

```

This writes the proxy URL to both keys in `~/.agent-reach/config.yaml`, ensuring immediate compatibility with all channel implementations.

## Updating Proxy Configuration After Installation

You can modify the proxy settings at any time without reinstalling the tool using the `configure` sub-command. The `configure proxy` handler in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) updates the configuration file directly:

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

```

Update your proxy configuration with:

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

```

## Runtime Proxy Application

At runtime, Agent Reach reads the stored proxy value and injects it into the environment of any subprocess that requires external network access. This pattern is implemented throughout the codebase, particularly in channel handlers and dependency installation helpers.

Before invoking external binaries like `twitter-cli` or `rdt-cli`, the code prepares the environment:

```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 all upstream tools respect the proxy settings without requiring individual configuration.

## Legacy Bilibili Proxy Support

Older versions of Agent Reach stored proxy settings exclusively under the key `bilibili_proxy`. The current implementation maintains both keys simultaneously to ensure backward compatibility. When you set or update the proxy using modern CLI commands, both `proxy` and `bilibili_proxy` are synchronized to the same value, preventing breaking changes for legacy channel implementations.

## Configuration Examples

### Install with Proxy Authentication

Configure proxy support during installation, including credentials:

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

```

Result: The proxy URL is written to `~/.agent-reach/config.yaml` under both `proxy` and `bilibili_proxy` keys.

### Update Proxy After Installation

Change proxy settings without reinstalling:

```bash
agent-reach configure proxy http://new-proxy.company.com:8080

```

### Verify Current Configuration

Inspect the stored configuration while respecting sensitive data masking:

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

```

Expected output:

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

```

### Dry-Run Installation

Preview what would be saved without writing to disk:

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

```

Output:

```

[dry-run] Would save network proxy

```

### Validate Proxy with Health Checks

Run the diagnostic tool to verify all channels can access external networks through the proxy:

```bash
agent-reach doctor

```

Each channel test receives the `HTTP_PROXY` and `HTTPS_PROXY` environment variables automatically.

## Summary

- **Storage Location**: Proxy credentials are stored in `~/.agent-reach/config.yaml` managed by [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), with automatic masking of sensitive values.
- **Dual Keys**: The system writes to both `proxy` (current standard) and `bilibili_proxy` (legacy) for compatibility.
- **CLI Commands**: Use `agent-reach install --proxy <url>` during setup or `agent-reach configure proxy <url>` for updates.
- **Runtime Injection**: Before executing external tools, Agent Reach copies the environment, adds `HTTP_PROXY` and `HTTPS_PROXY` from the config, and passes this to subprocesses.
- **Dry-Run Support**: The `--dry-run` flag allows testing configuration changes without persisting them.

## Frequently Asked Questions

### Where does Agent Reach store proxy credentials?

Agent Reach stores proxy credentials in the YAML configuration file 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) handles persistence and automatically masks proxy values when displaying configuration to prevent credential exposure.

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

The `bilibili_proxy` key exists for backward compatibility with older versions of Agent Reach that stored proxy settings under that specific name. Modern implementations use the `proxy` key, but the CLI synchronizes both values to ensure legacy channel implementations continue functioning while newer code uses the standard key.

### Can I update the proxy configuration without reinstalling Agent Reach?

Yes, use the `agent-reach configure proxy <url>` command to update proxy settings at any time. This command writes to [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) updates both configuration keys immediately without requiring reinstallation or affecting other settings.

### How does Agent Reach handle authenticated proxies?

Agent Reach stores the complete proxy URL including authentication credentials (e.g., `http://user:pass@proxy.example.com:3128`) in the configuration file. At runtime, the full URL is exported to `HTTP_PROXY` and `HTTPS_PROXY` environment variables, allowing underlying tools to handle the authentication protocol according to standard proxy conventions.