# How to Set Up a Network Proxy for Agent-Reach in Restricted Networks

> Learn how to set up a network proxy for Agent-Reach in restricted environments. Configure your proxy settings in config.yaml and leverage environment variables for seamless API access.

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

---

**Agent-Reach routes all external API calls through a standard HTTP/HTTPS proxy by storing the URL in `~/.agent-reach/config.yaml` and injecting `HTTP_PROXY`/`HTTPS_PROXY` environment variables into every subprocess.**

When operating behind corporate firewalls or restrictive network policies, the open-source **Panniantong/Agent-Reach** framework requires explicit proxy configuration to reach external services like Twitter, Reddit, and YouTube. The tool persists proxy credentials locally and automatically applies them to all spawned channel processes at runtime.

## Where Proxy Settings Are Stored

Configuration values reside in the user’s home 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) manages persistence and treats any key containing “proxy” as sensitive data, masking it in logs and console output.

```python

# From agent_reach/config.py

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 proxy credentials containing authentication tokens are never fully displayed when viewing configuration dumps.

## Setting the Proxy During Installation

You can define the network proxy immediately during the initial setup using the `--proxy` flag with the `install` command. The CLI handler in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) captures the URL and writes it to both the modern `proxy` key and the legacy `bilibili_proxy` key for backward compatibility.

```python

# From agent_reach/cli.py – install handler

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 访问受限网络时使用）")

```

Execute the following to configure the proxy in one step:

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

```

## Updating Proxy Configuration After Installation

If the network environment changes or you need to rotate credentials after installation, use the `configure proxy` sub-command. This updates the stored values without requiring a full reinstallation.

```python

# From agent_reach/cli.py – configure handler

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

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

```

Run this command to update your settings:

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

```

## How the Proxy Is Applied at Runtime

Agent-Reach does not use the proxy for its own internal logic; instead, it exports the stored value as standard `HTTP_PROXY` and `HTTPS_PROXY` environment variables before invoking external binaries. This pattern appears throughout the codebase, particularly in channel implementations that spawn subprocesses for tools like `twitter-cli`, `rdt-cli`, or Node.js fetch operations.

```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, ...)

```

Because the proxy is injected into the environment of every spawned process, upstream tools that respect standard environment variables automatically route traffic through your specified proxy.

## Legacy Key Compatibility

Older versions of Agent-Reach stored proxy settings exclusively under the key `bilibili_proxy`. The current installer synchronizes both `proxy` and `bilibili_proxy` to ensure legacy channel code continues to function while newer implementations read from the canonical `proxy` key. Maintaining both keys prevents breaking changes for existing installations that may still reference the legacy name.

## Practical Configuration Examples

### Install with Proxy in One Step

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

```

This writes the URL to `~/.agent-reach/config.yaml` and enables proxy support for all subsequent channel operations.

### Update Proxy After Installation

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

```

Verify the configuration file contents:

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

```

Expected output:

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

```

### Verify with Dry-Run Mode

Test the installation logic without writing changes:

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

```

Output:

```

[dry-run] Would save network proxy

```

### Runtime Verification

Run the diagnostic command to ensure all channels inherit the proxy environment:

```bash
agent-reach doctor

```

The `doctor` command invokes each channel’s health check, and because the subprocess environment includes `HTTP_PROXY`/`HTTPS_PROXY`, any network-dependent validations will route through your configured proxy.

## Summary

- **Configuration Location**: Proxy URLs are stored in `~/.agent-reach/config.yaml` under the `proxy` key (and legacy `bilibili_proxy`).
- **CLI Commands**: Use `agent-reach install --proxy <url>` during setup or `agent-reach configure proxy <url>` to update later.
- **Runtime Behavior**: The stored URL is injected into `HTTP_PROXY` and `HTTPS_PROXY` for every subprocess spawned by channel tools.
- **Security**: The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) automatically masks proxy values to prevent credential leakage in logs.
- **Backward Compatibility**: Both `proxy` and `bilibili_proxy` keys are maintained in sync to support legacy channel implementations.

## Frequently Asked Questions

### What URL format should I use for the proxy?

Agent-Reach passes the proxy URL directly to the underlying tools, so any format supported by your external binaries works. Typically, use `http://user:pass@host:port` for authenticated HTTP proxies or `http://host:port` for unauthenticated ones. The URL is written verbatim to the config file and exported as `HTTP_PROXY`/`HTTPS_PROXY`.

### Does Agent-Reach support SOCKS5 proxies?

Support depends entirely on the external tools (Node.js fetch, Python requests, etc.) invoked by each channel. Agent-Reach itself only stores and exports the proxy URL; it does not modify or validate the protocol. If your downstream tools support SOCKS5 via `HTTP_PROXY` (or require `ALL_PROXY`), specify that URL format when running `agent-reach configure proxy`.

### Why does my config file contain both `proxy` and `bilibili_proxy` keys?

The `bilibili_proxy` key exists for backward compatibility with older Agent-Reach versions that stored network settings under that specific name. The current CLI in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) writes to both keys simultaneously to ensure legacy channel code continues to function while newer code uses the canonical `proxy` key.

### How can I verify the proxy is actually being used?

Run `agent-reach doctor` after configuring the proxy. This command executes health checks for all channels, and because the runtime injects `HTTP_PROXY`/`HTTPS_PROXY` into each subprocess, network-dependent validations will fail if the proxy is unreachable. You can also inspect the environment of running Agent-Reach processes to confirm the variables are present.