# Configure network proxy for Agent Reach in restricted environments

> Learn to configure network proxy for Agent Reach in restricted environments. Seamlessly route API calls via proxy by setting the URL in config.yaml and exporting environment variables.

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

---

**Agent Reach routes all external API calls through a network proxy by persisting the proxy URL in `~/.agent-reach/config.yaml` and automatically injecting `HTTP_PROXY` and `HTTPS_PROXY` into subprocess environments whenever tools access Twitter, Reddit, or YouTube.**

Agent Reach, maintained in the `Panniantong/Agent-Reach` repository, orchestrates external platform interactions through various CLI tools. When running in restricted network environments, configuring proxy support ensures that underlying fetch operations can traverse firewalls without manual environment variable management.

## Where Agent Reach stores proxy credentials

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, automatically masking values when displaying configuration to prevent credential leakage. The proxy URL is persisted in the user's home directory at `~/.agent-reach/config.yaml` alongside other settings.

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

```

## Setting the proxy during installation

During initial setup, the `agent-reach install` command accepts a `--proxy` flag that captures the proxy URL and writes it to both the modern `proxy` key and the legacy `bilibili_proxy` key for backward compatibility.

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

```

You can perform a dry‑run to verify what would be saved:

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

```

## Updating proxy settings after installation

To configure or change the proxy without reinstalling, use the `configure proxy` sub‑command. The CLI writes the values to the config file, and agents read these settings back at runtime to populate environment variables.

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

```

Example command:

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

```

## Runtime proxy injection

When Agent Reach spawns subprocesses to interact with external platforms (e.g., calling `twitter-cli` or `rdt-cli`), it reads the stored proxy from `~/.agent-reach/config.yaml` and exports standard `HTTP_PROXY` and `HTTPS_PROXY` variables into the subprocess environment, as implemented in [`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 pattern ensures that any command executed on the host inherits the proxy settings automatically.

## Legacy key synchronization

Agent Reach maintains backward compatibility by writing the proxy URL to both the `proxy` key (current) and `bilibili_proxy` key (legacy). Older versions of the codebase stored the proxy exclusively under `bilibili_proxy`. Keeping them synchronized ensures that legacy channel implementations continue to function while newer code migrates to the standardized key.

## Practical configuration examples

1. **Install with a proxy in one step**

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

2. **Add or change the proxy after installation**

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

3. **Verify the saved configuration**

   ```bash
   cat ~/.agent-reach/config.yaml
   # → proxy: http://user:pass@proxy.example.com:3128

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

   ```

4. **Validate connectivity through the proxy**

   ```bash
   agent-reach doctor
   ```

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

## Summary

- Agent Reach stores proxy credentials in `~/.agent-reach/config.yaml`, masking them as sensitive values.
- Use `agent-reach install --proxy <url>` during setup or `agent-reach configure proxy <url>` for updates.
- The system writes the proxy to both `proxy` and `bilibili_proxy` keys for backward compatibility.
- At runtime, Agent Reach injects `HTTP_PROXY` and `HTTPS_PROXY` into subprocess environments before invoking external tools like `twitter-cli` or `rdt-cli`.

## Frequently Asked Questions

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

Agent Reach persists the proxy URL in `~/.agent-reach/config.yaml` under the keys `proxy` and `bilibili_proxy`. The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) treats these as sensitive values and masks them when displaying configuration to prevent credential leakage.

### How do I update the proxy URL after installation?

Run the `agent-reach configure proxy <url>` command to update the stored proxy without reinstalling. The CLI writes the new value to the configuration file, and subsequent agent operations will automatically export the updated `HTTP_PROXY` and `HTTPS_PROXY` variables to subprocesses.

### Does Agent Reach support authenticated proxies?

Yes, the proxy configuration accepts standard URL formats including credentials, such as `http://user:pass@proxy.example.com:3128`. These values are stored securely in the config file and injected into the environment variables that upstream CLI tools respect.

### Why are there two proxy keys in the config file?

The `bilibili_proxy` key exists for backward compatibility with older versions of Agent Reach that stored the proxy exclusively under that name. Modern code uses the `proxy` key, but the CLI synchronizes both keys during any write operation to ensure legacy channel implementations continue to function correctly.