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

> Configure a network proxy for Agent Reach in restricted networks using the --proxy flag or configure proxy command. Learn how to ensure agent connectivity.

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

---

**Agent Reach supports HTTP(S) proxy configuration via the `--proxy` flag during installation or the `configure proxy` command, storing the URL in `~/.agent-reach/config.yaml` and injecting it as environment variables for downstream agent subprocesses.**

When operating behind corporate firewalls or restricted networks, Agent Reach (from the [Panniantong/Agent-Reach](https://github.com/Panniantong/Agent-Reach) repository) allows you to configure a generic HTTP(S) proxy that automatically applies to all external network requests made by agents. The proxy URL is persisted in a local configuration file and exported as `HTTP_PROXY` and `HTTPS_PROXY` environment variables whenever agents invoke external commands like `yt-dlp` or `feedparser`.

## Installation-Time Proxy Configuration

### Using the --proxy Flag

You can configure a proxy immediately when installing Agent Reach by passing the `--proxy` flag to the `install` command. The CLI parses this argument in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 68-71) and persists it to your configuration file (lines 36-44).

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

```

This command stores the proxy credentials securely in `~/.agent-reach/config.yaml` with restricted file permissions, ensuring subsequent agent operations automatically traverse the network restriction.

## Post-Installation Proxy Management

If you need to add or modify a proxy after the initial setup, Agent Reach provides a dedicated configuration sub-command.

### Setting or Updating the Proxy

The `configure proxy` sub-command (implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) lines 81-86) updates the stored proxy value without requiring a full reinstallation:

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

```

### Verifying the Current Configuration

To inspect the currently stored proxy value without exposing credentials in shell history, run the command without arguments:

```bash
agent-reach configure proxy

```

This retrieves the value using `Config.get("proxy")` as implemented in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 86-90).

### Removing the Proxy

To clear the proxy configuration and return to direct network connections:

```bash
agent-reach configure proxy ""

```

## How the Proxy Configuration Works Internally

Understanding the architecture helps troubleshoot connectivity issues in restricted environments.

### CLI Parsing and Persistence

When you specify `--proxy`, the CLI installer in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) validates the URL format and writes it to persistent storage. The configuration manager handles the actual file operations, using `Config.set("proxy", value)` to update the YAML structure while maintaining safe file permissions via `make_private_dir` in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py).

### Configuration Storage

The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) manages the `~/.agent-reach/config.yaml` file. Sensitive values like proxy credentials are stored with appropriate file system permissions, and the proxy key is accessed consistently across the application via `Config.get("proxy")`.

### Runtime Injection

When agents execute commands requiring external network access, Agent Reach retrieves the proxy setting and injects it into the subprocess environment. For example, in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) and other channel implementations, the tool forwards the proxy to underlying utilities like `yt-dlp` using the `--proxy` flag or via the `HTTP_PROXY` environment variable, allowing seamless traversal of restricted networks.

## Practical Usage Examples

### Passing Proxy to Manual Tool Invocations

For manual debugging or when invoking tools directly outside of Agent Reach, extract the stored proxy and export it:

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

```

### Dry-Run Installation

To verify your proxy configuration before committing changes, use the `--dry-run` flag:

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

```

This simulates the installation process without modifying your system, allowing you to confirm the proxy URL parses correctly.

## Summary

- **Install with proxy**: Use `agent-reach install --proxy="http://user:pass@host:port"` to configure during setup.
- **Update anytime**: Use `agent-reach configure proxy "URL"` to modify settings without reinstallation.
- **Storage location**: Configuration persists in `~/.agent-reach/config.yaml` managed by [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).
- **Automatic injection**: Saved proxy values export as `HTTP_PROXY` and `HTTPS_PROXY` for all agent subprocesses.
- **Clear settings**: Pass an empty string to `configure proxy` to remove the configuration.

## Frequently Asked Questions

### What authentication formats does the Agent Reach proxy support?

Agent Reach accepts standard HTTP(S) proxy URLs including embedded credentials, such as `http://user:pass@proxy.host:3128`. The URL is stored as-is in the configuration file and passed directly to downstream tools that support proxy authentication.

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

The proxy URL is stored in `~/.agent-reach/config.yaml` on your local filesystem. The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) handles reading and writing these values, 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 to protect sensitive credentials.

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

No, configuration changes take effect immediately for new agent processes. The `configure proxy` command updates the YAML file instantly, and each subsequent agent invocation reads the current value via `Config.get("proxy")`. Running agents must be restarted to pick up the new environment variables.

### How do I troubleshoot proxy connectivity issues in Agent Reach?

First, verify the stored configuration with `agent-reach configure proxy`. Then, test the proxy manually using the export method shown above with `yt-dlp` or `curl`. Check that your proxy URL includes the correct scheme (`http` vs `https`) and that credentials are properly URL-encoded if they contain special characters.