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

> Configure a network proxy for Agent Reach in restricted environments. Learn how to set proxy settings via CLI commands for seamless tool integration. Simplify your restricted network setup.

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

---

**Agent Reach stores proxy settings in `~/.agent-reach/config.yaml` and exposes them to downstream tools via the `HTTP_PROXY` and `HTTPS_PROXY` environment variables, configurable through either the `install` or `configure` CLI commands.**

Agent Reach is an open-source automation framework developed by Panniantong that requires network connectivity for external service integrations. When operating in restricted network environments, you must configure a network proxy for Agent Reach to ensure agents can reach external APIs and services. This configuration is handled through a centralized YAML-based configuration system managed by the `Config` class.

## Configuration Storage and Architecture

Agent Reach persists runtime settings in a per-user YAML file located 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) manages this file, providing methods like `set()`, `get()`, and `save()` to manipulate key-value pairs.

When you configure a network proxy, the system writes the value to two keys within this file:

- `proxy` — the primary key used by current agent implementations
- `bilibili_proxy` — a legacy key maintained for backward compatibility

The proxy string is treated as opaque configuration data. Agent Reach does not perform network operations through the proxy itself; instead, it exports the value as standard `HTTP_PROXY` and `HTTPS_PROXY` environment variables before invoking external tools.

## CLI Methods for Proxy Configuration

The command-line interface in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) provides two distinct entry points for setting proxy values depending on your installation stage.

### Option 1: Configure During Installation

When running the initial setup, pass the `--proxy` flag to the `install` sub-command. According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 68-71 for the flag definition and lines 36-44 for the handling logic), the installer accepts the flag and persists it via the `Config` class:

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

```

### Option 2: Configure After Installation

If you need to add or update a proxy on an existing installation, use the `configure` sub-command. The handler for this command (lines 62-70 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)) stores the supplied string under both the `proxy` and `bilibili_proxy` keys via `Config.set(key, value)`:

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

```

Both methods ultimately call `Config.save()` to persist the changes to disk.

## How Downstream Tools Consume the Proxy

Once stored, agents retrieve the proxy value using `Config.get("proxy")` before invoking channel-specific tools. The framework exports the configuration as environment variables (`HTTP_PROXY` and `HTTPS_PROXY`) that standard HTTP libraries recognize.

This design benefits integrations with external channels such as `youtube`, `twitter`, and `reddit`, allowing these tools to transparently route traffic through your corporate or restricted gateway without requiring tool-specific proxy configurations.

## Verifying Your Proxy Configuration

To confirm that Agent Reach has correctly stored your network proxy settings, inspect the configuration file directly:

```bash
cat ~/.agent-reach/config.yaml

```

Expected output should include both keys:

```yaml
proxy: http://user:pass@proxy.example.com:8080
bilibili_proxy: http://user:pass@proxy.example.com:8080

```

If these values appear as expected, agents will automatically apply them when executing network-dependent operations.

## Summary

- Agent Reach stores proxy settings in `~/.agent-reach/config.yaml`, managed by the `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).
- Use `agent-reach install --proxy "<url>"` for initial setup or `agent-reach configure proxy "<url>"` for post-installation updates.
- The system writes the proxy to both `proxy` and `bilibili_proxy` keys for backward compatibility.
- Agents export the configured value as `HTTP_PROXY` and `HTTPS_PROXY` environment variables for downstream channel tools.
- The proxy string is opaque—Agent Reach does not validate connectivity, leaving network operations to the external utilities that consume these environment variables.

## Frequently Asked Questions

### Can I configure the proxy without using the CLI?

Yes. Because Agent Reach uses a standard YAML file at `~/.agent-reach/config.yaml`, you can manually edit this file with any text editor. Add or modify the `proxy` key directly, following standard YAML syntax. The `Config` class will read this value the next time an agent initializes.

### Does Agent Reach support authenticated proxies?

Yes. The proxy configuration accepts any valid HTTP or HTTPS URL string, including those containing embedded credentials. Pass the full URL with authentication to the `--proxy` flag or `configure` command, such as `http://username:password@proxy.company.com:8080`. The framework stores and exports this string verbatim to the environment variables.

### Which network operations in Agent Reach use the proxy settings?

Agent Reach itself does not perform direct network operations. Instead, the proxy settings are consumed by external channel integrations—specifically `youtube`, `twitter`, and `reddit` agents—when they invoke upstream utilities. The framework sets `HTTP_PROXY` and `HTTPS_PROXY` before spawning these processes, ensuring compliant traffic routing in restricted environments.

### Where is the proxy configuration logic implemented in the source code?

The configuration persistence logic resides in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) within the `Config` class methods `set()` and `save()`. The CLI entry points are implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py): the `--proxy` flag definition appears at lines 68-71, installation-time handling at lines 36-44, and the `configure` sub-command handler at lines 62-70. Test coverage for these features exists in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) (lines 158 and 174).