# Agent-Reach Environment Auto-Detection: How It Differentiates Local vs Server Machines

> Agent-Reach auto-detection distinguishes local from server environments using a scoring system for SSH, containers, display variables, and cloud VM identifiers. Learn how it works.

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

---

**Agent-Reach uses a lightweight scoring system in `_detect_environment()` that assigns points to SSH sessions, container files, display variables, cloud VM identifiers, and virtualization status, classifying the environment as "server" when the total reaches 2 or more points, otherwise "local".**

Panniantong/Agent-Reach includes an intelligent **environment auto-detection** system that automatically determines whether the CLI is running on a developer workstation or a headless server. This capability triggers when using `--env=auto` (the default for `agent-reach install`), enabling the tool to tailor its behavior—such as providing proxy hints for Bilibili on servers—without manual configuration.

## How the Detection Algorithm Works

The classification 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 975-1014). Rather than relying on a single check, the implementation uses a cumulative scoring system that inspects OS-level clues typical of virtualized or headless environments.

### The Scoring Threshold

The function initializes an `indicators` counter at zero and evaluates five distinct environment clues. After processing all checks, it applies a simple threshold:

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

```

Any environment scoring **2 or more points** is classified as a *server*, while scores below 2 default to *local* desktop/laptop classification.

### Indicator Categories and Point Values

The algorithm checks for the following conditions, adding points when detected:

- **SSH Session Detection (+2 points)**: Checks for the presence of `SSH_CONNECTION` or `SSH_CLIENT` environment variables using `os.environ.get()`.
- **Container Detection (+2 points)**: Verifies existence of `/.dockerenv` or `/run/.containerenv` files that indicate Docker or containerized environments.
- **Headless Display (+1 point)**: Confirms absence of graphical display by checking that neither `DISPLAY` nor `WAYLAND_DISPLAY` environment variables exist.
- **Cloud VM Identification (+2 points per match)**: Reads `/sys/hypervisor/uuid` or `/sys/class/dmi/id/product_name` for known cloud vendor strings (Amazon, Google, Microsoft, DigitalOcean, Linode, Vultr, Hetzner).
- **Virtualization Detection (+1 point)**: Executes `systemd-detect-virt` via subprocess and verifies output is not `"none"`.

## Source Code Implementation

The complete detection logic implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) relies only on standard library modules and universal filesystem paths, ensuring compatibility across Linux, macOS, and CI containers without external dependencies.

```python
def _detect_environment():
    """Auto-detect if running on local computer or server."""
    import os
    indicators = 0                     
    
    # SSH session detection

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

    if os.path.exists("/.dockerenv") or os.path.exists("/run/.containerenv"):
        indicators += 2
        
    # Headless display check

    if not os.environ.get("DISPLAY") and not os.environ.get("WAYLAND_DISPLAY"):
        indicators += 1
        
    # Cloud VM and virtualization checks omitted for brevity...

    # (Checks /sys/hypervisor/uuid, /sys/class/dmi/id/product_name for cloud vendors)

    # (Runs systemd-detect-virt and adds +1 if not "none")

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

```

The full implementation including cloud file parsing and `systemd-detect-virt` execution can be found at lines 975-1014 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).

## Practical Usage Examples

### CLI Auto-Detection

When running the installer with `--env=auto` (the default), Agent-Reach invokes the detection automatically and prints the classification:

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

# ... output …

Environment: Server/VPS (auto-detected)

```

On a local workstation with graphical display and no SSH session, the output changes accordingly:

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

# ... output …

Environment: Local computer (auto-detected)

```

### Programmatic Access

You can import and test the detection logic directly in Python to verify how your environment scores:

```python
from agent_reach.cli import _detect_environment

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

# Output: 'local' or 'server'

```

## Summary

- **Agent-Reach environment auto-detection** uses a point-based scoring system in `_detect_environment()` located at lines 975-1014 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).
- The system checks for SSH sessions (+2), container files (+2), missing display variables (+1), cloud VM identifiers (+2), and virtualization status (+1).
- A threshold of **2 points** separates server environments from local machines.
- The implementation requires no external dependencies, relying solely on standard library calls and filesystem checks available on Linux, macOS, and containerized CI environments.

## Frequently Asked Questions

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

Agent-Reach evaluates five OS-level indicators including SSH environment variables, container filesystem markers, display server availability, cloud vendor identifiers in `/sys/hypervisor/uuid` and `/sys/class/dmi/id/product_name`, and virtualization status via `systemd-detect-virt`. Each indicator adds points to a cumulative score, and environments scoring 2 or higher are classified as servers, while lower scores indicate local machines.

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

Yes. While `--env=auto` is the default for `agent-reach install`, you can explicitly specify `--env=local` or `--env=server` to bypass the `_detect_environment()` logic entirely and force a specific classification regardless of the underlying system characteristics.

### Why does the scoring system use different point values for different indicators?

The weighting reflects detection reliability. SSH sessions and container environments (2 points each) provide strong evidence of server infrastructure, while missing display variables (1 point) could potentially indicate a local headless Linux workstation. This tiered approach prevents false positives while maintaining sensitivity to genuine server characteristics.

### Is the environment detection compatible with macOS and CI/CD containers?

Yes. According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the detection relies only on universally available environment variables and filesystem paths. The `systemd-detect-virt` check is wrapped in exception handling, allowing graceful degradation on macOS or minimal containers where the utility may not exist.