Agent-Reach Environment Auto-Detection: How It Differentiates Local vs Server Machines

Agent-Reach uses a lightweight scoring system in _detect_environment() that assigns points to SSH sessions, container files, display variables, cloud VM identifiers, and virtualization status, classifying the environment as "server" when the total reaches 2 or more points, otherwise "local".

Panniantong/Agent-Reach includes an intelligent environment auto-detection system that automatically determines whether the CLI is running on a developer workstation or a headless server. This capability triggers when using --env=auto (the default for agent-reach install), enabling the tool to tailor its behavior—such as providing proxy hints for Bilibili on servers—without manual configuration.

How the Detection Algorithm Works

The classification logic resides in agent_reach/cli.py within the _detect_environment() function (lines 975-1014). Rather than relying on a single check, the implementation uses a cumulative scoring system that inspects OS-level clues typical of virtualized or headless environments.

The Scoring Threshold

The function initializes an indicators counter at zero and evaluates five distinct environment clues. After processing all checks, it applies a simple threshold:

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

Any environment scoring 2 or more points is classified as a server, while scores below 2 default to local desktop/laptop classification.

Indicator Categories and Point Values

The algorithm checks for the following conditions, adding points when detected:

• SSH Session Detection (+2 points): Checks for the presence of SSH_CONNECTION or SSH_CLIENT environment variables using os.environ.get().
• Container Detection (+2 points): Verifies existence of /.dockerenv or /run/.containerenv files that indicate Docker or containerized environments.
• Headless Display (+1 point): Confirms absence of graphical display by checking that neither DISPLAY nor WAYLAND_DISPLAY environment variables exist.
• Cloud VM Identification (+2 points per match): Reads /sys/hypervisor/uuid or /sys/class/dmi/id/product_name for known cloud vendor strings (Amazon, Google, Microsoft, DigitalOcean, Linode, Vultr, Hetzner).
• Virtualization Detection (+1 point): Executes systemd-detect-virt via subprocess and verifies output is not "none".

Source Code Implementation

The complete detection logic implemented in agent_reach/cli.py relies only on standard library modules and universal filesystem paths, ensuring compatibility across Linux, macOS, and CI containers without external dependencies.

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

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

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

    if not os.environ.get("DISPLAY") and not os.environ.get("WAYLAND_DISPLAY"):
        indicators += 1
        
    # Cloud VM and virtualization checks omitted for brevity...

    # (Checks /sys/hypervisor/uuid, /sys/class/dmi/id/product_name for cloud vendors)

    # (Runs systemd-detect-virt and adds +1 if not "none")

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

The full implementation including cloud file parsing and systemd-detect-virt execution can be found at lines 975-1014 of agent_reach/cli.py.

Practical Usage Examples

CLI Auto-Detection

When running the installer with --env=auto (the default), Agent-Reach invokes the detection automatically and prints the classification:

$ agent-reach install --env=auto

# ... output …

Environment: Server/VPS (auto-detected)

On a local workstation with graphical display and no SSH session, the output changes accordingly:

$ agent-reach install --env=auto

# ... output …

Environment: Local computer (auto-detected)

Programmatic Access

You can import and test the detection logic directly in Python to verify how your environment scores:

from agent_reach.cli import _detect_environment

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

# Output: 'local' or 'server'

Summary

• Agent-Reach environment auto-detection uses a point-based scoring system in _detect_environment() located at lines 975-1014 of agent_reach/cli.py.
• The system checks for SSH sessions (+2), container files (+2), missing display variables (+1), cloud VM identifiers (+2), and virtualization status (+1).
• A threshold of 2 points separates server environments from local machines.
• The implementation requires no external dependencies, relying solely on standard library calls and filesystem checks available on Linux, macOS, and containerized CI environments.

Frequently Asked Questions

How does Agent-Reach distinguish between a local development machine and a production server?

Agent-Reach evaluates five OS-level indicators including SSH environment variables, container filesystem markers, display server availability, cloud vendor identifiers in /sys/hypervisor/uuid and /sys/class/dmi/id/product_name, and virtualization status via systemd-detect-virt. Each indicator adds points to a cumulative score, and environments scoring 2 or higher are classified as servers, while lower scores indicate local machines.

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 classification regardless of the underlying system characteristics.

Why does the scoring system use different point values for different indicators?

The weighting reflects detection reliability. SSH sessions and container environments (2 points each) provide strong evidence of server infrastructure, while missing display variables (1 point) could potentially indicate a local headless Linux workstation. This tiered approach prevents false positives while maintaining sensitivity to genuine server characteristics.

Is the environment detection compatible with macOS and CI/CD containers?

Yes. According to the source code in agent_reach/cli.py, the detection relies only on universally available environment variables and filesystem paths. The systemd-detect-virt check is wrapped in exception handling, allowing graceful degradation on macOS or minimal containers where the utility may not exist.

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