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

> Configure a proxy for Agent-Reach in restricted networks. Learn how Agent-Reach automatically exports proxy settings for secure outbound traffic in `config.yaml`.

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

---

**Agent-Reach stores proxy settings in `~/.agent-reach/config.yaml` and automatically exports them as `HTTP_PROXY` and `HTTPS_PROXY` environment variables for all outbound channel traffic.**

When operating behind corporate firewalls or regional restrictions, Agent-Reach requires explicit proxy configuration to access external platforms like Twitter, Reddit, and YouTube according to the Panniantong/Agent-Reach source code. The tool persists these settings in a per-user YAML configuration file managed by the `Config` class and transparently applies them to downstream binaries. Understanding how to configure a proxy for restricted network environments ensures seamless data collection even in server or VPS deployments with strict egress rules.

## Configuration Storage and the Config Class

Agent-Reach centralizes all user-defined settings in **`~/.agent-reach/config.yaml`**, parsed and persisted by the `Config` class defined in [[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). When you supply a proxy URL, the system writes it to two keys in this file:

- **`proxy`** — The primary key used by current channel implementations
- **`bilibili_proxy`** — A legacy key maintained for backward compatibility

The `Config.get()` method (lines 69-77) implements a fallback hierarchy: it first checks the in-memory dictionary, then attempts to read an uppercase environment variable of the same name. This design allows temporary overrides via `HTTP_PROXY` or `HTTPS_PROXY` if you need to bypass the saved configuration for a single session.

## CLI Methods for Proxy Configuration

The [[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) module provides two distinct entry points for proxy management depending on whether you are performing a fresh install or updating an existing configuration.

### Setting Proxy During Installation

During the initial setup, pass the **`--proxy`** flag to the install command (lines 68-70). The CLI validates the URL format and immediately persists it via `config.set("proxy", args.proxy)` and `config.set("bilibili_proxy", args.proxy)` (lines 228-236).

```bash
agent-reach install --proxy http://user:pass@203.0.113.10:3128

```

This single command creates the configuration directory, writes the YAML file, and ensures all future channel invocations route through the specified proxy.

### Updating Proxy After Installation

If you need to change or add a proxy to an existing installation, use the dedicated configure subcommand. The handler at lines 1040-1046 detects when `args.key == "proxy"` and triggers the same persistence logic as the installer.

```bash
agent-reach configure proxy http://user:pass@203.0.113.10:3128

```

Both methods accept standard proxy URLs including protocol, authentication credentials, IP address, and port.

## Runtime Proxy Application

At runtime, Agent-Reach does not manually route HTTP requests through a custom socket layer. Instead, it relies on the standard Unix environment variable convention. Before invoking upstream tools like `twitter-cli`, `rdt-cli`, or `yt-dlp`, the application ensures that `HTTP_PROXY` and `HTTPS_PROXY` are set to the value retrieved from `Config.get("proxy")`.

This approach offers two advantages for restricted network environments:

1. **Transparency** — Downstream binaries automatically detect and use the proxy without requiring additional command-line flags
2. **Compatibility** — Any subprocess spawned by Agent-Reach inherits the environment, ensuring consistency across Python, Node.js, or Go-based channel implementations

The export happens implicitly when channels initialize their network stacks, guaranteeing that Reddit, Twitter, and YouTube requests traverse the proxy even in headless server deployments.

## Verifying and Testing Your Proxy Configuration

To confirm that your proxy settings were saved correctly, inspect the configuration file directly:

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

```

You should see output similar to:

```yaml
proxy: http://user:pass@203.0.113.10:3128
bilibili_proxy: http://user:pass@203.0.113.10:3128

```

You can also verify programmatically using the `Config` class in a Python script:

```python
from agent_reach.config import Config
import os

cfg = Config()
proxy = cfg.get("proxy")

if proxy:
    os.environ["HTTP_PROXY"] = proxy
    os.environ["HTTPS_PROXY"] = proxy
    print(f"Proxy configured: {proxy}")
else:
    print("No proxy configured")

```

This snippet mirrors the internal behavior of Agent-Reach channels, allowing you to test connectivity before running full data collection tasks.

## Summary

- **Storage Location**: Proxy settings reside in `~/.agent-reach/config.yaml` under the `proxy` key (with `bilibili_proxy` as legacy support)
- **CLI Interfaces**: Use `agent-reach install --proxy <URL>` for initial setup or `agent-reach configure proxy <URL>` for updates
- **Runtime Mechanism**: The `Config` class exports `HTTP_PROXY` and `HTTPS_PROXY` environment variables for automatic downstream tool consumption
- **Override Capability**: `Config.get()` checks environment variables first, enabling temporary overrides without modifying the YAML file
- **Implementation Files**: Core logic resides in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (persistence) and [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (argument parsing and commands)

## Frequently Asked Questions

### What file does Agent-Reach use to store proxy settings?

Agent-Reach stores all proxy configuration in **`~/.agent-reach/config.yaml`**, a per-user YAML file managed by the `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). This file contains the `proxy` key and the legacy `bilibili_proxy` key.

### Can I override the configured proxy using environment variables?

Yes. The `Config.get()` method implements a fallback chain: it checks the in-memory configuration dictionary first, then looks for an uppercase environment variable of the same name. Setting `HTTP_PROXY` or `HTTPS_PROXY` in your shell will override the value saved in the YAML file for that session.

### Does Agent-Reach support authenticated proxies?

Yes. The CLI accepts full proxy URLs including authentication credentials in the standard format `http://user:pass@ip:port`. This URL is stored verbatim in the configuration file and exported as the `HTTP_PROXY`/`HTTPS_PROXY` values, which downstream tools parse for authentication.

### Which network channels respect the proxy configuration?

All channels that invoke external CLI tools respect the proxy configuration, including those interfacing with Twitter (`twitter-cli`), Reddit (`rdt-cli`), and YouTube (`yt-dlp`). Because Agent-Reach exports `HTTP_PROXY` and `HTTPS_PROXY` globally before spawning subprocesses, any tool that respects standard environment variable conventions will route traffic through the configured proxy automatically.