# How to Configure a Proxy for Agent Reach in Restricted Networks

> Configure a proxy for Agent Reach in restricted networks. Learn how to set up HTTP_PROXY and HTTPS_PROXY environment variables and store the proxy URL in config.yaml for seamless external API calls.

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

---

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

Agent Reach is designed to operate behind corporate firewalls and restrictive network environments by supporting standard proxy configurations. When you configure a proxy for Agent Reach, the CLI stores your credentials in a local configuration file and automatically applies them whenever invoking external tools like Twitter or Reddit clients. This ensures seamless connectivity even when direct internet access is blocked.

## Where Agent Reach Stores Proxy Configuration

The proxy settings persist in the user's home directory within the Agent Reach configuration file.

### The Config File Location

Agent Reach maintains its configuration at `~/.agent-reach/config.yaml`. This file contains the `proxy` key alongside other sensitive credentials required for channel operations.

### Sensitive Value Masking

In [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the `Config` class automatically masks any configuration key containing "proxy" when displaying settings to prevent credential leakage. The source code explicitly checks for proxy-related strings:

```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 with embedded authentication tokens never appear in logs or terminal output.

## Setting the Proxy During Installation

You can configure the proxy immediately when installing Agent Reach using the `--proxy` flag. This captures the proxy URL and writes it to the configuration file before any network operations begin.

According to the install handler in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the CLI accepts the proxy URL and persists it to both the current `proxy` key and the legacy `bilibili_proxy` key:

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

```

Run this command during initial setup:

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

```

This single command ensures that all subsequent channel operations route through your specified proxy.

## Updating the Proxy After Installation

Network environments change, and Agent Reach allows you to update proxy settings without reinstalling the entire tool.

### Using the Configure Command

The `configure proxy` sub-command updates the stored proxy URL in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py). This writes the new value to the configuration file and maintains synchronization between the modern `proxy` key and the legacy `bilibili_proxy` key:

```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 at any time:

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

```

The change takes effect immediately for the next channel operation.

## How the Proxy is Applied at Runtime

Agent Reach does not use the proxy for its own internal logic. Instead, it reads the stored proxy value and injects it into the environment of any subprocess that requires external network access.

Before invoking external binaries like `twitter-cli` or `rdt-cli`, the runtime executes code similar to this pattern found throughout the codebase:

```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 approach ensures that upstream tools receive the standard `HTTP_PROXY` and `HTTPS_PROXY` environment variables they expect, enabling seamless operation behind corporate firewalls without modifying individual channel implementations.

## Understanding the Legacy bilibili_proxy Key

Older versions of Agent Reach stored proxy settings exclusively under the `bilibili_proxy` key. The current codebase maintains both keys simultaneously to ensure backward compatibility with legacy channel implementations while supporting modern proxy-aware code.

When you set or update the proxy using either the `--proxy` flag or the `configure proxy` command, Agent Reach writes the same URL to both the `proxy` and `bilibili_proxy` keys. This synchronization prevents configuration drift and ensures that older Bilibili channel code continues to function correctly while newer implementations use the standardized `proxy` key.

## Complete Configuration Examples

### 1. Install with Proxy in One Step

Configure the proxy during initial installation to ensure all dependencies are downloaded through your network gateway:

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

```

### 2. Update Proxy After Installation

Change the proxy URL without reinstalling:

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

```

### 3. Verify the Configuration

Inspect the configuration file to confirm both keys are set:

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

```

You should see output similar to:

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

```

### 4. Test with Dry Run

Preview what the installer would do without making changes:

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

```

This outputs:

```

[dry-run] Would save network proxy

```

### 5. Runtime Verification

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

```bash
agent-reach doctor

```

Each channel test inherits the `HTTP_PROXY` and `HTTPS_PROXY` variables from the configuration.

## Summary

- **Configuration location**: Agent Reach stores proxy settings in `~/.agent-reach/config.yaml` under the `proxy` key.
- **Dual key strategy**: The tool synchronizes both `proxy` and `bilibili_proxy` keys for backward compatibility.
- **CLI commands**: Use `agent-reach install --proxy` for initial setup or `agent-reach configure proxy` for updates.
- **Runtime behavior**: The CLI injects `HTTP_PROXY` and `HTTPS_PROXY` environment variables into subprocesses before invoking external tools.
- **Security**: The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) masks proxy URLs containing credentials when displaying configuration.

## Frequently Asked Questions

### Where does Agent Reach store the proxy configuration?

Agent Reach stores the proxy URL in the YAML configuration file located 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) manages this file, automatically masking sensitive values like passwords when displaying settings. Both the modern `proxy` key and the legacy `bilibili_proxy` key contain the same URL to ensure compatibility across different channel implementations.

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

The `bilibili_proxy` key exists for backward compatibility with older versions of Agent Reach that specifically referenced this key for Bilibili channel operations. Current versions write the proxy URL to both keys simultaneously when you use the `--proxy` flag or `configure proxy` command. This dual-key strategy ensures that legacy code continues to function while newer implementations migrate to the standardized `proxy` key.

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

No restart is required. Agent Reach reads the configuration file from `~/.agent-reach/config.yaml` at runtime whenever it invokes external tools. When you run `agent-reach configure proxy`, the change takes effect immediately for the next channel operation. The CLI reads the current proxy value and injects it into the environment of any subprocess it launches.

### How do I verify that the proxy is working correctly?

Run `agent-reach doctor` to execute health checks across all configured channels. This command invokes external tools like `twitter-cli` and `rdt-cli` with the `HTTP_PROXY` and `HTTPS_PROXY` environment variables set from your configuration. If the channels can reach their respective APIs, the proxy is functioning correctly. You can also inspect the configuration file directly with `cat ~/.agent-reach/config.yaml` to confirm the proxy URL is stored.