# Agent-Reach Environment Detection: Local Computer vs. Server/VPS Identification

> Discover how Agent-Reach identifies runtime environments, distinguishing between local computers and servers/VPS using a weighted heuristic system. Understand your deployment.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-11

---

**Agent-Reach uses a weighted heuristic system in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) that aggregates SSH session indicators, container markers, cloud VM metadata, and virtualization status to classify the runtime as either `"server"` or `"local"` when the cumulative score reaches 2 or higher.**

Agent-Reach is an open-source automation framework that adapts its behavior based on whether it executes on a developer workstation or a remote headless machine. The repository implements a lightweight detection mechanism that inspects environment variables, filesystem markers, and hardware identifiers to determine the execution context. Understanding how Agent-Reach environment detection works ensures you can leverage automatic configuration adjustments for proxies, interactive prompts, and health checks.

## Detection Algorithm and Heuristics

In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the private function `_detect_environment()` (lines 55-95) implements a scoring system that aggregates multiple system indicators. Each check adds a specific weight to the total score.

### SSH Session Detection

The function checks for `SSH_CONNECTION` or `SSH_CLIENT` environment variables using `os.environ.get()`. Presence of either variable indicates a remote SSH session.

Weight: **+2**

### Container Environment Markers

The code verifies the existence of `/.dockerenv` or `/run/.containerenv` via `os.path.exists()`. These files indicate the process is running inside a Docker or containerized environment.

Weight: **+2**

### Headless Display Check

The algorithm detects the absence of `DISPLAY` or `WAYLAND_DISPLAY` variables using `not os.environ.get()`. Missing display variables typically indicate a headless server rather than a GUI workstation.

Weight: **+1**

### Cloud VM Identification

The function reads `/sys/hypervisor/uuid` or `/sys/class/dmi/id/product_name` and scans the content for known cloud provider strings (`amazon`, `google`, `microsoft`, `digitalocean`, `linode`, `vultr`, `hetzner`) using `open(...).read().lower()` and `any(...)`.

Weight: **+2**

### Virtualization Detection

The code executes `systemd-detect-virt` via `subprocess.run([...])`. Any return value other than `none` indicates a virtualized environment.

Weight: **+1**

### Scoring Threshold

If the aggregate score is **2 or higher**, `_detect_environment()` returns `"server"`; otherwise, it returns `"local"`.

## Implementation in the CLI

The detection logic drives behavior in several command handlers within [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).

### Install Command

When running `agent-reach install --env=auto`, the CLI invokes `_detect_environment()` and outputs a classification message:

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

```

or

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

```

(See lines 217-225 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).)

### Watch Command

The health-check wrapper also consumes this detection to decide whether to suggest proxy configuration for headless environments.

## Practical Code Examples

### Auto-Detect via Command Line

Let the tool automatically determine the environment during installation:

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

```

### Force a Specific Environment

Override the automatic detection to treat a server as a local machine (useful for debugging):

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

```

### Programmatic Detection

Import the detection function directly in Python scripts:

```python
from agent_reach.cli import _detect_environment

env = _detect_environment()
print(f"Current environment: {env}")  # Prints "server" or "local"

```

### Unit Testing Approach

The repository verifies the behavior in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) (lines 90-104) by monkey-patching the function. You can simulate environments like this:

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

# Clear SSH indicators and simulate a Docker container

os.environ.pop("SSH_CONNECTION", None)
os.environ.pop("SSH_CLIENT", None)

# In actual tests, you would mock os.path.exists to return True for '/.dockerenv'

# For demonstration:

with open('/.dockerenv', 'w') as f:
    f.write('')

assert _detect_environment() == "server"

```

## Testing and Verification

The test suite in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) patches `_detect_environment()` to simulate both "local" and "server" outcomes, verifying that the CLI prints the correct environment classification strings. This ensures the scoring logic remains stable across different Linux distributions and cloud providers.

## Summary

- Agent-Reach environment detection relies on a weighted scoring system in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) that aggregates multiple heuristics.
- The `_detect_environment()` function inspects SSH variables, container files, display settings, cloud metadata, and virtualization status.
- A score of 2 or higher classifies the system as `"server"`; otherwise `"local"`.
- The detection affects CLI commands like `install` and `watch`, automatically adjusting proxy suggestions and interactive prompts.
- Developers can override automatic detection using the `--env` flag or import the function directly for programmatic use.

## Frequently Asked Questions

### How does Agent-Reach detect if it's running on a server versus a local machine?

Agent-Reach checks five system indicators: SSH environment variables (`SSH_CONNECTION`, `SSH_CLIENT`), Docker/container files (`/.dockerenv`, `/run/.containerenv`), display availability (`DISPLAY`, `WAYLAND_DISPLAY`), cloud provider metadata in `/sys/hypervisor/uuid` or `/sys/class/dmi/id/product_name`, and virtualization status via `systemd-detect-virt`. Each indicator carries a weight of +1 or +2, and if the total reaches 2 or higher, the system is classified as a server.

### Can I force Agent-Reach to treat my server as a local environment?

Yes. Use the `--env=local` flag with CLI commands like `install` to bypass automatic detection. This is useful for debugging or when running on specialized hardware that the heuristics might misclassify.

### Where is the environment detection logic implemented in the source code?

The core logic resides in the `_detect_environment()` function within [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 55-95). The CLI consumes this function in command handlers around lines 217-225, and tests validating the behavior exist in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) (lines 90-104).

### Why does Agent-Reach need to distinguish between local and server environments?

The distinction allows the tool to disable interactive prompts and suggest proxy configurations on headless servers, while enabling GUI-dependent features and direct user interaction on local workstations. This ensures appropriate behavior across development machines and remote VPS instances.