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

> Learn how to configure a network proxy for Agent Reach in restricted environments. Agent Reach routes HTTP/S traffic through your proxy for seamless operation.

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

---

**Agent Reach routes all HTTP/S traffic through a user-defined proxy by saving the URL to `~/.agent-reach/config.yaml` and injecting it into `HTTP_PROXY`/`HTTPS_PROXY` environment variables for subprocesses.**

When operating behind corporate firewalls or national internet restrictions such as mainland China's Great Firewall, Agent Reach requires explicit proxy configuration to reach external APIs and download dependencies. According to the Panniantong/Agent-Reach source code, the tool provides built-in CLI flags and persistent configuration storage to streamline proxy setup without manual environment management.

## Where Agent Reach Stores Proxy Configuration

### The Configuration File Structure

Agent Reach persists user settings in `~/.agent-reach/config.yaml`. When you supply a proxy URL via command line or configuration commands, the system invokes `Config.set("proxy", …)` as implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 227-235). The tool also maintains a legacy key `bilibili_proxy` for backward compatibility with older configurations.

### Security Masking in Logs

In [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 106-110), the configuration renderer automatically masks any key containing "proxy" to prevent credential leakage. When running diagnostic commands, the proxy URL appears obfuscated, ensuring that authentication tokens in `http://user:pass@host:port` URLs remain hidden from logs and terminal output.

## Configuring the Proxy via CLI

### During Initial Installation

The `install` command accepts a `--proxy` flag defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 68-71). This immediately writes the proxy URL to your user configuration file:

```bash
agent-reach install \
    --env=auto \
    --proxy="http://user:pass@203.0.113.45:3128" \
    --channels=twitter,xiaoyuzhou

```

### Post-Installation Updates

To modify or add proxy settings after installation, use the dedicated configure sub-command:

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

```

This command updates the `proxy:` key in `~/.agent-reach/config.yaml` without requiring a full reinstall.

## Runtime Proxy Injection

When Agent Reach launches subprocesses that require network access—such as platform-specific dependency installers—it reads `config.get("proxy")` and injects the value into the subprocess environment as both `HTTP_PROXY` and `HTTPS_PROXY`. This occurs in the installer helper functions (prefixed with `_install_system_deps_*`), ensuring that tools like `curl`, `pip`, or `npm` automatically route through your specified endpoint when reaching blocked resources like GitHub or OpenAI APIs.

## Verifying Your Configuration

Confirm that your proxy is correctly saved and masked by running the diagnostic tool:

```bash
agent-reach doctor --json | jq .proxy

```

The JSON output displays the configured proxy URL, while the standard console output masks sensitive credentials. If the command returns your proxy URL, Agent Reach will use it for all subsequent network operations.

## Manual Environment Export (Workaround)

If you need to bypass Agent Reach's internal injection or configure the proxy for external tools, manually export the environment variables:

```bash
export HTTP_PROXY=$(grep '^proxy:' ~/.agent-reach/config.yaml | awk '{print $2}')
export HTTPS_PROXY=$HTTP_PROXY

```

Note that while `agent-reach configure get proxy` is not yet implemented as a built-in sub-command, directly reading the YAML file provides the same functionality.

## Best Practices for Restricted Environments

- **Authentication**: Use URL-encoded credentials in the format `http://user:pass@host:port` when the proxy requires basic authentication.
- **Connectivity Testing**: Verify proxy reachability before configuration with `curl -I https://api.github.com --proxy http://your-proxy:port`.
- **Security**: Never commit proxy URLs to version-controlled files; keep them exclusively in the per-user `~/.agent-reach/` directory.
- **SELinux/AppArmor**: On hardened systems, ensure the proxy binary has permissions to establish outbound connections.

## Summary

- Agent Reach stores proxy URLs in `~/.agent-reach/config.yaml` via the `Config.set()` method in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).
- The `--proxy` flag during installation and the `configure proxy` command provide ergonomic CLI methods for setting the proxy.
- Runtime subprocesses automatically receive `HTTP_PROXY` and `HTTPS_PROXY` environment variables based on the stored configuration.
- Proxy credentials are masked in diagnostic output to prevent leaking sensitive information in logs.

## Frequently Asked Questions

### Does Agent Reach support SOCKS5 proxies?

The current implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) accepts any URL string for the `--proxy` parameter, including `socks5://` schemes. However, the actual connectivity depends on whether the underlying subprocess tools (such as `curl` or Python's `requests`) are configured to handle SOCKS5 protocols. For guaranteed compatibility in restricted environments like mainland China, HTTP/HTTPS proxies are recommended.

### Why does `agent-reach doctor` hide my proxy credentials?

According to [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 106-110), the configuration display logic automatically masks any key containing the substring "proxy". This security feature prevents accidental exposure of authentication tokens in screenshots, log files, or shared terminal sessions while still allowing you to verify that a proxy is configured.

### Can I use different proxies for HTTP and HTTPS traffic?

Currently, Agent Reach stores a single `proxy` key that is exported to both `HTTP_PROXY` and `HTTPS_PROXY` environment variables. If you require separate endpoints, you must manually set these environment variables before launching Agent Reach, as the tool does not yet support distinct configuration keys for protocol-specific proxies.

### What is the `bilibili_proxy` legacy key mentioned in the source code?

The codebase maintains a `bilibili_proxy` configuration key for backward compatibility with earlier versions of Agent Reach. While the modern `proxy` key is now standard, existing configurations using the legacy key remain functional. New configurations should use the standard `proxy` key in `~/.agent-reach/config.yaml`.