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

> Learn how Agent Reach config command manages proxy settings for restricted networks. Securely store credentials, test with dry-run, and ensure all agent HTTP requests use your private YAML config.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-08-05

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the argument parser defines the `--proxy` option at lines 68-70:

```python

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

```bash
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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) implement this guard:

```python

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

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) handle this:

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) implement this resolution:

```python

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

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) define key-name-based masking for sensitive values:

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.