How Agent Reach Automatically Detects Local vs Server Environments

Agent Reach uses a point-based scoring system in _detect_environment() that inspects OS-level clues—such as SSH sessions, container files, display variables, and cloud metadata—to classify environments as "server" (2+ points) or "local".

Agent Reach is an open-source CLI tool that adapts its behavior based on whether it is running on a developer workstation or a headless server. The repository Panniantong/Agent-Reach implements automatic environment detection through a lightweight heuristic algorithm that requires no external dependencies, enabling seamless operation across Linux, macOS, and CI containers.

How the Auto-Detection Algorithm Works

The detection logic resides in the _detect_environment() function inside agent_reach/cli.py (lines 975–1014). This function implements a scoring system that tallies indicator points based on common server characteristics. Any environment accumulating 2 or more points is classified as a server; otherwise, it returns "local".

SSH Session Detection

The function first checks for remote access indicators by inspecting environment variables.

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

Presence of either SSH_CONNECTION or SSH_CLIENT adds 2 points, strongly suggesting a remote server session.

Container Environment Checks

To identify containerized environments, the code looks for Docker-specific marker files.

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

Either /.dockerenv or /run/.containerenv contributes 2 points, flagging the environment as likely containerized infrastructure.

Display and Graphics Verification

Headless servers typically lack graphical display capabilities.

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

Absence of both DISPLAY and WAYLAND_DISPLAY environment variables adds 1 point, indicating a headless configuration common in server environments.

Cloud Provider Identification

The algorithm checks system files for cloud vendor identifiers by reading /sys/hypervisor/uuid or /sys/class/dmi/id/product_name. Matching known strings—such as amazon, google, microsoft, digitalocean, linode, vultr, or hetzner—awards 2 points per match.

Virtualization Status

Finally, the function executes systemd-detect-virt to detect hypervisors.

result = subprocess.run(["systemd-detect-virt"], capture_output=True, text=True)
if result.stdout.strip() != "none":
    indicators += 1

Any virtualization output other than "none" contributes 1 point to the server likelihood score.

Implementation in agent_reach/cli.py

The complete decision logic concludes with a simple threshold check:

def _detect_environment():
    """Auto-detect if running on local computer or server."""
    import os
    import subprocess
    
    indicators = 0
    
    if os.environ.get("SSH_CONNECTION") or os.environ.get("SSH_CLIENT"):
        indicators += 2
    if os.path.exists("/.dockerenv") or os.path.exists("/run/.containerenv"):
        indicators += 2
    if not os.environ.get("DISPLAY") and not os.environ.get("WAYLAND_DISPLAY"):
        indicators += 1
    # Cloud VM checks and systemd-detect-virt logic...

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

This implementation deliberately relies only on standard POSIX files and environment variables, ensuring compatibility without additional dependencies.

Using the Detection in Practice

When running the installer with --env=auto (the default for agent-reach install), the CLI invokes this detection automatically:

$ agent-reach install --env=auto

# Output:

Environment: Server/VPS (auto-detected)

# or

Environment: Local computer (auto-detected)

You can also import and test the detection directly in Python:

>>> from agent_reach.cli import _detect_environment
>>> _detect_environment()
'server'  # or 'local' depending on your environment

Summary

• Point-based scoring: The _detect_environment() function assigns weighted points to server-specific indicators.
• 2-point threshold: Environments scoring 2 or more points are classified as "server"; all others return "local".
• Universal compatibility: Checks rely on standard environment variables (SSH_CONNECTION, DISPLAY), filesystem markers (/.dockerenv), and system commands (systemd-detect-virt) available across Linux and macOS.
• Default behavior: The agent-reach install command uses --env=auto by default, triggering automatic detection without user intervention.
• Source location: All logic resides in agent_reach/cli.py at lines 975–1014 according to the Panniantong/Agent-Reach repository.

Frequently Asked Questions

What threshold determines if Agent Reach classifies an environment as a server?

Agent Reach uses a threshold of 2 points. The _detect_environment() function returns "server" if the cumulative indicator score is 2 or higher, and "local" for scores of 0 or 1. This threshold balances sensitivity to server characteristics while avoiding false positives from single indicators.

Can I override the automatic detection in Agent Reach?

Yes. While --env=auto is the default for the install command, you can explicitly specify the environment by passing --env=server or --env=local to bypass the heuristic detection in _detect_environment() and force a specific configuration.

Does the detection work inside Docker containers?

Yes. The algorithm specifically checks for /.dockerenv or /run/.containerenv files, adding 2 points when either exists. This ensures containerized environments are correctly identified as servers, even when running on local developer machines via Docker Desktop.

Which cloud providers does Agent Reach recognize?

The detection logic scans /sys/hypervisor/uuid and /sys/class/dmi/id/product_name for specific vendor strings including amazon, google, microsoft, digitalocean, linode, vultr, and hetzner. Matching any of these strings contributes 2 points toward the server classification.

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