How the Agent Reach Install Command Automatically Detects Local vs Server/VPS Environments

The Agent Reach install command uses a weighted scoring system in _detect_environment() that checks for SSH sessions, container environments, display availability, cloud provider metadata, and virtualization status to automatically classify the host as either a local computer or a server/VPS.

The agent-reach install command in the Panniantong/Agent-Reach repository simplifies deployment by adapting its behavior based on whether it is running on a desktop workstation or a remote server. When invoked with the default --env=auto flag, the CLI executes an internal heuristic analyzer located in agent_reach/cli.py to determine the runtime environment. This automatic detection ensures that server-specific configurations—such as proxy settings or headless warnings—are only presented when appropriate.

How Auto-Detection Works in agent_reach/cli.py

At the core of this functionality lies the _detect_environment() helper function defined in agent_reach/cli.py. This function implements a point-based classification system where specific environmental clues contribute weighted scores toward determining the host type.

The Scoring Algorithm

The function aggregates indicators across five distinct categories. When the cumulative score reaches 2 or greater, the environment is classified as "server"; otherwise, it returns "local".

• SSH Sessions (+2 points): Checks for the presence of SSH_CONNECTION or SSH_CLIENT environment variables, indicating a remote login session.
• Container Detection (+2 points): Detects Docker or containerized execution by verifying the existence of /.dockerenv or /run/.containerenv.
• Headless Display (+1 point): Identifies servers lacking graphical interfaces by confirming the absence of both DISPLAY and WAYLAND_DISPLAY environment variables.
• Cloud Provider Metadata (+2 points): Reads files such as /sys/hypervisor/uuid and /sys/class/dmi/id/product_name for strings matching major providers (Amazon, Google, Microsoft, DigitalOcean, Linode, Vultr, Hetzner).
• Virtualization Layer (+1 point): Executes systemd-detect-virt and adds a point if the output is anything other than "none".

Source Code Implementation

The detection logic is implemented between lines 975–1014 in agent_reach/cli.py:

def _detect_environment():
    """Auto-detect if running on local computer or server."""
    import os
    indicators = 0

    # SSH session

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

    # Docker / container

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

    # No display (headless)

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

    # Cloud VM identifiers

    for cloud_file in ["/sys/hypervisor/uuid", "/sys/class/dmi/id/product_name"]:
        if os.path.exists(cloud_file):
            try:
                with open(cloud_file) as f:
                    content = f.read().lower()
                if any(x in content for x in ["amazon", "google", "microsoft",
                                               "digitalocean", "linode", "vultr", "hetzner"]):
                    indicators += 2
            except Exception:
                pass

    # systemd-detect-virt

    try:
        import subprocess
        result = subprocess.run(["systemd-detect-virt"], capture_output=True,
                                encoding="utf-8", errors="replace", timeout=3)
        if result.returncode == 0 and result.stdout.strip() != "none":
            indicators += 1
    except Exception:
        pass

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

Integration with the Install Command

The CLI entry point for the install subcommand processes the --env argument around line 202 of agent_reach/cli.py. When users run agent-reach install without explicit environment flags, the system defaults to "auto" and invokes the detection routine:

# In _cmd_install()

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

if env == "server":
    print(f"Environment: Server/VPS (auto‑detected)")
else:
    print(f"Environment: Local computer (auto‑detected)")

This integration allows the installer to conditionally render environment-specific guidance. Headless servers receive appropriate proxy configurations, while local workstations skip server-only warnings.

Practical Usage Examples

The --env flag supports three modes: auto (default), local, and server. While auto-detection handles most scenarios correctly, you can override the behavior when working in hybrid or specialized environments.

Default auto-detection (recommended):

$ agent-reach install
Environment: Server/VPS (auto-detected)   # Or "Local computer" depending on host

Force local installation mode on a server:

$ agent-reach install --env=local

Force server-oriented installation on a workstation:

$ agent-reach install --env=server

Summary

• Agent Reach automatically differentiates between local workstations and remote servers during installation using the _detect_environment() function in agent_reach/cli.py.
• The detection algorithm employs a weighted scoring system (threshold ≥ 2) that examines SSH connections, container status, display availability, cloud metadata, and virtualization indicators.
• Five primary indicators contribute to the score: SSH sessions (+2), Docker containers (+2), headless displays (+1), cloud provider signatures (+2), and systemd-detect-virt output (+1).
• Users can override automatic detection using the --env flag with values auto, local, or server according to the source code implementation.
• The implementation gracefully handles missing files and command failures to ensure robust cross-platform behavior.

Frequently Asked Questions

How accurate is the Agent Reach install command's automatic detection?

The heuristics are highly reliable for standard configurations, correctly identifying SSH sessions, major cloud providers (AWS, GCP, Azure), and Docker containers. However, minimal VPS environments or unconventional local setups with SSH forwarding might occasionally trigger false positives, which is why the --env override flag remains available.

Can I disable automatic environment detection entirely?

Yes. Explicitly passing --env=local or --env=server to the agent-reach install command bypasses the _detect_environment() function entirely. According to the source code in agent_reach/cli.py, the auto-detection logic only executes when the --env parameter is set to auto (the default).

Why does the detection algorithm check for both DISPLAY and WAYLAND_DISPLAY?

The function verifies the absence of both DISPLAY (X11) and WAYLAND_DISPLAY (Wayland) to confirm a headless environment with no graphical session. On modern Linux distributions, checking only one might miss headless servers running alternative display protocols, so the dual verification ensures broader compatibility across different desktop environments.

Where is the environment detection logic located in the repository?

The primary detection implementation resides in agent_reach/cli.py between lines 975–1014, while the integration point that parses the --env flag and calls _detect_environment() occurs around lines 202–210 in the same file.

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