# Agent Reach Proxy Configuration for Restricted Networks: A Complete Guide

> Configure Agent Reach for restricted networks with our comprehensive guide. Learn to set up HTTP(S) proxy settings and overcome corporate firewall challenges seamlessly. Works with your existing setup.

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

---

**Agent Reach supports corporate firewalls and restricted networks by accepting a generic HTTP(S) proxy URL that it persists to `~/.agent-reach/config.yaml` and automatically injects into downstream agent subprocesses via the `HTTP_PROXY` and `HTTPS_PROXY` environment variables.**

Agent Reach is an open-source automation framework that frequently operates in enterprise environments with strict egress controls. When running in restricted networks, you must configure proxy settings so that agent tools like `yt-dlp` and `feedparser` can reach external APIs. This guide covers the proxy architecture, CLI commands, and configuration file mechanics based on the latest source code in the `Panniantong/Agent-Reach` repository.

## How Agent Reach Handles Proxy Configuration

Agent Reach implements a centralized proxy management system that bridges CLI input and runtime environment variables.

### Architecture Overview

The proxy handling spans two core components:

1. **CLI Interface** – Parses the `--proxy` flag during installation and the `configure proxy` sub-command for updates. The argument parsing logic resides in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) around lines 68-71, while the saving logic is implemented at lines 36-44.
2. **Configuration Manager** – Persists settings securely in `~/.agent-reach/config.yaml` with restricted permissions. The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 86-90) provides `Config.set("proxy", ...)` for writing and `Config.get("proxy")` for retrieval, with sensitive values masked in logs.

When an agent triggers a subprocess that requires network access—such as `yt-dlp` for YouTube subtitles or `feedparser` for RSS feeds—Agent Reach automatically exports the stored proxy URL as `HTTP_PROXY` and `HTTPS_PROXY` environment variables, allowing seamless traversal of restricted networks without code changes.

## Setting the Proxy During Installation

Configure a proxy at install time using the `--proxy` flag. This is the most efficient method for initial setup behind corporate firewalls.

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

```

The CLI validates the URL format and immediately persists the value to the config file. For a dry run to verify the configuration without applying changes:

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

```

The parsing logic in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) handles the argument, while [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) ensures the configuration directory is created with safe permissions via `make_private_dir`.

## Updating Proxy Settings After Installation

Use the `configure proxy` sub-command to modify or inspect proxy settings without reinstalling.

**Set or update a proxy:**

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

```

**Display the currently stored proxy:**

```bash
agent-reach configure proxy

```

**Remove the proxy configuration:**

```bash
agent-reach configure proxy ""

```

Each command invokes `Config.set("proxy", value)` or `Config.get("proxy")` from [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), ensuring the YAML file remains the single source of truth.

## Proxy Propagation to Channel Executions

Channel implementations automatically inherit proxy settings. For example, in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py), the system retrieves the proxy via `Config.get("proxy")` and passes it to underlying tools. This pattern is consistent across all channel files—agents invoke external commands with the proxy environment variables pre-populated, so tools like `curl` or `yt-dlp` receive the `--proxy` flag or `HTTP_PROXY` variable transparently.

If you need to manually invoke a downstream tool with the same proxy:

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

```

## Practical Configuration Examples

**One-shot installation with authentication:**

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

```

**Post-install reconfiguration:**

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

```

**Verification and debugging:**

```bash
agent-reach configure proxy  # Prints current value

```

**Clearing credentials (empty string):**

```bash
agent-reach configure proxy ""

```

## Summary

- **Configuration storage**: Proxy URLs are stored in `~/.agent-reach/config.yaml` with restricted file permissions.
- **CLI entry points**: Use `--proxy` during installation or `configure proxy` afterward; both update the same config key via [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).
- **Runtime injection**: Subprocesses receive `HTTP_PROXY` and `HTTPS_PROXY` automatically, enabling restricted network access for tools like `yt-dlp` and `feedparser`.
- **API methods**: The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) handles persistence through `Config.set("proxy", ...)` and `Config.get("proxy")`.

## Frequently Asked Questions

### What proxy formats does Agent Reach support?

Agent Reach accepts standard HTTP(S) proxy URLs with optional authentication, following the format `http://user:pass@host:port` or `https://host:port`. The URL is stored as a string and exported directly to environment variables without modification.

### Where is the proxy configuration stored?

The configuration is saved in `~/.agent-reach/config.yaml`. The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) manages this file, using `make_private_dir` from [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) to ensure the directory has safe permissions (typically `0o700`) before writing sensitive credentials.

### How do I remove a configured proxy?

Pass an empty string to the configure command: `agent-reach configure proxy ""`. This clears the stored value, and subsequent agent commands will run without proxy environment variables unless your shell already exports them.

### Do all channels automatically use the proxy?

Yes. All channel implementations retrieve the proxy via `Config.get("proxy")` and forward it to underlying tools. For example, [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) syncs the global proxy setting with channel-specific logic, ensuring consistent network access across all agent operations.