How Agent Reach Auto-Detects Local vs. Server Execution Environments

Agent Reach uses a scoring-based heuristic in the _detect_environment() helper (located in agent_reach/cli.py) that checks for SSH sessions, container files, display availability, cloud VM identifiers, and virtualization status, returning "server" if the total score reaches 2 or higher, otherwise "local".

The open-source Agent-Reach repository implements intelligent environment detection to adapt its installation behavior and tool suggestions based on whether the CLI is running on a personal workstation or a headless remote machine. When users invoke agent-reach install with the default --env=auto flag, the system automatically evaluates multiple environment indicators to determine the appropriate execution path.

The Detection Algorithm: Scoring Environment Indicators

The core logic resides in agent_reach/cli.py within the _detect_environment() function (lines 555–595). The algorithm inspects five distinct environment indicators, assigns weighted scores, and classifies the environment based on a threshold of 2 points.

Step 1: SSH Session Detection

The function first checks for the presence of SSH_CONNECTION or SSH_CLIENT environment variables. These variables indicate an active SSH session, which is a strong signal of a remote server environment.

Contribution: +2 points

# Conceptual check from the source

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

Step 2: Container Environment Checks

Next, the code probes for container-specific files including /.dockerenv and /run/.containerenv. These files exist exclusively inside Docker or OCI-compliant containers, which typically run in server or CI/CD environments.

Contribution: +2 points

Step 3: Display Availability

The absence of graphical display servers suggests a headless server. The function checks for DISPLAY and WAYLAND_DISPLAY environment variables. If neither is set, the environment likely lacks a GUI.

Contribution: +1 point

Step 4: Cloud Provider Identification

The algorithm examines system files to detect cloud virtualization. It reads /sys/hypervisor/uuid and /sys/class/dmi/id/product_name, searching for strings associated with major providers such as "amazon", "google", "microsoft", or "digitalocean".

Contribution: +2 points

Step 5: Virtualization Detection

Finally, the function executes systemd-detect-virt (if available) and checks for non‑none output. This utility identifies virtualization technologies like KVM, LXC, or Microsoft Hyper-V.

Contribution: +1 point

Final Classification

After tallying the scores, the function returns the environment type:

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

This threshold ensures that a single strong signal (such as an SSH connection) immediately classifies the environment as a server, while weaker signals (like missing display combined with containerization) also trigger server-specific behavior.

Where Detection Is Used in the CLI

The environment detection result directly influences the installation workflow in the _cmd_install function (lines 222–226 of agent_reach/cli.py). When invoked with --env=auto, the installer:

1. Calls _detect_environment() to determine the context
2. Prints a contextual message (e.g., "Environment: Server/VPS (auto-detected)")
3. Skips desktop-only channels (such as OpenCLI) on server environments

This prevents the installation of graphical or desktop-specific tools on headless servers where they cannot function.

Practical Code Examples

Directly Querying the Detection Function

You can programmatically inspect the detected environment for debugging or scripting purposes:

from agent_reach.cli import _detect_environment

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

On a local macOS or Linux workstation, this outputs local; on an AWS EC2 instance or Docker container, it returns server.

Using Auto-Detect with the CLI

The default installation command automatically triggers environment detection:

agent-reach install --env=auto

Sample output on a VPS:

Environment: Server/VPS (auto-detected)

Sample output on a local workstation:

Environment: Local computer (auto-detected)

Impact on Installation Channels

When specifying optional channels, the auto-detection affects which installers execute:

agent-reach install --env=auto --channels=twitter,opencli

If _detect_environment() returns "server", the CLI prints a notification and skips the OpenCLI installer because it requires a desktop environment, while still installing the Twitter integration.

Source Code Reference

The environment detection logic is contained entirely within the CLI module:

• agent_reach/cli.py (lines 555–595): Contains the _detect_environment() function implementing the scoring heuristic
• agent_reach/cli.py (lines 222–226): Contains the _cmd_install logic that consumes the detection result to customize installation flow

Summary

• Agent Reach automatically distinguishes between local and server environments using a scoring algorithm in _detect_environment().
• The function checks five indicators: SSH sessions (+2), container files (+2), missing displays (+1), cloud VM identifiers (+2), and virtualization status (+1).
• A score of 2 or higher triggers "server" classification; otherwise, it returns "local".
• The detection result is consumed by the agent-reach install command to skip desktop-only tools and display contextual messages.
• Users can invoke detection explicitly via Python imports or implicitly through the --env=auto CLI flag.

Frequently Asked Questions

How does Agent Reach distinguish between a local machine and a server?

Agent Reach evaluates multiple system indicators in the _detect_environment() function, including SSH environment variables, container runtime files, display server availability, and cloud provider metadata. Each indicator contributes to a cumulative score; reaching a threshold of 2 points classifies the system as a server.

What score is required to classify an environment as a server?

The algorithm requires a minimum score of 2 points to return "server". This threshold allows a single strong indicator (such as an active SSH connection worth 2 points) or a combination of weaker signals (such as missing display plus containerization) to trigger server classification.

Can I override the auto-detection in Agent Reach?

Yes. While --env=auto is the default for the install command, you can explicitly specify the environment by using --env=local or --env=server to bypass the automatic detection logic and force a specific execution path.

Which cloud providers does the detection algorithm recognize?

The detection logic identifies major cloud providers by inspecting /sys/hypervisor/uuid and /sys/class/dmi/id/product_name for strings including "amazon", "google", "microsoft", and "digitalocean", among others. This allows Agent Reach to recognize AWS EC2, Google Cloud Platform, Azure, and DigitalOcean droplets automatically.

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