How to Configure a Proxy for Agent Reach in Restricted Networks

Agent Reach routes all external API calls through a network proxy by storing the proxy URL in ~/.agent-reach/config.yaml and injecting HTTP_PROXY and HTTPS_PROXY environment variables into subprocesses at runtime.

Agent Reach is designed to operate behind corporate firewalls and restrictive network environments by supporting standard proxy configurations. When you configure a proxy for Agent Reach, the CLI stores your credentials in a local configuration file and automatically applies them whenever invoking external tools like Twitter or Reddit clients. This ensures seamless connectivity even when direct internet access is blocked.

Where Agent Reach Stores Proxy Configuration

The proxy settings persist in the user's home directory within the Agent Reach configuration file.

The Config File Location

Agent Reach maintains its configuration at ~/.agent-reach/config.yaml. This file contains the proxy key alongside other sensitive credentials required for channel operations.

Sensitive Value Masking

In agent_reach/config.py, the Config class automatically masks any configuration key containing "proxy" when displaying settings to prevent credential leakage. The source code explicitly checks for proxy-related strings:

# 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 proxy URLs with embedded authentication tokens never appear in logs or terminal output.

Setting the Proxy During Installation

You can configure the proxy immediately when installing Agent Reach using the --proxy flag. This captures the proxy URL and writes it to the configuration file before any network operations begin.

According to the install handler in agent_reach/cli.py, the CLI accepts the proxy URL and persists it to both the current proxy key and the legacy bilibili_proxy key:

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 during initial setup:

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

This single command ensures that all subsequent channel operations route through your specified proxy.

Updating the Proxy After Installation

Network environments change, and Agent Reach allows you to update proxy settings without reinstalling the entire tool.

Using the Configure Command

The configure proxy sub-command updates the stored proxy URL in agent_reach/cli.py. This writes the new value to the configuration file and maintains synchronization between the modern proxy key and the legacy bilibili_proxy key:

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 configuration at any time:

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

The change takes effect immediately for the next channel operation.

How the Proxy is Applied at Runtime

Agent Reach does not use the proxy for its own internal logic. Instead, it reads the stored proxy value and injects it into the environment of any subprocess that requires external network access.

Before invoking external binaries like twitter-cli or rdt-cli, the runtime executes code similar to this pattern found throughout the codebase:

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 approach ensures that upstream tools receive the standard HTTP_PROXY and HTTPS_PROXY environment variables they expect, enabling seamless operation behind corporate firewalls without modifying individual channel implementations.

Understanding the Legacy bilibili_proxy Key

Older versions of Agent Reach stored proxy settings exclusively under the bilibili_proxy key. The current codebase maintains both keys simultaneously to ensure backward compatibility with legacy channel implementations while supporting modern proxy-aware code.

When you set or update the proxy using either the --proxy flag or the configure proxy command, Agent Reach writes the same URL to both the proxy and bilibili_proxy keys. This synchronization prevents configuration drift and ensures that older Bilibili channel code continues to function correctly while newer implementations use the standardized proxy key.

Complete Configuration Examples

1. Install with Proxy in One Step

Configure the proxy during initial installation to ensure all dependencies are downloaded through your network gateway:

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

2. Update Proxy After Installation

Change the proxy URL without reinstalling:

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

3. Verify the Configuration

Inspect the configuration file to confirm both keys are set:

cat ~/.agent-reach/config.yaml

You should see output similar to:

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

4. Test with Dry Run

Preview what the installer would do without making changes:

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

This outputs:

[dry-run] Would save network proxy

5. Runtime Verification

Run the diagnostic tool to verify all channels can access external networks through the proxy:

agent-reach doctor

Each channel test inherits the HTTP_PROXY and HTTPS_PROXY variables from the configuration.

Summary

• Configuration location: Agent Reach stores proxy settings in ~/.agent-reach/config.yaml under the proxy key.
• Dual key strategy: The tool synchronizes both proxy and bilibili_proxy keys for backward compatibility.
• CLI commands: Use agent-reach install --proxy for initial setup or agent-reach configure proxy for updates.
• Runtime behavior: The CLI injects HTTP_PROXY and HTTPS_PROXY environment variables into subprocesses before invoking external tools.
• Security: The Config class in agent_reach/config.py masks proxy URLs containing credentials when displaying configuration.

Frequently Asked Questions

Where does Agent Reach store the proxy configuration?

Agent Reach stores the proxy URL in the YAML configuration file located at ~/.agent-reach/config.yaml. The Config class in agent_reach/config.py manages this file, automatically masking sensitive values like passwords when displaying settings. Both the modern proxy key and the legacy bilibili_proxy key contain the same URL to ensure compatibility across different channel implementations.

Why does Agent Reach use both proxy and bilibili_proxy keys?

The bilibili_proxy key exists for backward compatibility with older versions of Agent Reach that specifically referenced this key for Bilibili channel operations. Current versions write the proxy URL to both keys simultaneously when you use the --proxy flag or configure proxy command. This dual-key strategy ensures that legacy code continues to function while newer implementations migrate to the standardized proxy key.

Do I need to restart Agent Reach after changing the proxy?

No restart is required. Agent Reach reads the configuration file from ~/.agent-reach/config.yaml at runtime whenever it invokes external tools. When you run agent-reach configure proxy, the change takes effect immediately for the next channel operation. The CLI reads the current proxy value and injects it into the environment of any subprocess it launches.

How do I verify that the proxy is working correctly?

Run agent-reach doctor to execute health checks across all configured channels. This command invokes external tools like twitter-cli and rdt-cli with the HTTP_PROXY and HTTPS_PROXY environment variables set from your configuration. If the channels can reach their respective APIs, the proxy is functioning correctly. You can also inspect the configuration file directly with cat ~/.agent-reach/config.yaml to confirm the proxy URL is stored.

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