# How Agent Reach Handles Proxy Configuration for Restricted Network Environments

> Agent Reach simplifies proxy configuration for restricted networks by centralizing settings and exporting them as HTTP_PROXY and HTTPS_PROXY environment variables for agents.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the argument is defined with a default empty string to handle optional proxy injection:

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

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) around line 317, the CLI accepts:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the `Config` class explicitly lists `proxy` as an allowed configuration key at line 114:

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

```bash

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

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