Configuring a Network Proxy in Agent Reach for Restricted Networks

Agent Reach routes all external API calls through a configurable network proxy by storing the proxy URL in ~/.agent-reach/config.yaml and automatically injecting HTTP_PROXY and HTTPS_PROXY environment variables into every subprocess invocation.

Agent Reach is an open-source automation framework that interacts with external platforms like Twitter, Reddit, YouTube, and Bilibili. When operating behind corporate firewalls or restricted networks, you must configure proxy support to ensure agents can reach these services. This guide explains how to set up, update, and verify proxy configuration using the CLI and configuration files.

Where Proxy Settings Are Stored

Proxy configuration persists in the YAML file located at ~/.agent-reach/config.yaml. The Config class in agent_reach/config.py manages this file and handles all read and write operations for the proxy and bilibili_proxy keys.

Security Masking for Sensitive Values

The configuration manager treats proxy URLs as sensitive data to prevent credential leakage. When displaying configuration values, the system masks any key containing the substring "proxy" by truncating the value to eight characters and appending an ellipsis.

# 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 authentication credentials remain secure in logs and terminal output while still allowing you to verify that a proxy is configured.

Setting the Proxy During Installation

You can configure the proxy during the initial installation using the --proxy flag. This captures the proxy URL and persists it to the configuration file immediately.

Using the --proxy Flag

When running agent-reach install, append the --proxy argument followed by your proxy URL:

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

According to the source code in agent_reach/cli.py, this command writes the proxy URL to both the 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 访问受限网络时使用）")

Preview Changes with Dry-Run

To preview what the installer would configure without modifying the system, use the --dry-run flag:

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

This outputs [dry-run] Would save network proxy without writing to the configuration file.

Updating Proxy Configuration After Installation

You can modify proxy settings at any time using the configure command without reinstalling the entire framework.

The configure proxy Command

Update the stored proxy URL using the configure proxy sub-command:

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

As implemented in agent_reach/cli.py, this command updates both configuration keys to maintain backward compatibility:

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

Verify the configuration by viewing the YAML file:

cat ~/.agent-reach/config.yaml

The output shows both keys synchronized:

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

How Agent Reach Applies Proxy Settings at Runtime

Agent Reach does not use the proxy configuration directly for its own HTTP requests. Instead, it injects the settings into the environment of subprocesses that execute external tools and channel binaries.

Environment Variable Injection

Before invoking any external binary (such as twitter-cli, rdt-cli, or Node.js fetch implementations), the CLI reads the stored proxy and populates standard environment variables:

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, found in agent_reach/cli.py and utilized by agent_reach/channels/base.py and agent_reach/doctor.py, ensures that upstream tools respect the proxy settings without requiring individual configuration.

Legacy Key Support

Older versions of Agent Reach stored proxy settings exclusively under the bilibili_proxy key. The current implementation maintains both keys to ensure backward compatibility with legacy channel implementations while supporting new features that read the standardized proxy key.

Verifying Proxy Configuration

After configuring the proxy, verify connectivity using the built-in diagnostic command:

agent-reach doctor

This command runs health checks across all configured channels, with each subprocess receiving the HTTP_PROXY and HTTPS_PROXY environment variables automatically.

For Node.js-based channels that use undici for HTTP requests, ensure the dependency is installed:

agent-reach install

The installer automatically detects Node.js and installs undici if present, enabling proper proxy support for modern fetch implementations.

Summary

• Storage Location: Proxy settings reside in ~/.agent-reach/config.yaml and are managed by the Config class in agent_reach/config.py.
• Configuration Methods: Use agent-reach install --proxy <url> during setup or agent-reach configure proxy <url> for updates.
• Environment Variables: The runtime injects HTTP_PROXY and HTTPS_PROXY into every subprocess environment before invoking external tools.
• Dual Key Storage: Both proxy and bilibili_proxy keys are maintained for backward compatibility with legacy channel implementations.
• Security: Proxy values are masked in output to prevent credential leakage in logs and terminal sessions.

Frequently Asked Questions

What environment variables does Agent Reach use for proxy configuration?

Agent Reach reads the proxy value from its configuration file and exports it as both HTTP_PROXY and HTTPS_PROXY environment variables before spawning subprocesses. This follows the standard convention that most HTTP clients and CLI tools respect.

Why does Agent Reach store both proxy and bilibili_proxy keys?

Older versions of the framework used only the bilibili_proxy key. The current implementation writes to both proxy and bilibili_proxy to maintain backward compatibility with legacy code while transitioning to a standardized key name used by newer channel implementations.

How can I verify that my proxy configuration is active?

Run cat ~/.agent-reach/config.yaml to confirm the proxy URL appears in the file. Then execute agent-reach doctor to test connectivity across all channels. If the proxy is configured correctly, external API calls will succeed even in restricted network environments.

Does Agent Reach support authenticated proxies?

Yes. Include the username and password directly in the proxy URL when configuring: http://user:pass@proxy.example.com:3128. The Config class in agent_reach/config.py masks these credentials in display output to prevent exposure in logs or terminal sessions.

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