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

> Discover how Agent-Reach detects local vs server environments. Learn the auto-detection logic using weighted scoring for accurate classification.

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

---

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

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

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

```

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

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