How Agent-Reach Auto-Detects Installation Environment (Local vs Server)

Agent-Reach automatically distinguishes between local desktop and remote server environments by scoring system indicators such as SSH sessions, container files, and cloud metadata, returning "server" when the cumulative score reaches 2 or higher.

The Panniantong/Agent-Reach repository includes an intelligent environment detection system that determines whether the installation is running on a developer's laptop or a headless VPS. When executing agent-reach install --env=auto, the tool analyzes multiple system heuristics to auto-detect the installation environment without requiring manual configuration.

How the Detection Algorithm Works

The auto-detection logic relies on a weighted scoring system that inspects runtime characteristics typical of virtualized or headless machines. The private helper function _detect_environment() in agent_reach/cli.py aggregates these signals to make an accurate determination.

Environment Scoring Heuristics

Each checked condition adds points to an indicators variable according to the following criteria:

• SSH Session Detection (+2 points): Checks for the presence of SSH_CONNECTION or SSH_CLIENT environment variables, indicating an active SSH session.
• Docker or Container Environment (+2 points): Verifies existence of /.dockerenv or /run/.containerenv files that mark containerized environments.
• Graphical Display Absence (+1 point): Confirms neither DISPLAY nor WAYLAND_DISPLAY environment variables are set, suggesting a headless system.
• Cloud VM Identifiers (+2 points): Reads /sys/hypervisor/uuid or /sys/class/dmi/id/product_name for strings containing "amazon", "google", "microsoft", "digitalocean", "linode", "vultr", or "hetzner".
• Virtualization Detection (+1 point): Executes systemd-detect-virt and adds a point if the output is anything other than "none".

The Decision Threshold

After accumulating scores, the function applies a simple threshold logic as implemented in agent_reach/cli.py (lines 5555-5595):

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

Any combination yielding 2 or more points classifies the environment as a server or VPS, while scores below 2 indicate a local desktop environment.

Implementation in agent_reach/cli.py

The core detection logic resides in the _detect_environment() function within agent_reach/cli.py. The install command handler invokes this logic when the user specifies --env=auto (lines 171-226):

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

The resulting environment classification is then communicated to the user:

Environment: Server/VPS (auto-detected)

# or

Environment: Local computer (auto-detected)

Practical Usage Examples

Direct Python API Access

For debugging or custom automation scripts, you can import and call the detector directly:

from agent_reach.cli import _detect_environment

if __name__ == "__main__":
    print("Detected environment:", _detect_environment())

Running this on a typical laptop outputs local, while execution inside an SSH-connected VM or Docker container returns server.

CLI Auto-Detection

Use the --env=auto flag to let the installer decide:

# Auto-detect environment (default behavior)

$ agent-reach install --env=auto
...
Environment: Local computer (auto-detected)

# Force server mode explicitly

$ agent-reach install --env=server
...
Environment: Server/VPS (auto-detected)

Simulating Server Conditions in Testing

You can verify the detection logic by mocking server conditions:

import os
from agent_reach.cli import _detect_environment

# Simulate Docker and SSH environment

os.environ["SSH_CONNECTION"] = "127.0.0.1 22 192.168.0.2 54321"

# Create marker file (function checks existence, not content)

open("/.dockerenv", "w").close()
os.unsetenv("DISPLAY")
os.unsetenv("WAYLAND_DISPLAY")

print(_detect_environment())  # Outputs: "server"

Summary

• Agent-Reach uses a scoring-based heuristic system in agent_reach/cli.py to distinguish between local and server environments.
• The _detect_environment() function checks for SSH sessions, container files, missing displays, cloud provider identifiers, and virtualization status.
• A threshold of 2 points determines the classification: meeting or exceeding this score triggers "server" mode, while lower scores default to "local".
• The detection runs automatically when using agent-reach install --env=auto, allowing the installer to skip desktop-specific steps (like OpenCLI installation) on headless servers.

Frequently Asked Questions

What triggers Agent-Reach to detect a server environment?

Agent-Reach detects a server when the cumulative score from system heuristics reaches 2 or higher. Common triggers include running inside an SSH session (+2), presence of Docker container files like /.dockerenv (+2), or missing graphical display variables combined with cloud VM identifiers (+1 and +2 respectively).

Can I override the auto-detection if it guesses incorrectly?

Yes. While --env=auto delegates the decision to _detect_environment(), you can force a specific environment by passing --env=server or --env=local to the install command, bypassing the automatic scoring system entirely.

Where is the detection logic located in the source code?

The implementation resides in agent_reach/cli.py. Specifically, the _detect_environment() function spans approximately lines 5555-5595, and the consumption logic within the install command appears around lines 171-226, where it evaluates args.env and applies the detected value.

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