How the Agent Reach Config Command Manages Proxy Settings for Restricted Networks

Agent Reach stores network proxy URLs in a private YAML configuration file and applies them to all agent HTTP requests, with secure handling for credentials and dry-run support for safe testing.

The agent-reach configure command provides a straightforward mechanism for deploying agents behind corporate firewalls or restricted networks that require HTTP(S) proxy traversal. This article examines the implementation details of proxy configuration management in the Panniantong/Agent-Reach repository, covering how settings are parsed, persisted, and secured.

Configuring Proxies via the CLI

Agent Reach offers two primary entry points for proxy configuration: the install command with a --proxy flag, or the standalone configure command targeting the proxy key.

Install-Time Proxy Setup

The install sub-command accepts proxy settings during initial setup. In agent_reach/cli.py, the argument parser defines the --proxy option at lines 68-70:

# From agent_reach/cli.py

parser.add_argument(
    "--proxy",
    help="HTTP(S) proxy URL for restricted network access"
)

This allows one-line installation with proxy configuration:

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

Post-Install Configuration

For existing installations, the configure sub-command provides direct key-value manipulation:

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

Both paths converge on the same persistence mechanism through the Config class.

Safe Mode and Dry-Run Handling

Before writing any configuration, the CLI checks for safe execution modes. Lines 90-95 in agent_reach/cli.py implement this guard:

# From agent_reach/cli.py

if args.dry_run or args.safe:
    print("[dry-run] Would save network proxy")
    return  # Early exit prevents disk writes

This pattern enables administrators to validate configuration changes in restricted environments without affecting production state. Example dry-run invocation:

agent-reach install --dry-run --proxy "http://proxy.example:8080"

# Output: [dry-run] Would save network proxy

Persistent Storage Implementation

When operating in normal mode, proxy values are persisted through Config.set() with backward compatibility considerations. Lines 96-98 in agent_reach/cli.py handle this:

# From agent_reach/cli.py

config.set("proxy", args.proxy)
config.set("bilibili_proxy", args.proxy)  # Legacy key for compatibility

The Config class in agent_reach/config.py implements atomic YAML writes with security hardening. Lines 45-79 contain the core persistence logic:

• Directory creation with 0o700 permissions (owner-only access)
• Symlink traversal prevention — the implementation resolves and validates all path components
• Atomic file replacement using write-to-temporary-then-rename patterns

This ensures proxy credentials (which may contain embedded passwords) are never written to world-readable locations.

Runtime Proxy Resolution

Agents retrieve configured proxies through Config.get() with environment variable fallback. Lines 58-66 in agent_reach/config.py implement this resolution:

# From agent_reach/config.py

def get(self, key: str, default=None):
    """Retrieve configuration value with environment fallback."""
    # Check explicit configuration first

    if key in self._data:
        return self._data[key]
    # Fall back to environment variable for proxy settings

    env_key = key.upper()  # "proxy" -> "PROXY"

    return os.getenv(env_key, default)

Runtime usage in agent code:

from agent_reach.config import Config

cfg = Config()
proxy = cfg.get("proxy")  # Returns saved URL, env var, or None

# Apply to HTTP requests

import requests
session = requests.Session()
if proxy:
    session.proxies = {"http": proxy, "https": proxy}

Credential Masking and Security

The Config class implements proactive credential protection. Lines 26-32 in agent_reach/config.py define key-name-based masking for sensitive values:

# From agent_reach/config.py

def to_dict(self, mask_secrets: bool = True) -> dict:
    """Export configuration with optional secret masking."""
    result = dict(self._data)
    if mask_secrets:
        for key in result:
            if "proxy" in key.lower():
                # Truncate to protocol and host only

                url = result[key]
                result[key] = url[:url.find("//")+2] + "***masked***"
    return result

This prevents accidental credential exposure in logs, debug output, or configuration dumps while preserving diagnostic utility.

Configuration File Location and Permissions

All proxy settings reside in ~/.agent-reach/config.yaml. The Config class enforces:

• Parent directory: ~/.agent-reach created with 0o700 permissions
• Configuration file: Written with 0o600 permissions (owner read-write only)
• Path validation: All components checked for symlink attacks before write operations

Summary

• Dual CLI entry points: install --proxy for setup-time configuration, configure proxy for post-installation changes
• Safe execution modes: --dry-run and --safe flags prevent unintended disk writes in production environments
• Atomic, secure persistence: Config.set() in agent_reach/config.py implements hardened YAML storage with permission enforcement
• Credential protection: Automatic masking of proxy URLs in to_dict() output prevents secret leakage
• Environment fallback: Config.get("proxy") falls back to PROXY environment variable for containerized deployments

Frequently Asked Questions

How do I verify my proxy configuration without saving it?

Use the --dry-run flag with any installation command. This prints the intended action without writing to ~/.agent-reach/config.yaml. The implementation in agent_reach/cli.py lines 90-95 handles this early exit before any Config.set() calls occur.

Can I set the proxy via environment variable instead of configuration file?

Yes. The Config.get() method in agent_reach/config.py lines 58-66 checks for an uppercase environment variable matching the key name. Setting export PROXY=http://proxy.example:8080 provides the same runtime behavior as persistent configuration, though environment variables are not written to disk.

Why does Agent Reach store proxy credentials in two configuration keys?

The code at agent_reach/cli.py lines 96-98 mirrors the proxy value to bilibili_proxy for backward compatibility with earlier agent versions. Both keys receive identical values, and the modern proxy key is preferred for new integrations.

How are proxy credentials protected in log output?

The Config.to_dict() method in agent_reach/config.py lines 26-32 detects keys containing "proxy" and replaces the value with a truncated, masked placeholder. This default behavior prevents credential exposure while allowing administrators to confirm that a proxy is configured.

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