# How to Set Up Agent Reach Proxy for Restricted Networks: Complete Configuration Guide

> Learn to set up Agent Reach proxy for restricted networks easily. This configuration guide details seamless restricted network access for the Agent Reach repository.

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

---

**Agent Reach supports HTTP(S) proxy configuration via the `--proxy` flag during installation or the `configure proxy` command, storing credentials in `~/.agent-reach/config.yaml` and injecting them into subprocess environment variables for seamless restricted network access.**

Agent Reach is an open-source automation framework that enables AI agents to interact with external platforms, but corporate firewalls and restricted networks often block these connections. Setting up a proxy for Agent Reach ensures that agent subprocesses—whether downloading YouTube content with `yt-dlp` or fetching RSS feeds—can traverse network restrictions transparently. This guide covers the complete proxy configuration based on the actual implementation in the `Panniantong/Agent-Reach` repository.

## How Agent Reach Handles Proxy Configuration

The proxy system operates through two core components: the **CLI interface** that captures user input and the **configuration manager** that persists settings securely.

### CLI Argument Parsing

In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the installation command parses the `--proxy` flag between lines 68-71, accepting standard HTTP(S) proxy URLs including authentication credentials. The `configure proxy` sub-command at lines 81-86 provides a dedicated interface for updating proxy settings after initial setup, writing values via the `Config` class.

### Secure Configuration Storage

The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 86-90) handles persistent storage in `~/.agent-reach/config.yaml`. The implementation uses [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) to create the configuration directory with restricted permissions via `make_private_dir`, ensuring that proxy credentials remain accessible only to the file owner.

## Installing Agent Reach Behind a Corporate Proxy

Configure the proxy during initial setup to ensure all subsequent agent operations respect network restrictions.

Use the `--proxy` flag with the install command:

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

```

For testing the configuration without applying changes, add the `--dry-run` flag:

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

```

The CLI validates the URL format and immediately stores the value using `Config.set("proxy", url)`, persisting to your user-specific configuration file with safe file permissions.

## Updating and Verifying Proxy Settings

After installation, modify the proxy configuration without reinstalling the entire framework.

Set or update the proxy using the dedicated sub-command:

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

```

To view the currently stored proxy value for debugging:

```bash
agent-reach configure proxy

```

This retrieves the value via `Config.get("proxy")` and outputs the URL, helping verify that authentication credentials persisted correctly.

Remove the proxy configuration entirely by passing an empty string:

```bash
agent-reach configure proxy ""

```

## Runtime Proxy Injection for Agent Commands

When agents execute external commands requiring network access, Agent Reach retrieves the stored proxy from `~/.agent-reach/config.yaml` and exports it as `HTTP_PROXY` and `HTTPS_PROXY` environment variables for child subprocesses.

Channel implementations demonstrate this pattern consistently. For example, in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py), the code accesses the proxy via `Config.get("proxy")` and passes it to underlying tools. External utilities like `yt-dlp` receive the proxy through their native `--proxy` arguments, while standard HTTP clients use the injected environment variables automatically.

To manually invoke a tool with the configured proxy:

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

```

## Summary

- **Agent Reach** supports HTTP(S) proxies via the `--proxy` installation flag and `configure proxy` command, storing values in `~/.agent-reach/config.yaml`.
- The **CLI parser** in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 68-71) handles proxy URL validation during installation, while lines 81-86 manage post-install updates.
- The **Config class** in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 86-90) provides secure storage with restricted file permissions via [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py).
- Agents automatically inject the configured proxy into subprocess **environment variables**, enabling restricted network traversal without code modifications.

## Frequently Asked Questions

### What proxy formats does Agent Reach support?

Agent Reach accepts standard HTTP and HTTPS proxy URLs, including optional authentication credentials in the format `http://user:pass@host:port` or `https://host:port`. The CLI parser in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) validates these URLs before storing them in the configuration file.

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

The proxy URL is saved in `~/.agent-reach/config.yaml` under the `proxy` key. The configuration directory is created with restricted permissions using `make_private_dir` in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) to protect credentials containing passwords.

### Do I need to restart agents after changing the proxy?

No restart is required. Agent Reach reads the proxy configuration fresh from `~/.agent-reach/config.yaml` using `Config.get("proxy")` each time it spawns a subprocess. Changes made via `agent-reach configure proxy` take effect immediately for the next agent operation.

### How do I troubleshoot proxy connectivity issues?

Verify the stored configuration by running `agent-reach configure proxy` without arguments to echo the current URL. Check that the proxy format includes the correct scheme and port number. For authenticated proxies, ensure special characters in passwords are properly URL-encoded.