# How to Configure Proxy Settings for Networks Blocking Agent Reach Platforms

> Configure proxy settings for Agent Reach platforms blocked by networks. Learn to use `agent-reach configure proxy` to securely route all requests through your specified server.

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

---

**Agent Reach provides built-in HTTP(S) proxy support via the `agent-reach configure proxy` command, which stores credentials in `~/.config/agent-reach/config.yml` and automatically routes all platform requests through the specified server.**

Agent Reach is a Python-based CLI and library that enables AI agents to read and search 13 Internet platforms. Because many corporate and educational networks block direct access to these platforms, the tool includes comprehensive proxy configuration capabilities that allow it to operate within restricted network environments.

## Understanding the Proxy Configuration Workflow

The proxy implementation follows a three-stage pipeline that separates user input from runtime execution.

### CLI Argument Processing

The configuration begins in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), where the `configure` command defines a `--proxy` argument (lines 68-69). When you run the configuration command, the CLI validates the proxy URL and delegates persistent storage to the configuration helper.

### Persistent Storage with Backward Compatibility

The [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) module handles all YAML read/write operations. When saving a proxy, the code writes to two keys: `proxy` (the modern key) and `bilibili_proxy` (maintained for backward compatibility, lines 232-233). During loading, any configuration key containing the substring *proxy* is recognized as a network proxy setting (line 106), ensuring flexible key matching.

### Runtime HTTP Injection

Individual platform channels do not implement proxy logic directly. Instead, the generic HTTP request helper in [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) reads the `proxy` value from the loaded configuration and injects it into request headers or environment variables as needed. This abstraction ensures consistent proxy behavior across all 13 supported platforms.

## Configuring Proxy Settings via Command Line

The simplest method uses the CLI configuration command to persist settings globally.

```bash

# Configure proxy with authentication

python -m agent_reach.cli configure proxy http://user:pass@proxy.mycorp.com:3128

```

This command writes the URL to your user configuration directory at `~/.config/agent-reach/config.yml`. The proxy string supports standard HTTP and HTTPS schemes with optional username/password authentication.

## Programmatic Proxy Configuration

You can also modify proxy settings within Python scripts using the `Config` class.

```python
from agent_reach.config import Config

# Initialize configuration handler

cfg = Config()

# Set proxy for all platforms

cfg.set("proxy", "http://proxy.example.com:8080")
cfg.save()  # Persists to ~/.config/agent-reach/config.yml

# Verify current settings

print("Active proxy:", cfg.get("proxy"))

```

The `Config.set()` method automatically synchronizes the legacy `bilibili_proxy` key, ensuring compatibility with older Agent Reach versions.

## Proxy Support for Subprocess and Node.js Clients

For agents that spawn subprocesses or use Node.js-based tools, Agent Reach provides export commands that align with `undici` proxy requirements (lines 599-609 in [`cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cli.py)).

```bash

# Export proxy environment variables for downstream tools

export HTTP_PROXY=$(agent-reach config get proxy)
export HTTPS_PROXY=$HTTP_PROXY

# Subsequent curl or Node requests will route through the proxy

curl https://api.twitter.com/2/tweets

```

This ensures that external processes inherit the same proxy configuration without requiring separate manual setup.

## Configuration File Location and Format

Agent Reach stores proxy credentials as plain text in the YAML configuration file. The system automatically creates `~/.config/agent-reach/config.yml` on first run. Because the proxy value is stored as a standard URI string, you can manually edit this file to update credentials without using the CLI.

## Summary

- **CLI Configuration**: Use `agent-reach configure proxy <url>` to save settings via [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 68-69).
- **Dual Key Storage**: The system writes to both `proxy` and `bilibili_proxy` keys in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 232-233) for backward compatibility.
- **Automatic Routing**: The [`core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/core.py) HTTP helper reads configuration and applies proxies to all platform requests without channel-specific code.
- **Subprocess Support**: Environment variable exports ensure Node.js clients using `undici` (lines 599-609) and shell tools inherit proxy settings.
- **Flexible Authentication**: Supports standard HTTP(S) proxy URLs with embedded credentials (e.g., `http://user:pass@host:port`).

## Frequently Asked Questions

### Where does Agent Reach store proxy configuration?

Agent Reach writes proxy settings to `~/.config/agent-reach/config.yml` as handled by [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). The configuration is stored in plain YAML format, making it human-readable and editable with standard text editors.

### Does Agent Reach support authenticated proxies?

Yes. The proxy configuration accepts any valid HTTP or HTTPS URL, including those with embedded authentication credentials in the format `http://username:password@proxy.example.com:port`. Both the CLI and programmatic `Config.set()` methods preserve these credentials in the configuration file.

### How do I use Agent Reach behind a corporate firewall?

First, obtain your corporate proxy URL from your network administrator. Then run `agent-reach configure proxy <url>` to persist the setting. Agent Reach will automatically route all platform requests through this proxy, including traffic to the 13 Internet platforms it supports. For tools spawned by Agent Reach, export the `HTTP_PROXY` and `HTTPS_PROXY` environment variables using the configuration value.

### Can I set different proxies for different platforms?

The current implementation uses a single global `proxy` key that applies to all platforms. However, [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) treats any key containing "proxy" as a potential proxy setting (line 106). While the base [`core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/core.py) implementation uses the global setting, individual channel implementations in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) could theoretically be extended to check for platform-specific proxy keys (e.g., `twitter_proxy`) in custom implementations.