# How to Configure Proxy for Restricted Networks in Agent-Reach

> Learn how to configure proxy for restricted networks in Agent-Reach. Route external API calls through a proxy by editing config.yaml and setting environment variables.

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

---

**TLDR:** Agent-Reach routes external API calls through a proxy by storing the URL in `~/.agent-reach/config.yaml` and injecting `HTTP_PROXY`/`HTTPS_PROXY` into subprocess environments when channels invoke external tools.

Agent-Reach is an open-source agent framework (Panniantong/Agent-Reach) that interacts with external services like Twitter, Reddit, and YouTube. When operating behind corporate firewalls or restrictive networks, you must configure proxy settings to allow these agents to reach external APIs. The framework supports this via CLI flags and configuration commands that persist settings to your local config file.

## Where Proxy Configuration is Stored

All proxy settings are persisted in the user's configuration directory 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) handles read and write operations, treating any key containing "proxy" as sensitive data that requires masking when displayed.

### Sensitive Value Masking

According to the source code in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the configuration manager automatically masks proxy values to prevent credential leakage in logs or UI displays:

```python

# mask proxy-related keys when showing the config

if any(s in k.lower() for s in ("key", "token", "password", "proxy")):
    masked[k] = f"{str(v)[:8]}..." if v else None

```

This ensures that when you view your configuration, the proxy URL appears truncated (e.g., `http://us...`) rather than exposing the full credentials.

## Setting the Proxy During Installation

You can configure the proxy during the initial setup using the `--proxy` flag with the install command. This captures the proxy URL and writes it to both the modern `proxy` key and the legacy `bilibili_proxy` key for backwards compatibility.

### Using the Install Command

In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the install handler processes the `--proxy` argument and persists it to the config file:

```python
if args.proxy:
    if dry_run:
        print(f"[dry-run] Would save network proxy")
    else:
        config.set("proxy", args.proxy)
        config.set("bilibili_proxy", args.proxy)  # legacy key

        print(f"✅ 代理已保存（Agent 访问受限网络时使用）")

```

Run this command to set your proxy during installation:

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

```

### Dry-Run Mode

To verify what would be saved without actually modifying your configuration, use the `--dry-run` flag:

```bash
agent-reach install --dry-run --proxy http://proxy:8080

```

The CLI outputs `[dry-run] Would save network proxy` without writing to [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml).

## Updating Proxy Settings After Installation

If you need to change or add a proxy after the initial installation, use the `configure` command. This updates the existing configuration without reinstalling dependencies.

In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the configure handler accepts a `proxy` key and updates both configuration entries:

```python
if args.key == "proxy":
    # Nothing reads this key at runtime — agents read it back

    # and export HTTP(S)_PROXY before invoking upstream tools.

    config.set("proxy", value)
    config.set("bilibili_proxy", value)  # keep legacy key in sync

    print("✅ 代理已保存（供 Agent 在访问 Reddit/Twitter 等需要代理的网络时设置 HTTP_PROXY/HTTPS_PROXY）")

```

Update your proxy with:

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

```

Verify the change by viewing your config file:

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

```

You should see both keys populated:

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

```

## How Proxy Settings Are Applied at Runtime

Agent-Reach does not use the proxy configuration directly for its own HTTP requests. Instead, it acts as a passthrough layer for external tools like `twitter-cli`, `rdt-cli`, or Node.js fetch implementations.

### Environment Variable Injection

When a channel invokes an external binary, the CLI reads the stored proxy and injects it into the subprocess environment:

```python
env = os.environ.copy()
if config.get("proxy"):
    env["HTTP_PROXY"] = config.get("proxy")
    env["HTTPS_PROXY"] = config.get("proxy")
subprocess.run([binary, "..."], env=env, …)

```

This pattern ensures that any command executed on the host inherits the proxy settings, enabling seamless operation behind restrictive firewalls.

### Legacy Key Synchronization

Older versions of Agent-Reach stored the proxy under `bilibili_proxy` specifically for Bilibili channel operations. The current implementation maintains both keys to ensure backwards compatibility:

- **`proxy`**: The modern key used by current channel implementations
- **`bilibili_proxy`**: Legacy key maintained for older code paths

The `configure` and `install` commands always update both keys simultaneously to prevent configuration drift.

## Verifying Proxy Configuration

To confirm your proxy is active, run the diagnostic command:

```bash
agent-reach doctor

```

This executes health checks across all channels, and each external tool invoked during these checks receives the `HTTP_PROXY` and `HTTPS_PROXY` environment variables from your configuration.

If you encounter issues with Node.js-based channels, ensure `undici` is installed for proper proxy support:

```bash
agent-reach install

```

The installer automatically detects Node.js and installs `undici` if present, ensuring fetch operations respect the proxy configuration.

## Summary

- Agent-Reach stores proxy URLs in `~/.agent-reach/config.yaml` under the `proxy` key (and legacy `bilibili_proxy` key).
- Set during installation with `agent-reach install --proxy <url>` or update later with `agent-reach configure proxy <url>`.
- The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) masks proxy values as sensitive data.
- At runtime, the CLI injects `HTTP_PROXY` and `HTTPS_PROXY` into subprocess environments before invoking external tools like `twitter-cli` or `rdt-cli`.
- Use `--dry-run` to test configuration changes without modifying files.
- Run `agent-reach doctor` to verify proxy settings across all channels.

## Frequently Asked Questions

### How does Agent-Reach handle authentication in proxy URLs?

Agent-Reach stores the complete proxy URL including credentials in `~/.agent-reach/config.yaml`. The framework treats any key containing "proxy" as sensitive and masks the value in display outputs, showing only the first 8 characters. When executing subprocesses, the full URL (including username and password) is passed to the `HTTP_PROXY` and `HTTPS_PROXY` environment variables.

### Can I use different proxies for different channels?

Currently, Agent-Reach supports a single global proxy configuration. The `proxy` and `bilibili_proxy` keys in [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) are synchronized to maintain backwards compatibility, but the framework does not support channel-specific proxy settings. All external tools invoked by any channel receive the same `HTTP_PROXY` and `HTTPS_PROXY` values.

### Why are there two proxy keys in my config file?

The `bilibili_proxy` key exists for backwards compatibility with older versions of Agent-Reach that stored proxy settings specifically for Bilibili channel operations. Modern versions use the `proxy` key for all channels. The CLI automatically keeps both keys synchronized when you run `agent-reach install --proxy` or `agent-reach configure proxy`, ensuring legacy code continues to function while newer implementations use the standardized key.

### What happens if no proxy is configured?

If the proxy configuration is absent or empty, Agent-Reach does not modify the subprocess environment. External tools inherit the system environment variables without proxy overrides, which may result in connection failures when operating behind restrictive firewalls.