# How Agent Reach Auto-Detects Local vs. Server Execution Environments

> Agent Reach auto-detects local or server execution environments using a scoring heuristic. Discover how it identifies SSH, containers, cloud VMs, and more.

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

---

**Agent Reach uses a scoring-based heuristic in the `_detect_environment()` helper (located in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)) that checks for SSH sessions, container files, display availability, cloud VM identifiers, and virtualization status, returning `"server"` if the total score reaches 2 or higher, otherwise `"local"`.**

The open-source **Agent-Reach** repository implements intelligent environment detection to adapt its installation behavior and tool suggestions based on whether the CLI is running on a personal workstation or a headless remote machine. When users invoke `agent-reach install` with the default `--env=auto` flag, the system automatically evaluates multiple environment indicators to determine the appropriate execution path.

## The Detection Algorithm: Scoring Environment Indicators

The core logic resides in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) within the `_detect_environment()` function (lines 555–595). The algorithm inspects five distinct environment indicators, assigns weighted scores, and classifies the environment based on a threshold of **2 points**.

### Step 1: SSH Session Detection

The function first checks for the presence of `SSH_CONNECTION` or `SSH_CLIENT` environment variables. These variables indicate an active SSH session, which is a strong signal of a remote server environment.

**Contribution:** +2 points

```python

# Conceptual check from the source

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

```

### Step 2: Container Environment Checks

Next, the code probes for container-specific files including `/.dockerenv` and `/run/.containerenv`. These files exist exclusively inside Docker or OCI-compliant containers, which typically run in server or CI/CD environments.

**Contribution:** +2 points

### Step 3: Display Availability

The absence of graphical display servers suggests a headless server. The function checks for `DISPLAY` and `WAYLAND_DISPLAY` environment variables. If neither is set, the environment likely lacks a GUI.

**Contribution:** +1 point

### Step 4: Cloud Provider Identification

The algorithm examines system files to detect cloud virtualization. It reads `/sys/hypervisor/uuid` and `/sys/class/dmi/id/product_name`, searching for strings associated with major providers such as `"amazon"`, `"google"`, `"microsoft"`, or `"digitalocean"`.

**Contribution:** +2 points

### Step 5: Virtualization Detection

Finally, the function executes `systemd-detect-virt` (if available) and checks for non‑none output. This utility identifies virtualization technologies like KVM, LXC, or Microsoft Hyper-V.

**Contribution:** +1 point

### Final Classification

After tallying the scores, the function returns the environment type:

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

```

This threshold ensures that a single strong signal (such as an SSH connection) immediately classifies the environment as a server, while weaker signals (like missing display combined with containerization) also trigger server-specific behavior.

## Where Detection Is Used in the CLI

The environment detection result directly influences the installation workflow in the `_cmd_install` function (lines 222–226 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)). When invoked with `--env=auto`, the installer:

1. Calls `_detect_environment()` to determine the context
2. Prints a contextual message (e.g., "Environment: Server/VPS (auto-detected)")
3. Skips desktop-only channels (such as OpenCLI) on server environments

This prevents the installation of graphical or desktop-specific tools on headless servers where they cannot function.

## Practical Code Examples

### Directly Querying the Detection Function

You can programmatically inspect the detected environment for debugging or scripting purposes:

```python
from agent_reach.cli import _detect_environment

env = _detect_environment()
print(f"Detected environment: {env}")

```

On a local macOS or Linux workstation, this outputs `local`; on an AWS EC2 instance or Docker container, it returns `server`.

### Using Auto-Detect with the CLI

The default installation command automatically triggers environment detection:

```bash
agent-reach install --env=auto

```

**Sample output on a VPS:**

```

Environment: Server/VPS (auto-detected)

```

**Sample output on a local workstation:**

```

Environment: Local computer (auto-detected)

```

### Impact on Installation Channels

When specifying optional channels, the auto-detection affects which installers execute:

```bash
agent-reach install --env=auto --channels=twitter,opencli

```

If `_detect_environment()` returns `"server"`, the CLI prints a notification and skips the OpenCLI installer because it requires a desktop environment, while still installing the Twitter integration.

## Source Code Reference

The environment detection logic is contained entirely within the CLI module:

- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** (lines 555–595): Contains the `_detect_environment()` function implementing the scoring heuristic
- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** (lines 222–226): Contains the `_cmd_install` logic that consumes the detection result to customize installation flow

## Summary

- **Agent Reach** automatically distinguishes between local and server environments using a scoring algorithm in `_detect_environment()`.
- The function checks five indicators: SSH sessions (+2), container files (+2), missing displays (+1), cloud VM identifiers (+2), and virtualization status (+1).
- A score of **2 or higher** triggers `"server"` classification; otherwise, it returns `"local"`.
- The detection result is consumed by the `agent-reach install` command to skip desktop-only tools and display contextual messages.
- Users can invoke detection explicitly via Python imports or implicitly through the `--env=auto` CLI flag.

## Frequently Asked Questions

### How does Agent Reach distinguish between a local machine and a server?

Agent Reach evaluates multiple system indicators in the `_detect_environment()` function, including SSH environment variables, container runtime files, display server availability, and cloud provider metadata. Each indicator contributes to a cumulative score; reaching a threshold of 2 points classifies the system as a server.

### What score is required to classify an environment as a server?

The algorithm requires a minimum score of **2 points** to return `"server"`. This threshold allows a single strong indicator (such as an active SSH connection worth 2 points) or a combination of weaker signals (such as missing display plus containerization) to trigger server classification.

### Can I override the auto-detection in Agent Reach?

Yes. While `--env=auto` is the default for the install command, you can explicitly specify the environment by using `--env=local` or `--env=server` to bypass the automatic detection logic and force a specific execution path.

### Which cloud providers does the detection algorithm recognize?

The detection logic identifies major cloud providers by inspecting `/sys/hypervisor/uuid` and `/sys/class/dmi/id/product_name` for strings including `"amazon"`, `"google"`, `"microsoft"`, and `"digitalocean"`, among others. This allows Agent Reach to recognize AWS EC2, Google Cloud Platform, Azure, and DigitalOcean droplets automatically.