# How to Configure Custom Proxy Settings for Restricted Networks in Agent Reach

> Configure custom proxy settings for restricted networks in Agent Reach using the CLI. Learn how to set HTTP_PROXY and HTTPS_PROXY environment variables for seamless platform requests.

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

---

**Agent Reach configures custom proxy settings through the `agent-reach configure proxy` CLI command, which stores the URL internally and automatically injects `HTTP_PROXY` and `HTTPS_PROXY` environment variables for all downstream platform requests.**

Agent Reach is an open-source automation framework that orchestrates platform-specific tools for Reddit, Twitter, and other services. When operating behind corporate firewalls or restrictive networks, you need explicit proxy configuration to route external API calls. The project implements a centralized proxy handling system that maintains compatibility with legacy configurations while ensuring seamless credential security.

## How Agent Reach Handles Proxy Configuration

Agent Reach uses a three-layer architecture to manage proxy settings across its execution pipeline. Understanding this flow helps troubleshoot connectivity issues in restricted environments.

### Configuration Layer: CLI and Config Manager

The **CLI module** ([`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)) defines the `configure proxy` subcommand at lines 68-71. This parses your proxy URL and delegates persistent storage to the config manager.

The **Config Manager** ([`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)) stores the proxy under two keys:
- `"proxy"` — the modern, preferred key
- `"bilibili_proxy"` — legacy key for backward compatibility (handled at line 216)

This dual-key approach ensures older integrations continue functioning without code changes.

### Runtime Layer: Environment Variable Injection

Agent Reach does **not** modify platform-specific code to support proxies. Instead, the CLI exports `HTTP_PROXY` and `HTTPS_PROXY` to the process environment before invoking upstream tools like `rdt` or `twcli`. This design follows the principle of "never rewrite upstream tools" — Agent Reach remains a thin orchestration layer.

## Step-by-Step Configuration Guide

### 1. Identify Your Proxy URL

Standard HTTP/HTTPS proxy format:

```bash
http://username:password@proxy.company.com:8080
https://proxy.company.com:8080  # for non-authenticated proxies

```

Agent Reach masks credentials in log output through an internal scrubbing function (`scrub_url_credentials`), preventing accidental secret exposure.

### 2. Save the Proxy via CLI

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

```

Execution flow:
- CLI parses `--proxy` argument (lines 68-71 in [`cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cli.py))
- Config manager writes to `"proxy"` key (line 216 in [`config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/config.py))
- Legacy key `"bilibili_proxy"` receives the same value (line 296 in [`cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cli.py))

### 3. Verify Configuration

```bash
agent-reach doctor

```

Dry-run output shows the scrubbed proxy URL:

```bash
agent-reach doctor --dry-run

# Would save network proxy → http://***@proxy.company.com:3128

```

This verification logic is tested in [`tests/test_private_file_writes.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_private_file_writes.py) (lines 379-421), ensuring no persistent writes occur during dry-run mode.

### 4. Execute Platform Commands

```bash

# Reddit search automatically routes through configured proxy

agent-reach reddit search "python testing"

# Twitter operations use same proxy

agent-reach twitter search "open source"

```

No additional flags required — the environment variables propagate to all child processes.

## Managing and Removing Proxy Settings

### Update Existing Proxy

Simply re-run the configure command; new values overwrite existing configuration:

```bash
agent-reach configure proxy https://newproxy.internal:9090

```

### Clear Proxy Configuration

```bash
agent-reach configure proxy ""

```

Empty string removes both `"proxy"` and `"bilibili_proxy"` keys from storage.

## Common Issues and Resolution

| Symptom | Root Cause | Solution |
|---------|-----------|----------|
| Requests bypass proxy | Direct tool invocation without `agent-reach` wrapper | Always use `agent-reach` CLI prefix; environment variables are injected at this layer |
| Proxy URL visible in logs | Missing credential scrubbing | Verify you're running v0.2.0+; scrub logic tested in [`test_scrub_credentials.py`](https://github.com/Panniantong/Agent-Reach/blob/main/test_scrub_credentials.py) |
| Bilibili-specific failures | Legacy tool reads old config key | CLI automatically mirrors to `"bilibili_proxy"`; ensure CLI version matches core |
| HTTPS sites fail | HTTP-only proxy configured | Use `https://` schema in proxy URL or configure both protocols explicitly |

## Code Reference: Key Implementation Files

| File | Purpose | Relevant Lines |
|------|---------|--------------|
| [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) | Argument parsing, proxy persistence | 68-71 (definition), 296 (legacy key handling) |
| [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) | Configuration storage backend | 210-220 (`set` method implementation) |
| [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md) | User-facing documentation | 165-190 (proxy section) |
| [`tests/test_private_file_writes.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_private_file_writes.py) | Proxy verification tests | 379-421 (dry-run behavior) |
| [`tests/test_scrub_credentials.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_scrub_credentials.py) | Credential masking validation | Full file |

## Summary

- **Single command configuration**: `agent-reach configure proxy <url>` stores settings persistently
- **Environment-based propagation**: Runtime injection of `HTTP_PROXY`/`HTTPS_PROXY` requires no upstream code changes
- **Credential security**: Automatic URL scrubbing prevents secret leakage in logs
- **Backward compatibility**: Dual-key storage (`proxy` + `bilibili_proxy`) maintains legacy support

## Frequently Asked Questions

### Does Agent Reach support SOCKS5 proxies?

Agent Reach passes proxy URLs directly to underlying platform tools via standard environment variables. SOCKS5 support depends on whether the specific upstream tool (e.g., `rdt`, `twcli`) recognizes `HTTP_PROXY`/`HTTPS_PROXY` for SOCKS schemas. Test with `socks5://host:port` format and verify connectivity through `agent-reach doctor`.

### Why does my proxy work for some platforms but not others?

Platform-specific tools handle proxy environment variables differently. Agent Reach provides the configuration uniformly, but individual tools may ignore `HTTP_PROXY` or require protocol-specific variables. Check the documentation for each integrated platform tool and consider setting both `HTTP_PROXY` and `HTTPS_PROXY` explicitly if issues persist.

### How can I verify proxy traffic is actually routing correctly?

Enable verbose logging on your proxy server, then run `agent-reach doctor --verbose` followed by a platform command. The credential-scrubbed URL displayed in diagnostic output confirms Agent Reach recognizes your configuration, but actual routing verification requires proxy-side log inspection since Agent Reach does not implement request-level logging.

### Is proxy configuration stored securely?

The proxy URL is stored in Agent Reach's configuration file with the same permissions as other settings. Credentials embedded in the URL are **not** encrypted at rest—use environment variable references (`http://$PROXY_USER:$PROXY_PASS@host:port`) if your shell supports expansion, or implement external secret management that injects values at runtime before invoking `agent-reach`.