# How the Agent-Reach Environment Auto-Detection Algorithm Works (SSH, Docker, Display)

> Discover how Agent-Reach's environment auto-detection algorithm identifies SSH, Docker, and display settings. Learn about its weighted scoring system for accurate server or local detection.

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

---

**The environment auto-detection algorithm in Agent-Reach uses a weighted scoring system that checks for SSH sessions, Docker containers, display availability, cloud VM identifiers, and virtualization status, returning `"server"` when two or more indicators are present and `"local"` otherwise.**

When you run `agent-reach install --env=auto`, the tool automatically determines whether it is executing on a headless remote server or a local desktop machine. This detection is critical because Agent-Reach adapts its installation steps based on the runtime context. The logic resides in the private function `_detect_environment()` within the [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) file of the Panniantong/Agent-Reach repository.

## The Detection Logic in `_detect_environment()`

The algorithm implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 55-94) evaluates five distinct environmental indicators and assigns each a specific weight. It accumulates these weights into a total score and compares it against a threshold of **2**.

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

```

This binary classification allows Agent-Reach to distinguish between server environments (VPS, cloud instances, containers) and local workstations without manual configuration.

### SSH Session Detection (+2 Points)

The algorithm checks for active SSH connections by examining environment variables set by the SSH daemon.

```python
if os.environ.get("SSH_CONNECTION") or os.environ.get("SSH_CLIENT"):
    indicators += 2

```

**`SSH_CONNECTION`** and **`SSH_CLIENT`** are present when a user logs in via SSH, making this a strong signal for remote server environments.

### Docker and Container Detection (+2 Points)

Containerized environments leave specific filesystem markers that the algorithm detects.

```python
if os.path.exists("/.dockerenv") or os.path.exists("/run/.containerenv"):
    indicators += 2

```

The presence of **`/.dockerenv`** (Docker) or **`/run/.containerenv`** (Podman/other container runtimes) immediately indicates a containerized context, warranting server-mode installation.

### Display Availability Check (+1 Point)

Headless systems lack graphical display servers.

```python
if not os.environ.get("DISPLAY") and not os.environ.get("WAYLAND_DISPLAY"):
    indicators += 1

```

When both **`DISPLAY`** (X11) and **`WAYLAND_DISPLAY`** are absent, the system is likely a headless server, contributing one point to the score.

### Cloud Provider Identification (+2 Points)

The algorithm inspects system files for cloud-specific identifiers to detect VPS environments.

```python

# Checks /sys/hypervisor/uuid and /sys/class/dmi/id/product_name

# for strings like "amazon", "google", "microsoft", "digitalocean", 

# "linode", "vultr", "hetzner"

```

Each matching file adds **+2** points. The function reads these files, converts the content to lowercase, and searches for known provider strings.

### Virtualization Status (+1 Point)

Finally, the algorithm queries systemd for virtualization context.

```python

# Runs: systemd-detect-virt

# Adds +1 if output is not "none"

```

Any non-`none` response from **`systemd-detect-virt`** indicates the system is running inside a VM or container, adding one point to the total score.

## Server vs. Local Determination

After evaluating all indicators, `_detect_environment()` applies the threshold logic. If the accumulated score is **2 or higher**, the function returns `"server"`, triggering server-specific installation paths. Otherwise, it returns `"local"`, configuring Agent-Reach for desktop environments.

During installation, the CLI prints the detection result to stderr (see [`cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cli.py) lines 220-226):

```text
Environment: Server/VPS (auto-detected)

```

Or for local machines:

```text
Environment: Local computer (auto-detected)

```

## Practical Examples

You can test the detection logic directly in Python:

```python
from agent_reach.cli import _detect_environment

# Regular laptop with X11 display

print(_detect_environment())

# Output: 'local'

```

Simulate a server environment by setting SSH variables:

```bash
export SSH_CONNECTION="192.168.1.100 12345 10.0.0.1 22"
python -c "from agent_reach.cli import _detect_environment; print(_detect_environment())"

# Output: server

```

Test container detection by creating the Docker marker:

```bash
sudo touch /.dockerenv
python -c "from agent_reach.cli import _detect_environment; print(_detect_environment())"

# Output: server

```

## Implementation Files

The auto-detection logic spans three key files in the repository:

- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** – Contains the `_detect_environment()` function (lines 55-94) and the installation logic that consumes its output (lines 220-226)
- **[`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py)** – Provides the high-level API that triggers the CLI install path, indirectly invoking the detection algorithm
- **[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)** – Uses similar heuristics to verify system capabilities during diagnostics

## Summary

- The **`_detect_environment()`** function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) implements a weighted scoring algorithm to classify environments as `"server"` or `"local"`.
- SSH connections and Docker containers contribute **+2 points** each due to their strong correlation with server environments.
- Missing display variables (X11/Wayland) add **+1 point**, indicating headless operation.
- Cloud provider identifiers in `/sys/hypervisor/uuid` or `/sys/class/dmi/id/product_name` add **+2 points** when matched against known provider strings.
- The **`systemd-detect-virt`** command contributes **+1 point** if virtualization is detected.
- A threshold of **≥2 points** triggers server-mode installation, while scores below 2 default to local desktop configuration.

## Frequently Asked Questions

### How does the algorithm distinguish between a local Docker desktop and a remote server?

The algorithm relies on composite scoring rather than single indicators. A local Docker Desktop on macOS or Windows typically runs with a graphical display (`DISPLAY` variable present), which prevents the score from reaching the threshold of 2 unless SSH or cloud identifiers are also detected. Conversely, a Docker container on a remote VPS likely has SSH environment variables or cloud metadata files, pushing the score to 2 or higher and forcing server classification.

### Can I override the auto-detection if it incorrectly identifies my environment?

Yes. While the analysis focuses on the auto-detection mechanism, the CLI accepts an `--env` parameter that allows manual specification. You can bypass `_detect_environment()` entirely by using `--env=local` or `--env=server` instead of `--env=auto`, forcing the installer to use your preferred configuration regardless of the detected indicators.

### Why does the algorithm assign different weights to different indicators?

The weights reflect the reliability of each signal as a server indicator. SSH environment variables and Docker filesystem markers are definitive evidence of remote or containerized environments (hence **+2**), while missing display variables could indicate a headless local server or a TTY session (hence **+1**). Cloud VM files and virtualization detection provide supporting evidence but are weighted to avoid false positives from local virtual machines used for development.

### How reliable is the cloud provider detection across different VPS providers?

The detection reads `/sys/hypervisor/uuid` and `/sys/class/dmi/id/product_name` and searches for case-insensitive matches against a curated list including "amazon", "google", "microsoft", "digitalocean", "linode", "vultr", and "hetzner". While this covers major providers, custom or bare-metal installations may not trigger this indicator. However, the algorithm's composite nature means that cloud VMs are still correctly identified as servers through SSH connections, missing displays, or virtualization detection even if the specific provider file is absent or unrecognized.