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

> Configure Agent-Reach proxy settings for restricted networks. Learn to use the --proxy flag or configure proxy command to set HTTP_PROXY and HTTPS_PROXY.

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

---

**To configure a proxy for Agent-Reach, use the `--proxy` flag during installation or the `configure proxy` sub-command, which stores the URL in `~/.agent-reach/config.yaml` and exports it as `HTTP_PROXY`/`HTTPS_PROXY` for downstream agent commands.**

Agent-Reach is an open-source automation framework that enables agents to interact with external platforms like YouTube and Bilibili. When operating behind corporate firewalls or restricted networks, you must configure a **generic HTTP(S) proxy** to allow these agents to reach external APIs and download resources. The proxy configuration is handled natively by the CLI and applied transparently to all subprocesses invoked by agents.

## Installation-Time Proxy Configuration

### Using the --proxy Flag

During initial setup, pass the proxy URL directly to the installer. This captures the credentials and endpoint in a single command.

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

```

The CLI parses this argument in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) around lines 68-71, validating the URL format before passing it to the configuration layer. For a dry run to preview the configuration without applying changes, append the `--dry-run` flag:

```bash
agent-reach install --dry-run --proxy="http://proxy:3128"

```

### Persistent Storage in config.yaml

Upon installation, Agent-Reach writes the proxy value to `~/.agent-reach/config.yaml` with restricted file permissions. The storage operation occurs in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) at lines 36-44, utilizing the `Config` class to ensure sensitive values are masked in logs.

## Post-Installation Proxy Management

### Setting or Updating the Proxy

If the network environment changes or you skipped the flag during installation, use the dedicated sub-command to persist a new proxy URL:

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

```

This command is implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) between lines 81-86 and provides a shortcut to update the configuration without re-running the full installer.

### Verifying and Removing Proxy Settings

To inspect the currently stored proxy value, invoke the command without arguments:

```bash
agent-reach configure proxy

```

This prints the saved URL to stdout, which you can capture into environment variables for manual debugging:

```bash
export HTTP_PROXY="$(agent-reach configure proxy)"
yt-dlp --proxy "$HTTP_PROXY" "https://youtu.be/example"

```

To clear the configuration and disable proxy routing entirely, pass an empty string:

```bash
agent-reach configure proxy ""

```

## How the Proxy is Applied to Agent Operations

When an agent executes a command requiring network access (such as `yt-dlp` for YouTube subtitles or `feedparser` for RSS feeds), Agent-Reach retrieves the proxy setting via `Config.get("proxy")` and injects it into the subprocess environment as `HTTP_PROXY` and `HTTPS_PROXY`. This mechanism allows external tools to traverse the restricted network transparently without code modifications.

Channels like [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) demonstrate this pattern by syncing the global `proxy` value into tool-specific arguments (e.g., passing `--proxy` to `yt-dlp`).

## Code Implementation Details

### CLI Parsing Logic in cli.py

The **CLI installer** handles argument parsing for the `--proxy` flag and the `configure proxy` sub-command. In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), lines 68-71 define the argument structure, while lines 36-44 handle the persistence logic that writes the value to disk.

### Configuration Manager in config.py

The **Config class** in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 86-90) manages the YAML configuration file. It provides `Config.set("proxy", value)` for writes and `Config.get("proxy")` for reads, ensuring that proxy credentials are stored securely and accessed consistently across the application.

### Directory Permissions in paths.py

Before writing the configuration, Agent-Reach creates the user config directory using `make_private_dir` from [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py). This ensures that `~/.agent-reach/` and its contents are created with strict permissions to prevent credential leakage.

### Channel Integration

Each channel implementation retrieves the proxy configuration independently. For example, [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) accesses the proxy via the `Config` singleton and forwards it to any underlying HTTP clients or command-line tools, maintaining consistent network behavior across all agent activities.

## Summary

- **Set during install**: Use `agent-reach install --proxy="http://..."` to configure the proxy initially.
- **Update anytime**: Use `agent-reach configure proxy "http://..."` to change settings without reinstalling.
- **Storage location**: Values are saved in `~/.agent-reach/config.yaml` via the `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).
- **Transparent application**: The proxy is exported as `HTTP_PROXY`/`HTTPS_PROXY` environment variables for all agent subprocesses.
- **Security**: Configuration directories are created with restricted permissions via `make_private_dir` in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py).

## Frequently Asked Questions

### How do I check if Agent-Reach is using my configured proxy?

Run `agent-reach configure proxy` without arguments to print the stored URL. Additionally, you can verify environment variable injection by running an agent in verbose mode and inspecting the subprocess environment, or by checking network logs on your proxy server for requests originating from Agent-Reach tools like `yt-dlp`.

### Can I use an authenticated proxy with special characters in the password?

Yes. When passing the URL via `--proxy` or `configure proxy`, ensure special characters in the username or password are URL-encoded (e.g., `@` becomes `%40`). The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) stores the string literal and passes it directly to subprocesses, preserving your credentials as provided.

### Why does Agent-Reach store the proxy in a YAML file instead of using system environment variables?

Storing the proxy in `~/.agent-reach/config.yaml` provides persistence across terminal sessions and reboots. While you can manually export `HTTP_PROXY` in your shell, the YAML approach ensures that agents launched via cron jobs, systemd services, or IDEs automatically inherit the correct proxy settings without requiring global system configuration changes.

### Where is the proxy configuration file located, and is it secure?

The configuration resides at `~/.agent-reach/config.yaml`. The directory is created by `make_private_dir` in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) with mode `0o700` (owner read/write/execute only), ensuring other users on the system cannot read your proxy credentials or other sensitive settings.