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

> Agent-Reach automatically detects local vs server environments using a unique scoring algorithm. Learn how it inspects SSH variables, container files, and more.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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()`:

```python
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:

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

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.