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

> Learn to configure an HTTP proxy for Agent Reach, ensuring seamless API calls in restricted network environments. Set up your proxy for reliable external tool integration.

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

---

**Agent Reach routes all external API calls through an HTTP proxy by storing the proxy URL in `~/.agent-reach/config.yaml` under the `proxy` key, then automatically injecting `HTTP_PROXY` and `HTTPS_PROXY` environment variables into subprocesses when invoking external tools like Twitter or Reddit clients.**

When operating behind corporate firewalls or restrictive networks, Agent Reach agents require explicit proxy configuration to access external platforms such as Twitter, Reddit, and YouTube. The open-source tool **Panniantong/Agent-Reach** provides built-in support for HTTP proxy routing through both installation flags and runtime configuration management. This guide explains how to configure HTTP proxy settings for Agent Reach based on the actual implementation in the source code.

## Where Agent Reach Stores Proxy Configuration

Agent Reach persists proxy settings 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) handles all configuration read/write operations, automatically masking sensitive values containing "proxy" when displaying configuration data.

### Sensitive Value Masking in the Config Class

The configuration manager treats proxy URLs as sensitive data alongside API keys and tokens. When displaying configuration values, the code masks any key containing "proxy" to prevent credential leakage in logs or terminal 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

```

## Setting the Proxy During Installation

You can configure the HTTP proxy immediately when installing Agent Reach using the `--proxy` flag. This approach writes the proxy URL to both the modern `proxy` key and the legacy `bilibili_proxy` key for backward compatibility.

### Using the --proxy Flag with agent-reach install

The CLI handler in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) captures the proxy argument during the installation command:

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

```

The installation logic writes the value to configuration:

```python

# From agent_reach/cli.py

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

```

## Updating the Proxy After Installation

For environments where proxy settings change frequently or were not set during initial installation, Agent Reach provides a dedicated configuration command to update proxy settings without reinstallation.

### The configure proxy Command

Use the `configure proxy` subcommand to modify existing proxy settings:

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

```

The CLI updates both configuration keys to maintain synchronization:

```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）")

```

## How Proxy Settings Are Applied at Runtime

Agent Reach does not use the proxy configuration for its own internal HTTP clients directly; instead, it exports standard `HTTP_PROXY` and `HTTPS_PROXY` environment variables when spawning subprocesses. This ensures compatibility with external CLI tools like `twitter-cli`, `rdt-cli`, and Node.js fetch implementations.

### Environment Variable Injection

When any channel invokes an external binary, the runtime copies the current environment and injects the stored proxy values:

```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 appears throughout the codebase in channel-specific dependency installers and the `doctor` command handlers.

### Legacy Key Synchronization

Older Agent Reach versions stored proxy settings exclusively under `bilibili_proxy`. The current implementation maintains both keys simultaneously to ensure backward compatibility with legacy channel implementations while supporting newer code that reads the standardized `proxy` key.

## Practical Configuration Examples

### Verify Current Proxy Configuration

Inspect the YAML configuration file directly to confirm proxy settings:

```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

```

### Test Configuration with Dry Run

Before committing proxy settings to your configuration, test the install command:

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

```

Output:

```

[dry-run] Would save network proxy

```

### Validate Proxy Connectivity

Run the diagnostic command to verify all channels can access external services through the configured proxy:

```bash
agent-reach doctor

```

The `doctor` command invokes each channel's health check with `HTTP_PROXY` and `HTTPS_PROXY` populated from your configuration.

## Summary

- Agent Reach stores HTTP proxy URLs in `~/.agent-reach/config.yaml` under the `proxy` key (with `bilibili_proxy` as a legacy fallback).
- 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 to prevent credential exposure.
- Use `agent-reach install --proxy <url>` during initial setup or `agent-reach configure proxy <url>` to update existing installations.
- At runtime, Agent Reach injects `HTTP_PROXY` and `HTTPS_PROXY` into subprocess environments when invoking external tools like Twitter or Reddit clients.
- Both modern and legacy configuration keys are synchronized automatically to maintain backward compatibility.

## Frequently Asked Questions

### What file stores the HTTP proxy configuration for Agent Reach?

Agent Reach stores proxy settings in `~/.agent-reach/config.yaml` in the user's home directory. This YAML file contains the `proxy` key (and legacy `bilibili_proxy` key) that the CLI and runtime read to populate environment variables.

### Why does Agent Reach maintain both `proxy` and `bilibili_proxy` configuration keys?

Older versions of Agent Reach used `bilibili_proxy` exclusively. The current implementation writes to both keys simultaneously to ensure backward compatibility with legacy channel code while supporting newer implementations that use the standardized `proxy` key.

### Does Agent Reach support proxy authentication with usernames and passwords?

Yes. Agent Reach accepts fully qualified proxy URLs including embedded credentials in the format `http://user:pass@host:port`. These URLs are stored as-is in the configuration file and exported to `HTTP_PROXY` and `HTTPS_PROXY` environment variables that upstream tools respect.

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

Currently, Agent Reach uses a single global proxy configuration applied to all external subprocess calls. The architecture in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) sets one proxy value that applies universally across Twitter, Reddit, YouTube, and other channel operations.