How Agent-Reach Detects Local vs Server Environment: Auto-Detection Logic Explained

Agent-Reach uses a weighted scoring heuristic in _detect_environment() that assigns points for server-like indicators (SSH sessions, containers, headless displays, and cloud metadata) and classifies the environment as "server" if the total reaches 2 or more points, otherwise "local".

The open-source Agent-Reach CLI tool (Panniantong/Agent-Reach) automatically determines whether it's running on a developer workstation or a remote server to tailor its installation behavior. When you invoke agent-reach install with the default --env=auto flag, the tool executes an internal detection routine that inspects OS-level clues without requiring external dependencies. Understanding how agent-reach detects local vs server environment helps developers predict CLI behavior across different deployment contexts and debug misclassification issues.

The Scoring-Based Detection Algorithm

The detection logic resides in agent_reach/cli.py at lines 975–1014, implemented in the _detect_environment() helper function. Rather than relying on a single check, the function employs a weighted scoring system that tallies "indicator" points across five distinct categories of server-like characteristics.

SSH Session Detection

Remote terminal sessions receive the highest individual weight. The function checks for the presence of SSH_CONNECTION or SSH_CLIENT environment variables, adding +2 points immediately if either is detected.

Container and Virtualization Checks

Virtualized environments score heavily toward server classification. The code inspects for container files /.dockerenv or /run/.containerenv (worth +2 points), and executes systemd-detect-virt via subprocess.run() to identify hypervisors (worth +1 point if the output is not "none").

Display and Cloud Metadata

Headless systems lacking DISPLAY or WAYLAND_DISPLAY variables receive +1 point. Additionally, the function reads /sys/hypervisor/uuid and /sys/class/dmi/id/product_name for known cloud vendor strings (amazon, google, microsoft, digitalocean, linode, vultr, hetzner), awarding +2 points per match.

Implementation in _detect_environment()

The complete logic condenses into a concise decision tree. After accumulating indicators, the function returns a simple string classification based on the threshold:

def _detect_environment():
    """Auto-detect if running on local computer or server."""
    import os
    import subprocess
    
    indicators = 0
    
    if os.environ.get("SSH_CONNECTION") or os.environ.get("SSH_CLIENT"):
        indicators += 2
    if os.path.exists("/.dockerenv") or os.path.exists("/run/.containerenv"):
        indicators += 2
    if not os.environ.get("DISPLAY") and not os.environ.get("WAYLAND_DISPLAY"):
        indicators += 1
        
    # Cloud VM detection (checks /sys files for vendor strings)

    # Virtualization detection (runs systemd-detect-virt)

    
    return "server" if indicators >= 2 else "local"

This implementation requires only standard library modules (os, subprocess), ensuring portability across Linux, macOS, and CI containers without third-party dependencies.

Invoking the Detection via CLI

When executing the installer, the auto-detection activates by default:

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

Developers can also call the detection routine directly from Python to verify classification:

from agent_reach.cli import _detect_environment

result = _detect_environment()  # Returns 'local' or 'server'

print(f"Detected environment: {result}")

Why This Approach Works Across Platforms

The heuristic deliberately avoids platform-specific APIs or external dependencies. By checking universal environment variables (SSH_CLIENT, DISPLAY), standard filesystem paths (/.dockerenv), and common cloud metadata locations (/sys/class/dmi/id/product_name), the logic functions correctly on bare-metal servers, Docker containers, WSL instances, and macOS terminals. The 2-point threshold ensures conservative classification that defaults to "local" for ambiguous development environments while reliably catching headless production servers.

Summary

• Agent-Reach uses a weighted scoring system in _detect_environment() (lines 975–1014 of agent_reach/cli.py) to classify environments.
• The function checks five categories: SSH sessions (+2), container files (+2), headless displays (+1), cloud VM metadata (+2), and virtualization detection (+1).
• A threshold of 2 points distinguishes servers from local machines, ensuring conservative classification that favors "local" in ambiguous cases.
• The logic relies solely on standard library modules and universal filesystem paths, working across Linux distributions, macOS, and containerized CI environments.

Frequently Asked Questions

What triggers Agent-Reach to classify an environment as a server?

Any combination of indicators scoring 2 or more points triggers the "server" classification. Common triggers include running inside an SSH session (2 points), running inside a Docker container (2 points), or combining a headless display (1 point) with virtualization detection (1 point).

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

Yes. While --env=auto is the default for agent-reach install, you can explicitly specify --env=local or --env=server to bypass the _detect_environment() logic entirely and force a specific configuration profile.

Why does Agent-Reach check for cloud provider strings in system files?

Cloud metadata files like /sys/hypervisor/uuid contain vendor-specific strings that reliably indicate VPS or cloud instances. By awarding 2 points for these matches, Agent-Reach correctly identifies headless cloud servers even when they lack SSH connection variables or Docker containers.

Does the detection work on macOS and Windows?

The current implementation focuses on Unix-like systems (Linux and macOS) by checking for SSH_CONNECTION, DISPLAY, and systemd-detect-virt. While macOS supports the SSH and display checks, Windows environments may fall back to "local" classification unless running in WSL or containers where Linux filesystem paths are available.

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