# How Agent Reach Auto-Detects Local vs Server Environments Using System Indicators

> Discover how Agent Reach auto-detects local vs server environments using SSH sessions, container markers, cloud VM identifiers, and more with its weighted scoring system.

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

---

**Agent Reach uses a weighted scoring system in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) that checks SSH sessions, container markers, display variables, cloud VM identifiers, and virtualization status to classify the runtime as either "local" or "server" when the `--env=auto` flag is used.**

Agent Reach, an open-source automation framework maintained at `Panniantong/Agent-Reach`, implements intelligent environment detection to automatically configure itself for headless servers or local workstations. The `auto-detect local vs server environment` capability eliminates manual configuration by analyzing system indicators through the `_detect_environment` helper function. This detection logic ensures that browser automation and other channel backends adapt correctly whether you are developing on a laptop or deploying to a cloud VPS.

## The Weighted Scoring Algorithm Behind Environment Detection

The `_detect_environment` function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 777–816) implements a **weighted indicator system** that aggregates evidence from five distinct system checks. Each indicator contributes a specific weight to a running counter, and if the total reaches **2 or higher**, the function returns `"server"`; otherwise, it returns `"local"`.

### SSH Session Detection

Agent Reach detects remote terminal sessions by checking for the presence of `SSH_CONNECTION` or `SSH_CLIENT` environment variables using `os.environ.get()`. When either variable is present, the function adds **+2** to the indicators counter, strongly suggesting a server environment.

### Container Environment Markers

For Docker and containerized deployments, the code checks for the existence of `/.dockerenv` or `/run/.containerenv` using `os.path.exists()`. Detection of either marker file contributes **+2** to the score, as these files are typically present only in containerized server environments.

### Display Server Availability

The function identifies headless environments by verifying the absence of graphical display variables. When `DISPLAY` and `WAYLAND_DISPLAY` are both missing from the environment (checked via `os.environ.get()`), this adds **+1** to the indicators counter, indicating a server without a GUI.

### Cloud Provider Identification

Agent Reach reads system files to identify cloud virtual machines. It examines `/sys/hypervisor/uuid` and `/sys/class/dmi/id/product_name` for substrings associated with major providers: "amazon", "google", "microsoft", "digitalocean", "linode", "vultr", and "hetzner". Each match contributes **+2** to the indicators score.

### Virtualization Detection via systemd

The code executes `systemd-detect-virt` via `subprocess.run` to determine if the system is running under virtualization. Any output other than `none` results in **+1** being added to the indicator counter, catching KVM, Xen, VMware, and other hypervisor environments.

## Implementation in agent_reach/cli.py

The core logic resides in the `_detect_environment` function, which aggregates these checks and applies the threshold:

```python
def _detect_environment():
    """Auto-detect if running on local computer or server."""
    import os
    import subprocess
    
    indicators = 0
    
    # SSH detection (+2)

    if os.environ.get("SSH_CONNECTION") or os.environ.get("SSH_CLIENT"):
        indicators += 2
    
    # Container detection (+2)

    if os.path.exists("/.dockerenv") or os.path.exists("/run/.containerenv"):
        indicators += 2
    
    # Headless detection (+1)

    if not os.environ.get("DISPLAY") and not os.environ.get("WAYLAND_DISPLAY"):
        indicators += 1
    
    # Cloud VM detection (+2 per match)

    # ... logic to read /sys files and check provider strings ...

    
    # Virtualization detection (+1)

    try:
        result = subprocess.run(["systemd-detect-virt"], capture_output=True, text=True)
        if result.stdout.strip() != "none":
            indicators += 1
    except FileNotFoundError:
        pass
    
    return "server" if indicators >= 2 else "local"

```

This implementation ensures that even a single strong indicator (like an SSH session or Docker container) is sufficient to trigger server mode, while weaker indicators (like missing displays) require additional evidence.

## Using Auto-Detection in Practice

When running the Agent Reach CLI, you can trigger automatic environment detection using the `--env=auto` flag:

```bash
$ agent-reach install --env=auto
Environment: Server/VPS (auto-detected)

```

The CLI calls `_detect_environment()` during initialization and prints the detected context based on the return value.

For programmatic use within Python scripts, you can import and call the function directly:

```python
from agent_reach.cli import _detect_environment

env = _detect_environment()
print(f"Running in a {env} environment")

# → "Running in a server environment"   # on a remote VM

# → "Running in a local environment"   # on a personal laptop

```

This allows scripts to branch logic based on the detected environment without hardcoding assumptions about the deployment target.

## Channel-Specific Configuration Based on Environment

Downstream components consume the detection results to configure appropriate backends. In [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) (lines 726–808), the XiaoHongShu channel uses the environment classification to select between headless and desktop browser configurations:

```python
if _detect_environment() == "server":
    # Set up headless Chrome for server backend

    configure_headless_browser()
else:
    # Use the local desktop browser

    configure_desktop_browser()

```

This pattern ensures that browser automation works correctly in both development and production contexts without manual intervention.

## Summary

- **Agent Reach** implements environment detection through the `_detect_environment` function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).
- The system uses a **weighted scoring algorithm** examining five indicators: SSH sessions (+2), container markers (+2), missing displays (+1), cloud VM identifiers (+2), and virtualization status (+1).
- A threshold of **≥ 2 indicators** classifies the environment as `"server"`; otherwise it defaults to `"local"`.
- The detection triggers automatically with `--env=auto` and is consumed by channel backends like XiaoHongShu to configure appropriate browser automation.
- This approach eliminates manual configuration while reliably distinguishing between developer workstations and headless cloud servers.

## Frequently Asked Questions

### How does Agent Reach determine if it's running on a server?

Agent Reach examines multiple system indicators including `SSH_CONNECTION`/`SSH_CLIENT` environment variables, `/.dockerenv` or `/run/.containerenv` files, absence of `DISPLAY`/`WAYLAND_DISPLAY` variables, cloud provider strings in `/sys/class/dmi/id/product_name`, and output from `systemd-detect-virt`. Each indicator contributes weighted points to a scoring system that classifies the environment as either `"local"` or `"server"`.

### What is the threshold for classifying an environment as "server"?

The `_detect_environment` function uses a threshold of **2 or more accumulated points**. For example, detecting an SSH session (+2) alone is sufficient to trigger server mode, while a missing display (+1) would require an additional indicator such as container detection (+2) or cloud VM identification (+2) to reach the threshold.

### Can I override the auto-detection in Agent Reach?

Yes. While the raw analysis focuses on automatic detection, the CLI accepts an `--env` parameter that allows explicit specification of the environment. When you pass `--env=local` or `--env=server`, the `_detect_environment` function is bypassed in favor of the user-specified value, though the auto-detection logic remains available for `--env=auto`.

### Which cloud providers does Agent Reach recognize?

The detection logic searches for substrings associated with major cloud providers in system DMI files, including **Amazon** (AWS), **Google** (GCP), **Microsoft** (Azure), **DigitalOcean**, **Linode**, **Vultr**, and **Hetzner**. Each identified match contributes +2 to the server indicator score, making the detection robust across popular VPS and cloud hosting platforms.