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

> Learn how to configure proxy settings for restricted networks in Agent Reach. Easily set up proxy flags for firewall access and ensure seamless agent communication.

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

---

**Agent Reach supports corporate firewalls by accepting a `--proxy` flag during installation or via the `configure proxy` command, which stores the URL in `~/.agent-reach/config.yaml` and exports it as `HTTP_PROXY`/`HTTPS_PROXY` for all downstream agent subprocesses.**

Agent Reach is an open-source automation framework that enables AI agents to interact with external platforms like YouTube and Bilibili. When operating behind corporate firewalls or restricted networks, you must configure proxy settings to ensure agents can reach external APIs and download resources. According to the Panniantong/Agent-Reach source code, the tool implements a centralized proxy configuration system that automatically injects credentials into subprocess environments.

## Understanding the Proxy Architecture

The proxy implementation spans two core components in the Agent Reach codebase.

### CLI Configuration Layer

The command-line interface in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) handles proxy arguments during installation and provides a dedicated configuration sub-command. The parsing logic resides at lines 68-71, where the `--proxy` flag is extracted from the command arguments. The persistence logic at lines 36-44 writes the validated URL to the configuration file. Additionally, lines 81-86 implement the `configure proxy` sub-command, which allows you to update settings after the initial installation.

### Configuration Persistence Layer

The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) manages persistent storage in `~/.agent-reach/config.yaml`. The implementation at lines 86-90 provides `Config.set("proxy", ...)` and `Config.get("proxy")` methods that securely handle the proxy URL. The configuration directory is created with restricted permissions using `make_private_dir` from [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py), ensuring that credentials are not accessible to other system users.

## Configuring Proxy Settings Step-by-Step

### Initial Installation with Proxy

During the initial setup, pass the proxy URL directly to the install command:

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

```

The `--proxy` flag accepts standard HTTP(S) proxy URLs including authentication credentials. The CLI parser in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) processes this value and immediately persists it to the configuration file via the `Config` class.

### Updating Proxy Settings Post-Installation

To modify or add a proxy after installation, use the dedicated configuration command:

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

```

This command updates the stored value without requiring a full reinstall. To view the currently configured proxy without changing it, omit the value argument:

```bash
agent-reach configure proxy

```

### Removing Proxy Configuration

Clear the proxy setting by passing an empty string:

```bash
agent-reach configure proxy ""

```

This removes the key from `~/.agent-reach/config.yaml` and prevents environment variable injection in subsequent agent runs.

## How Agent Reach Applies Proxy Settings

When agents execute commands requiring network access, Agent Reach retrieves the proxy URL via `Config.get("proxy")` from [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) and exports it as `HTTP_PROXY` and `HTTPS_PROXY` environment variables. This mechanism ensures that downstream tools like `yt-dlp`, `feedparser`, or `curl` traverse the restricted network transparently without requiring manual configuration for each subprocess.

Channel implementations demonstrate this pattern concretely. For example, in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py), the configuration retrieves the global proxy value and passes it to the underlying download tool. This architecture ensures consistent proxy application across all supported platforms.

For manual verification or ad-hoc commands, you can export the stored proxy directly from the configuration:

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

```

## Summary

- **Agent Reach stores proxy URLs** 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) (lines 86-90).
- **Use `--proxy` during installation** or `agent-reach configure proxy` afterward to set credentials.
- **Proxy values are automatically exported** as `HTTP_PROXY` and `HTTPS_PROXY` for all agent subprocesses.
- **Channel implementations** like [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) retrieve settings via `Config.get("proxy")`.
- **Remove proxy settings** by passing an empty string to the configure command.

## Frequently Asked Questions

### Where does Agent Reach store proxy credentials?

Agent Reach persists proxy settings in the YAML configuration file 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) (lines 86-90) handles read/write operations with `Config.set("proxy", ...)` and `Config.get("proxy")`, while [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) ensures the directory is created with restricted permissions using `make_private_dir`.

### Does Agent Reach support authenticated proxies?

Yes. The proxy URL format supports standard HTTP(S) authentication syntax: `http://username:password@proxy.host:port`. Both the CLI parser in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 68-71) and the configuration manager accept URLs containing credentials, which are then injected into subprocess environments.

### How do I troubleshoot proxy connectivity issues?

First, verify the stored configuration by running `agent-reach configure proxy` without arguments to confirm the URL is correct. Test connectivity by manually exporting the proxy to your shell environment with `export HTTP_PROXY="$(agent-reach configure proxy)"` and attempting a direct request with tools like `curl`. Check that your proxy supports the HTTPS connections required by Agent Reach channels.

### Can I use different proxies for different channels?

Currently, Agent Reach implements a global proxy configuration. The `Config.get("proxy")` method returns a single value used across all channels, as seen in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) and other channel implementations. For channel-specific routing, you must configure your proxy server to handle destination-based routing or temporarily update the global setting before running specific agents.