How the Agent-Reach Environment Auto-Detection Algorithm Works (SSH, Docker, Display)

The environment auto-detection algorithm in Agent-Reach uses a weighted scoring system that checks for SSH sessions, Docker containers, display availability, cloud VM identifiers, and virtualization status, returning "server" when two or more indicators are present and "local" otherwise.

When you run agent-reach install --env=auto, the tool automatically determines whether it is executing on a headless remote server or a local desktop machine. This detection is critical because Agent-Reach adapts its installation steps based on the runtime context. The logic resides in the private function _detect_environment() within the agent_reach/cli.py file of the Panniantong/Agent-Reach repository.

The Detection Logic in _detect_environment()

The algorithm implemented in agent_reach/cli.py (lines 55-94) evaluates five distinct environmental indicators and assigns each a specific weight. It accumulates these weights into a total score and compares it against a threshold of 2.

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

This binary classification allows Agent-Reach to distinguish between server environments (VPS, cloud instances, containers) and local workstations without manual configuration.

SSH Session Detection (+2 Points)

The algorithm checks for active SSH connections by examining environment variables set by the SSH daemon.

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

SSH_CONNECTION and SSH_CLIENT are present when a user logs in via SSH, making this a strong signal for remote server environments.

Docker and Container Detection (+2 Points)

Containerized environments leave specific filesystem markers that the algorithm detects.

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

The presence of /.dockerenv (Docker) or /run/.containerenv (Podman/other container runtimes) immediately indicates a containerized context, warranting server-mode installation.

Display Availability Check (+1 Point)

Headless systems lack graphical display servers.

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

When both DISPLAY (X11) and WAYLAND_DISPLAY are absent, the system is likely a headless server, contributing one point to the score.

Cloud Provider Identification (+2 Points)

The algorithm inspects system files for cloud-specific identifiers to detect VPS environments.

# Checks /sys/hypervisor/uuid and /sys/class/dmi/id/product_name

# for strings like "amazon", "google", "microsoft", "digitalocean", 

# "linode", "vultr", "hetzner"

Each matching file adds +2 points. The function reads these files, converts the content to lowercase, and searches for known provider strings.

Virtualization Status (+1 Point)

Finally, the algorithm queries systemd for virtualization context.

# Runs: systemd-detect-virt

# Adds +1 if output is not "none"

Any non-none response from systemd-detect-virt indicates the system is running inside a VM or container, adding one point to the total score.

Server vs. Local Determination

After evaluating all indicators, _detect_environment() applies the threshold logic. If the accumulated score is 2 or higher, the function returns "server", triggering server-specific installation paths. Otherwise, it returns "local", configuring Agent-Reach for desktop environments.

During installation, the CLI prints the detection result to stderr (see cli.py lines 220-226):

Environment: Server/VPS (auto-detected)

Or for local machines:

Environment: Local computer (auto-detected)

Practical Examples

You can test the detection logic directly in Python:

from agent_reach.cli import _detect_environment

# Regular laptop with X11 display

print(_detect_environment())

# Output: 'local'

Simulate a server environment by setting SSH variables:

export SSH_CONNECTION="192.168.1.100 12345 10.0.0.1 22"
python -c "from agent_reach.cli import _detect_environment; print(_detect_environment())"

# Output: server

Test container detection by creating the Docker marker:

sudo touch /.dockerenv
python -c "from agent_reach.cli import _detect_environment; print(_detect_environment())"

# Output: server

Implementation Files

The auto-detection logic spans three key files in the repository:

• agent_reach/cli.py – Contains the _detect_environment() function (lines 55-94) and the installation logic that consumes its output (lines 220-226)
• agent_reach/core.py – Provides the high-level API that triggers the CLI install path, indirectly invoking the detection algorithm
• agent_reach/doctor.py – Uses similar heuristics to verify system capabilities during diagnostics

Summary

• The _detect_environment() function in agent_reach/cli.py implements a weighted scoring algorithm to classify environments as "server" or "local".
• SSH connections and Docker containers contribute +2 points each due to their strong correlation with server environments.
• Missing display variables (X11/Wayland) add +1 point, indicating headless operation.
• Cloud provider identifiers in /sys/hypervisor/uuid or /sys/class/dmi/id/product_name add +2 points when matched against known provider strings.
• The systemd-detect-virt command contributes +1 point if virtualization is detected.
• A threshold of ≥2 points triggers server-mode installation, while scores below 2 default to local desktop configuration.

Frequently Asked Questions

How does the algorithm distinguish between a local Docker desktop and a remote server?

The algorithm relies on composite scoring rather than single indicators. A local Docker Desktop on macOS or Windows typically runs with a graphical display (DISPLAY variable present), which prevents the score from reaching the threshold of 2 unless SSH or cloud identifiers are also detected. Conversely, a Docker container on a remote VPS likely has SSH environment variables or cloud metadata files, pushing the score to 2 or higher and forcing server classification.

Can I override the auto-detection if it incorrectly identifies my environment?

Yes. While the analysis focuses on the auto-detection mechanism, the CLI accepts an --env parameter that allows manual specification. You can bypass _detect_environment() entirely by using --env=local or --env=server instead of --env=auto, forcing the installer to use your preferred configuration regardless of the detected indicators.

Why does the algorithm assign different weights to different indicators?

The weights reflect the reliability of each signal as a server indicator. SSH environment variables and Docker filesystem markers are definitive evidence of remote or containerized environments (hence +2), while missing display variables could indicate a headless local server or a TTY session (hence +1). Cloud VM files and virtualization detection provide supporting evidence but are weighted to avoid false positives from local virtual machines used for development.

How reliable is the cloud provider detection across different VPS providers?

The detection reads /sys/hypervisor/uuid and /sys/class/dmi/id/product_name and searches for case-insensitive matches against a curated list including "amazon", "google", "microsoft", "digitalocean", "linode", "vultr", and "hetzner". While this covers major providers, custom or bare-metal installations may not trigger this indicator. However, the algorithm's composite nature means that cloud VMs are still correctly identified as servers through SSH connections, missing displays, or virtualization detection even if the specific provider file is absent or unrecognized.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}