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

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) 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) 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:

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

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

Execution flow:

• CLI parses --proxy argument (lines 68-71 in cli.py)
• Config manager writes to "proxy" key (line 216 in config.py)
• Legacy key "bilibili_proxy" receives the same value (line 296 in cli.py)

3. Verify Configuration

agent-reach doctor

Dry-run output shows the scrubbed proxy URL:

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 (lines 379-421), ensuring no persistent writes occur during dry-run mode.

4. Execute Platform Commands

# 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:

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

Clear Proxy Configuration

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
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	Argument parsing, proxy persistence	68-71 (definition), 296 (legacy key handling)
agent_reach/config.py	Configuration storage backend	210-220 (set method implementation)
docs/install.md	User-facing documentation	165-190 (proxy section)
tests/test_private_file_writes.py	Proxy verification tests	379-421 (dry-run behavior)
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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}