# How the Agent Reach Install Command Automatically Detects Local vs Server/VPS Environments

> Discover how the Agent Reach install command automatically detects local vs server/VPS environments using SSH, containers, cloud metadata, and more for seamless deployment.

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

---

**The Agent Reach install command uses a weighted scoring system in `_detect_environment()` that checks for SSH sessions, container environments, display availability, cloud provider metadata, and virtualization status to automatically classify the host as either a local computer or a server/VPS.**

The `agent-reach install` command in the [Panniantong/Agent-Reach](https://github.com/Panniantong/Agent-Reach) repository simplifies deployment by adapting its behavior based on whether it is running on a desktop workstation or a remote server. When invoked with the default `--env=auto` flag, the CLI executes an internal heuristic analyzer located in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) to determine the runtime environment. This automatic detection ensures that server-specific configurations—such as proxy settings or headless warnings—are only presented when appropriate.

## How Auto-Detection Works in agent_reach/cli.py

At the core of this functionality lies the **`_detect_environment()`** helper function defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py). This function implements a point-based classification system where specific environmental clues contribute weighted scores toward determining the host type.

### The Scoring Algorithm

The function aggregates indicators across five distinct categories. When the cumulative score reaches **2 or greater**, the environment is classified as `"server"`; otherwise, it returns `"local"`.

- **SSH Sessions (+2 points):** Checks for the presence of `SSH_CONNECTION` or `SSH_CLIENT` environment variables, indicating a remote login session.
- **Container Detection (+2 points):** Detects Docker or containerized execution by verifying the existence of `/.dockerenv` or `/run/.containerenv`.
- **Headless Display (+1 point):** Identifies servers lacking graphical interfaces by confirming the absence of both `DISPLAY` and `WAYLAND_DISPLAY` environment variables.
- **Cloud Provider Metadata (+2 points):** Reads files such as `/sys/hypervisor/uuid` and `/sys/class/dmi/id/product_name` for strings matching major providers (Amazon, Google, Microsoft, DigitalOcean, Linode, Vultr, Hetzner).
- **Virtualization Layer (+1 point):** Executes `systemd-detect-virt` and adds a point if the output is anything other than `"none"`.

### Source Code Implementation

The detection logic is implemented between lines 975–1014 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py):

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

    # SSH session

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

    # Docker / container

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

    # No display (headless)

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

    # Cloud VM identifiers

    for cloud_file in ["/sys/hypervisor/uuid", "/sys/class/dmi/id/product_name"]:
        if os.path.exists(cloud_file):
            try:
                with open(cloud_file) as f:
                    content = f.read().lower()
                if any(x in content for x in ["amazon", "google", "microsoft",
                                               "digitalocean", "linode", "vultr", "hetzner"]):
                    indicators += 2
            except Exception:
                pass

    # systemd-detect-virt

    try:
        import subprocess
        result = subprocess.run(["systemd-detect-virt"], capture_output=True,
                                encoding="utf-8", errors="replace", timeout=3)
        if result.returncode == 0 and result.stdout.strip() != "none":
            indicators += 1
    except Exception:
        pass

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

```

## Integration with the Install Command

The CLI entry point for the install subcommand processes the `--env` argument around line 202 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py). When users run `agent-reach install` without explicit environment flags, the system defaults to `"auto"` and invokes the detection routine:

```python

# In _cmd_install()

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

if env == "server":
    print(f"Environment: Server/VPS (auto‑detected)")
else:
    print(f"Environment: Local computer (auto‑detected)")

```

This integration allows the installer to conditionally render environment-specific guidance. Headless servers receive appropriate proxy configurations, while local workstations skip server-only warnings.

## Practical Usage Examples

The `--env` flag supports three modes: `auto` (default), `local`, and `server`. While auto-detection handles most scenarios correctly, you can override the behavior when working in hybrid or specialized environments.

**Default auto-detection (recommended):**

```bash
$ agent-reach install
Environment: Server/VPS (auto-detected)   # Or "Local computer" depending on host

```

**Force local installation mode on a server:**

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

```

**Force server-oriented installation on a workstation:**

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

```

## Summary

- **Agent Reach** automatically differentiates between local workstations and remote servers during installation using the `_detect_environment()` function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).
- The detection algorithm employs a **weighted scoring system** (threshold ≥ 2) that examines SSH connections, container status, display availability, cloud metadata, and virtualization indicators.
- **Five primary indicators** contribute to the score: SSH sessions (+2), Docker containers (+2), headless displays (+1), cloud provider signatures (+2), and `systemd-detect-virt` output (+1).
- Users can override automatic detection using the **`--env`** flag with values `auto`, `local`, or `server` according to the source code implementation.
- The implementation gracefully handles missing files and command failures to ensure robust cross-platform behavior.

## Frequently Asked Questions

### How accurate is the Agent Reach install command's automatic detection?

The heuristics are highly reliable for standard configurations, correctly identifying SSH sessions, major cloud providers (AWS, GCP, Azure), and Docker containers. However, minimal VPS environments or unconventional local setups with SSH forwarding might occasionally trigger false positives, which is why the `--env` override flag remains available.

### Can I disable automatic environment detection entirely?

Yes. Explicitly passing `--env=local` or `--env=server` to the `agent-reach install` command bypasses the `_detect_environment()` function entirely. According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the auto-detection logic only executes when the `--env` parameter is set to `auto` (the default).

### Why does the detection algorithm check for both DISPLAY and WAYLAND_DISPLAY?

The function verifies the absence of both `DISPLAY` (X11) and `WAYLAND_DISPLAY` (Wayland) to confirm a **headless environment** with no graphical session. On modern Linux distributions, checking only one might miss headless servers running alternative display protocols, so the dual verification ensures broader compatibility across different desktop environments.

### Where is the environment detection logic located in the repository?

The primary detection implementation resides in **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** between lines 975–1014, while the integration point that parses the `--env` flag and calls `_detect_environment()` occurs around lines 202–210 in the same file.