# How Agent Reach Automatically Detects Local vs Server Environments

> Agent Reach automatically detects local vs server environments using OS clues and a point-based scoring system. Learn how this system accurately classifies your environment for seamless operation.

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

---

**Agent Reach uses a point-based scoring system in `_detect_environment()` that inspects OS-level clues—such as SSH sessions, container files, display variables, and cloud metadata—to classify environments as "server" (2+ points) or "local".**

Agent Reach is an open-source CLI tool that adapts its behavior based on whether it is running on a developer workstation or a headless server. The repository **Panniantong/Agent-Reach** implements automatic environment detection through a lightweight heuristic algorithm that requires no external dependencies, enabling seamless operation across Linux, macOS, and CI containers.

## How the Auto-Detection Algorithm Works

The detection logic resides in the `_detect_environment()` function inside [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 975–1014). This function implements a **scoring system** that tallies indicator points based on common server characteristics. Any environment accumulating **2 or more points** is classified as a server; otherwise, it returns `"local"`.

### SSH Session Detection

The function first checks for remote access indicators by inspecting environment variables.

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

```

Presence of either `SSH_CONNECTION` or `SSH_CLIENT` adds **2 points**, strongly suggesting a remote server session.

### Container Environment Checks

To identify containerized environments, the code looks for Docker-specific marker files.

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

```

Either `/.dockerenv` or `/run/.containerenv` contributes **2 points**, flagging the environment as likely containerized infrastructure.

### Display and Graphics Verification

Headless servers typically lack graphical display capabilities.

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

```

Absence of both `DISPLAY` and `WAYLAND_DISPLAY` environment variables adds **1 point**, indicating a headless configuration common in server environments.

### Cloud Provider Identification

The algorithm checks system files for cloud vendor identifiers by reading `/sys/hypervisor/uuid` or `/sys/class/dmi/id/product_name`. Matching known strings—such as *amazon*, *google*, *microsoft*, *digitalocean*, *linode*, *vultr*, or *hetzner*—awards **2 points** per match.

### Virtualization Status

Finally, the function executes `systemd-detect-virt` to detect hypervisors.

```python
result = subprocess.run(["systemd-detect-virt"], capture_output=True, text=True)
if result.stdout.strip() != "none":
    indicators += 1

```

Any virtualization output other than `"none"` contributes **1 point** to the server likelihood score.

## Implementation in agent_reach/cli.py

The complete decision logic concludes with a simple threshold check:

```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 checks and systemd-detect-virt logic...

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

```

This implementation deliberately relies only on standard POSIX files and environment variables, ensuring compatibility without additional dependencies.

## Using the Detection in Practice

When running the installer with `--env=auto` (the default for `agent-reach install`), the CLI invokes this detection automatically:

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

# Output:

Environment: Server/VPS (auto-detected)

# or

Environment: Local computer (auto-detected)

```

You can also import and test the detection directly in Python:

```python
>>> from agent_reach.cli import _detect_environment
>>> _detect_environment()
'server'  # or 'local' depending on your environment

```

## Summary

- **Point-based scoring**: The `_detect_environment()` function assigns weighted points to server-specific indicators.
- **2-point threshold**: Environments scoring 2 or more points are classified as `"server"`; all others return `"local"`.
- **Universal compatibility**: Checks rely on standard environment variables (`SSH_CONNECTION`, `DISPLAY`), filesystem markers (`/.dockerenv`), and system commands (`systemd-detect-virt`) available across Linux and macOS.
- **Default behavior**: The `agent-reach install` command uses `--env=auto` by default, triggering automatic detection without user intervention.
- **Source location**: All logic resides in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) at lines 975–1014 according to the Panniantong/Agent-Reach repository.

## Frequently Asked Questions

### What threshold determines if Agent Reach classifies an environment as a server?

Agent Reach uses a threshold of **2 points**. The `_detect_environment()` function returns `"server"` if the cumulative indicator score is 2 or higher, and `"local"` for scores of 0 or 1. This threshold balances sensitivity to server characteristics while avoiding false positives from single indicators.

### Can I override the automatic detection in Agent Reach?

Yes. While `--env=auto` is the default for the install command, you can explicitly specify the environment by passing `--env=server` or `--env=local` to bypass the heuristic detection in `_detect_environment()` and force a specific configuration.

### Does the detection work inside Docker containers?

Yes. The algorithm specifically checks for `/.dockerenv` or `/run/.containerenv` files, adding **2 points** when either exists. This ensures containerized environments are correctly identified as servers, even when running on local developer machines via Docker Desktop.

### Which cloud providers does Agent Reach recognize?

The detection logic scans `/sys/hypervisor/uuid` and `/sys/class/dmi/id/product_name` for specific vendor strings including **amazon**, **google**, **microsoft**, **digitalocean**, **linode**, **vultr**, and **hetzner**. Matching any of these strings contributes **2 points** toward the server classification.