Agent-Reach Environment Detection: Local Computer vs. Server/VPS Identification

Agent-Reach uses a weighted heuristic system in agent_reach/cli.py that aggregates SSH session indicators, container markers, cloud VM metadata, and virtualization status to classify the runtime as either "server" or "local" when the cumulative score reaches 2 or higher.

Agent-Reach is an open-source automation framework that adapts its behavior based on whether it executes on a developer workstation or a remote headless machine. The repository implements a lightweight detection mechanism that inspects environment variables, filesystem markers, and hardware identifiers to determine the execution context. Understanding how Agent-Reach environment detection works ensures you can leverage automatic configuration adjustments for proxies, interactive prompts, and health checks.

Detection Algorithm and Heuristics

In agent_reach/cli.py, the private function _detect_environment() (lines 55-95) implements a scoring system that aggregates multiple system indicators. Each check adds a specific weight to the total score.

SSH Session Detection

The function checks for SSH_CONNECTION or SSH_CLIENT environment variables using os.environ.get(). Presence of either variable indicates a remote SSH session.

Weight: +2

Container Environment Markers

The code verifies the existence of /.dockerenv or /run/.containerenv via os.path.exists(). These files indicate the process is running inside a Docker or containerized environment.

Weight: +2

Headless Display Check

The algorithm detects the absence of DISPLAY or WAYLAND_DISPLAY variables using not os.environ.get(). Missing display variables typically indicate a headless server rather than a GUI workstation.

Weight: +1

Cloud VM Identification

The function reads /sys/hypervisor/uuid or /sys/class/dmi/id/product_name and scans the content for known cloud provider strings (amazon, google, microsoft, digitalocean, linode, vultr, hetzner) using open(...).read().lower() and any(...).

Weight: +2

Virtualization Detection

The code executes systemd-detect-virt via subprocess.run([...]). Any return value other than none indicates a virtualized environment.

Weight: +1

Scoring Threshold

If the aggregate score is 2 or higher, _detect_environment() returns "server"; otherwise, it returns "local".

Implementation in the CLI

The detection logic drives behavior in several command handlers within agent_reach/cli.py.

Install Command

When running agent-reach install --env=auto, the CLI invokes _detect_environment() and outputs a classification message:

Environment: Server/VPS (auto-detected)

or

Environment: Local computer (auto-detected)

(See lines 217-225 in agent_reach/cli.py.)

Watch Command

The health-check wrapper also consumes this detection to decide whether to suggest proxy configuration for headless environments.

Practical Code Examples

Auto-Detect via Command Line

Let the tool automatically determine the environment during installation:

agent-reach install --env=auto

Force a Specific Environment

Override the automatic detection to treat a server as a local machine (useful for debugging):

agent-reach install --env=local

Programmatic Detection

Import the detection function directly in Python scripts:

from agent_reach.cli import _detect_environment

env = _detect_environment()
print(f"Current environment: {env}")  # Prints "server" or "local"

Unit Testing Approach

The repository verifies the behavior in tests/test_cli.py (lines 90-104) by monkey-patching the function. You can simulate environments like this:

import os
from agent_reach.cli import _detect_environment

# Clear SSH indicators and simulate a Docker container

os.environ.pop("SSH_CONNECTION", None)
os.environ.pop("SSH_CLIENT", None)

# In actual tests, you would mock os.path.exists to return True for '/.dockerenv'

# For demonstration:

with open('/.dockerenv', 'w') as f:
    f.write('')

assert _detect_environment() == "server"

Testing and Verification

The test suite in tests/test_cli.py patches _detect_environment() to simulate both "local" and "server" outcomes, verifying that the CLI prints the correct environment classification strings. This ensures the scoring logic remains stable across different Linux distributions and cloud providers.

Summary

• Agent-Reach environment detection relies on a weighted scoring system in agent_reach/cli.py that aggregates multiple heuristics.
• The _detect_environment() function inspects SSH variables, container files, display settings, cloud metadata, and virtualization status.
• A score of 2 or higher classifies the system as "server"; otherwise "local".
• The detection affects CLI commands like install and watch, automatically adjusting proxy suggestions and interactive prompts.
• Developers can override automatic detection using the --env flag or import the function directly for programmatic use.

Frequently Asked Questions

How does Agent-Reach detect if it's running on a server versus a local machine?

Agent-Reach checks five system indicators: SSH environment variables (SSH_CONNECTION, SSH_CLIENT), Docker/container files (/.dockerenv, /run/.containerenv), display availability (DISPLAY, WAYLAND_DISPLAY), cloud provider metadata in /sys/hypervisor/uuid or /sys/class/dmi/id/product_name, and virtualization status via systemd-detect-virt. Each indicator carries a weight of +1 or +2, and if the total reaches 2 or higher, the system is classified as a server.

Can I force Agent-Reach to treat my server as a local environment?

Yes. Use the --env=local flag with CLI commands like install to bypass automatic detection. This is useful for debugging or when running on specialized hardware that the heuristics might misclassify.

Where is the environment detection logic implemented in the source code?

The core logic resides in the _detect_environment() function within agent_reach/cli.py (lines 55-95). The CLI consumes this function in command handlers around lines 217-225, and tests validating the behavior exist in tests/test_cli.py (lines 90-104).

Why does Agent-Reach need to distinguish between local and server environments?

The distinction allows the tool to disable interactive prompts and suggest proxy configurations on headless servers, while enabling GUI-dependent features and direct user interaction on local workstations. This ensures appropriate behavior across development machines and remote VPS instances.

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