How Agent Reach Handles Proxy Configuration for Restricted Network Environments

Agent Reach stores proxy URLs in a central configuration file and automatically exports them as HTTP_PROXY and HTTPS_PROXY environment variables for downstream agents, enabling seamless operation behind corporate firewalls.

The Panniantong/Agent-Reach repository provides a CLI-driven mechanism to persist proxy settings that agents can consume without manual environment variable management. By centralizing proxy configuration for restricted network environments in a YAML-based config store, Agent Reach ensures that HTTP and HTTPS requests from Node.js and Python backends automatically traverse corporate firewalls.

Configuring the Proxy via CLI

Agent Reach exposes proxy settings through two primary CLI interfaces: the installation flag for temporary configuration and the dedicated configure command for permanent storage.

The --proxy Installation Flag

The install sub-command accepts a --proxy argument that validates and stores the proxy URL immediately. In agent_reach/cli.py, the argument is defined with a default empty string to handle optional proxy injection:

p_install.add_argument("--proxy", default="", 
                       help="Network proxy saved for agents to export as HTTP(S)_PROXY ...")

When provided, the CLI writes the value to both the canonical proxy key and the legacy bilibili_proxy key for backward compatibility:

if args.proxy:
    print(f"[dry-run] Would save network proxy")
    config.set("proxy", args.proxy)
    config.set("bilibili_proxy", args.proxy)

Persistent Configuration with configure proxy

For non-transient proxy settings, the configure command provides a dedicated sub-command. As implemented in agent_reach/cli.py around line 317, the CLI accepts:

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

This persists the URL to the configuration storage, making it available across agent sessions without requiring the --proxy flag on every invocation.

How the Proxy Configuration is Stored

The configuration system validates and stores proxy settings through a centralized schema that ensures type safety and key consistency.

Configuration Schema Validation

In agent_reach/config.py, the Config class explicitly lists proxy as an allowed configuration key at line 114:

"proxy",

This registration ensures that any value set via config.set("proxy", ...) passes validation and persists to the underlying YAML or ENV-based storage backend.

Backward Compatibility Handling

Agent Reach maintains dual-key storage for proxy settings. When saving via CLI, the system writes identical values to both proxy (the current standard) and bilibili_proxy (legacy support). This dual-write approach ensures that older agent components reading the deprecated key still receive valid proxy URLs while new implementations migrate to the canonical proxy key.

Runtime Proxy Injection

Once persisted, the proxy configuration becomes available to downstream agent processes through environment variable injection and fetch library shimming.

Environment Variable Export

Downstream components read the stored proxy and expose it as standard HTTP_PROXY and HTTPS_PROXY environment variables. This convention allows any external process or subprocess spawned by Agent Reach to automatically route requests through the configured proxy without code modification.

Integration with Node.js undici

The opencli backend specifically leverages the stored proxy for Node.js fetch operations. According to the implementation in agent_reach/backends/opencli.py (referenced around lines 621-631 in the CLI structure), the undici fetch shim checks for the proxy entry and configures the HTTP client accordingly. This enables Node.js-based agents to traverse restricted networks even when running behind authenticated corporate proxies.

Complete Workflow Example

Configure a corporate proxy for persistent use:

# Store proxy credentials securely in config

agent-reach configure proxy http://user:pass@10.0.0.1:3128

# Verify configuration (dry-run mode)

agent-reach install --proxy http://user:pass@10.0.0.1:3128

Programmatically verify the stored value:

from agent_reach.config import Config

cfg = Config()
proxy_url = cfg.get("proxy")
print(f"Current proxy: {proxy_url}")

Summary

• CLI interface: Use agent-reach configure proxy <url> for permanent storage or --proxy flag for temporary configuration.
• Storage keys: Values are written to both proxy (canonical) and bilibili_proxy (legacy) keys in agent_reach/config.py.
• Environment injection: The stored proxy is automatically exported as HTTP_PROXY and HTTPS_PROXY for subprocess compatibility.
• Node.js support: The opencli backend integrates with undici to respect proxy settings in Node.js fetch operations.

Frequently Asked Questions

What environment variables does Agent Reach use for proxy settings?

Agent Reach exports the stored proxy URL as HTTP_PROXY and HTTPS_PROXY environment variables. This follows the standard convention that most HTTP clients and networking libraries recognize, ensuring that subprocesses and external tools automatically route traffic through the configured proxy.

Can I set different proxies for HTTP and HTTPS traffic?

The current implementation in agent_reach/cli.py stores a single proxy value that is applied to both HTTP and HTTPS protocols. While the configuration schema supports custom keys, the CLI and standard backends currently use a unified proxy URL for both protocols. Users requiring protocol-specific proxies would need to manually set HTTP_PROXY and HTTPS_PROXY in their shell environment before launching Agent Reach.

Where is the proxy configuration stored on disk?

The proxy URL is persisted through the Config class in agent_reach/config.py, which serializes values to a YAML configuration file or environment variables depending on the deployment context. The exact file path depends on the operating system and Agent Reach installation method, but the data is accessible via the Config.get("proxy") method regardless of storage backend.

How do I verify my proxy configuration is active?

Run the configure command to check the saved value, or use the install command with the --proxy flag in dry-run mode to see what would be saved. Additionally, inspect the HTTP_PROXY environment variable in your agent processes to confirm the value is being injected at runtime according to the opencli backend implementation.

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