How Agent-Reach Detects Local vs Server Environments: The Auto-Detection Scoring Algorithm

Agent-Reach uses a lightweight scoring algorithm in _detect_environment() that inspects SSH variables, container files, display availability, cloud metadata, and virtualization status to classify environments as "server" (2+ points) or "local" (<2 points).

When you invoke agent-reach install with the default --env=auto flag, the CLI automatically determines whether it’s running on a developer workstation or a headless remote server. This auto-detection capability, implemented in the Panniantong/Agent-Reach repository, inspects OS-level clues to tailor configuration advice without requiring manual input.

The Five-Point Heuristic in agent_reach/cli.py

The core detection logic resides in the _detect_environment() helper function defined at lines 975–1014 of agent_reach/cli.py. The function implements a point-based scoring system that tallies "indicator" points based on environment variables and filesystem markers typical of server environments.

SSH Sessions and Container Indicators

The function first checks for remote access and containerization signals. If the SSH_CONNECTION or SSH_CLIENT environment variables are present—indicating an active SSH session—the score increases by 2 points. Similarly, detection of container-specific files like /.dockerenv or /run/.containerenv adds another 2 points, immediately flagging most Docker and containerized environments as servers.

Headless and Cloud Infrastructure Detection

For graphical workstations, the code inspects DISPLAY and WAYLAND_DISPLAY variables. If both are absent, indicating a headless setup without a graphical display, the function adds 1 point. The logic then examines system files for cloud vendor identifiers. Reading /sys/hypervisor/uuid or /sys/class/dmi/id/product_name for strings such as amazon, google, microsoft, digitalocean, linode, vultr, or hetzner contributes 2 points per match, correctly identifying cloud VPS instances.

Virtualization Checks

Finally, the function executes systemd-detect-virt via subprocess. If the output is anything other than "none", indicating active virtualization (KVM, VMware, etc.), the score increases by 1 point.

The Classification Threshold

After aggregating all indicators, the function applies a simple threshold at the end of _detect_environment():

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

Any environment accumulating 2 or more points is classified as a server; all others are treated as local machines. This deliberate low threshold ensures that even lightly configured containers or VMs are correctly identified as server environments, while typical developer laptops with graphical displays and no SSH indicators remain classified as local.

Practical Usage Examples

You can observe this behavior when running the installer with auto-detection:

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

Alternatively, import and call the detection routine directly from Python to inspect the current environment:

from agent_reach.cli import _detect_environment

result = _detect_environment()
print(result)  # Outputs: 'local' or 'server'

The function relies only on standard environment variables and filesystem paths universally available on Linux, macOS, and typical CI containers, requiring no external dependencies.

Summary

• Agent-Reach auto-detects environments through _detect_environment() in agent_reach/cli.py (lines 975–1014).
• The scoring system assigns 2 points for SSH sessions and container files, 2 points for cloud VM identifiers, 1 point for headless displays, and 1 point for virtualization.
• A threshold of 2 points separates "server" from "local" classifications.
• The logic recognizes major cloud providers including Amazon, Google, Microsoft, DigitalOcean, Linode, Vultr, and Hetzner by inspecting /sys/class/dmi/id/product_name.

Frequently Asked Questions

What threshold determines if an environment is classified as a server?

The function returns "server" only when the indicator score reaches 2 or higher; otherwise, it returns "local". This means a single strong indicator (like an SSH session or Docker container) or a combination of weaker indicators (like headless display plus virtualization) triggers server classification.

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 environment classification.

Which cloud providers does the detection logic recognize?

According to the source code in agent_reach/cli.py, the function checks /sys/hypervisor/uuid and /sys/class/dmi/id/product_name for strings indicating amazon, google, microsoft, digitalocean, linode, vultr, or hetzner, assigning 2 points for each match detected.

Does this detection work on macOS and Windows?

The detection relies heavily on Linux-specific paths like /sys/class/dmi/id and the systemd-detect-virt command. While the SSH and display variable checks work across platforms, macOS and Windows systems typically lack the cloud metadata files, resulting in lower scores that default to "local" classification unless strong indicators like SSH are present.

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