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

Agent Reach uses a weighted scoring system in 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 (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:

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:

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

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 (lines 726–808), the XiaoHongShu channel uses the environment classification to select between headless and desktop browser configurations:

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.
• 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.

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