# How Agent-Reach Auto-Detects Installation Environment (Local vs Server)

> Agent-Reach auto-detects local vs server environments by scoring system indicators like SSH sessions and cloud metadata. Learn how it achieves this critical distinction.

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

---

**Agent-Reach automatically distinguishes between local desktop and remote server environments by scoring system indicators such as SSH sessions, container files, and cloud metadata, returning "server" when the cumulative score reaches 2 or higher.**

The Panniantong/Agent-Reach repository includes an intelligent environment detection system that determines whether the installation is running on a developer's laptop or a headless VPS. When executing `agent-reach install --env=auto`, the tool analyzes multiple system heuristics to auto-detect the installation environment without requiring manual configuration.

## How the Detection Algorithm Works

The auto-detection logic relies on a **weighted scoring system** that inspects runtime characteristics typical of virtualized or headless machines. The private helper function `_detect_environment()` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) aggregates these signals to make an accurate determination.

### Environment Scoring Heuristics

Each checked condition adds points to an `indicators` variable according to the following criteria:

- **SSH Session Detection** (+2 points): Checks for the presence of `SSH_CONNECTION` or `SSH_CLIENT` environment variables, indicating an active SSH session.
- **Docker or Container Environment** (+2 points): Verifies existence of `/.dockerenv` or `/run/.containerenv` files that mark containerized environments.
- **Graphical Display Absence** (+1 point): Confirms neither `DISPLAY` nor `WAYLAND_DISPLAY` environment variables are set, suggesting a headless system.
- **Cloud VM Identifiers** (+2 points): Reads `/sys/hypervisor/uuid` or `/sys/class/dmi/id/product_name` for strings containing `"amazon"`, `"google"`, `"microsoft"`, `"digitalocean"`, `"linode"`, `"vultr"`, or `"hetzner"`.
- **Virtualization Detection** (+1 point): Executes `systemd-detect-virt` and adds a point if the output is anything other than `"none"`.

### The Decision Threshold

After accumulating scores, the function applies a simple threshold logic as implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 5555-5595):

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

```

Any combination yielding **2 or more points** classifies the environment as a **server** or VPS, while scores below 2 indicate a **local** desktop environment.

## Implementation in agent_reach/cli.py

The core detection logic resides in the `_detect_environment()` function within [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py). The install command handler invokes this logic when the user specifies `--env=auto` (lines 171-226):

```python
env = args.env
if env == "auto":
    env = _detect_environment()

```

The resulting environment classification is then communicated to the user:

```

Environment: Server/VPS (auto-detected)

# or

Environment: Local computer (auto-detected)

```

## Practical Usage Examples

### Direct Python API Access

For debugging or custom automation scripts, you can import and call the detector directly:

```python
from agent_reach.cli import _detect_environment

if __name__ == "__main__":
    print("Detected environment:", _detect_environment())

```

Running this on a typical laptop outputs `local`, while execution inside an SSH-connected VM or Docker container returns `server`.

### CLI Auto-Detection

Use the `--env=auto` flag to let the installer decide:

```bash

# Auto-detect environment (default behavior)

$ agent-reach install --env=auto
...
Environment: Local computer (auto-detected)

# Force server mode explicitly

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

```

### Simulating Server Conditions in Testing

You can verify the detection logic by mocking server conditions:

```python
import os
from agent_reach.cli import _detect_environment

# Simulate Docker and SSH environment

os.environ["SSH_CONNECTION"] = "127.0.0.1 22 192.168.0.2 54321"

# Create marker file (function checks existence, not content)

open("/.dockerenv", "w").close()
os.unsetenv("DISPLAY")
os.unsetenv("WAYLAND_DISPLAY")

print(_detect_environment())  # Outputs: "server"

```

## Summary

- **Agent-Reach** uses a **scoring-based heuristic system** in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) to distinguish between local and server environments.
- The **`_detect_environment()`** function checks for SSH sessions, container files, missing displays, cloud provider identifiers, and virtualization status.
- A **threshold of 2 points** determines the classification: meeting or exceeding this score triggers "server" mode, while lower scores default to "local".
- The detection runs automatically when using **`agent-reach install --env=auto`**, allowing the installer to skip desktop-specific steps (like OpenCLI installation) on headless servers.

## Frequently Asked Questions

### What triggers Agent-Reach to detect a server environment?

Agent-Reach detects a server when the cumulative score from system heuristics reaches 2 or higher. Common triggers include running inside an SSH session (+2), presence of Docker container files like `/.dockerenv` (+2), or missing graphical display variables combined with cloud VM identifiers (+1 and +2 respectively).

### Can I override the auto-detection if it guesses incorrectly?

Yes. While `--env=auto` delegates the decision to `_detect_environment()`, you can force a specific environment by passing `--env=server` or `--env=local` to the install command, bypassing the automatic scoring system entirely.

### Where is the detection logic located in the source code?

The implementation resides in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py). Specifically, the `_detect_environment()` function spans approximately lines 5555-5595, and the consumption logic within the install command appears around lines 171-226, where it evaluates `args.env` and applies the detected value.