How Agent Reach Detects Local vs. Server Environments: Environment Detection Logic Explained

Agent Reach detects local vs. server deployments using a scoring system in _detect_environment() that checks five environment clues—SSH sessions, container files, display variables, cloud VM identifiers, and virtualization status—classifying as "server" when two or more indicators are present.

Agent Reach needs to distinguish between local workstation and server/VPS deployments to adapt its installation behavior appropriately. The detection logic lives in agent_reach/cli.py and is invoked automatically when users pass --env=auto to the install command. This article breaks down exactly how the _detect_environment() function works, what signals it evaluates, and how the scoring system determines the final classification.

The Five Environment Detection Signals

The _detect_environment() function (lines 1122–1161 in agent_reach/cli.py) examines five distinct environment characteristics. Each contributes to an indicators counter that drives the final decision.

1. SSH Session Detection

The function first checks for SSH-related environment variables:

os.environ.get("SSH_CONNECTION") or os.environ.get("SSH_CLIENT")

Why this matters: These variables are set when a process is launched through an SSH tunnel—common for remote server access but rare on local workstations. Presence of either variable adds +2 to the indicators score.

2. Container Environment Detection

The code looks for the existence of container marker files:

os.path.exists("/.dockerenv") or os.path.exists("/run/.containerenv")

Why this matters: Docker and OCI-compatible runtimes create these files inside containers. Server deployments frequently use containerization, while local development may not. A container detection adds +2 to the score.

3. Headless Display Check

The function verifies whether graphical display variables are absent:

not os.environ.get("DISPLAY") and not os.environ.get("WAYLAND_DISPLAY")

Why this matters: Servers typically run headless without X11 or Wayland displays. Missing both variables suggests a server environment and contributes +1 to the indicators count.

4. Cloud VM Identifier Parsing

The detection logic reads two sysfs files for cloud provider signatures:

# Checks /sys/hypervisor/uuid and /sys/class/dmi/id/product_name

# for strings like: amazon, google, microsoft, digitalocean,

# linode, vultr, hetzner

Why this matters: Major cloud providers embed identifying strings in these kernel-exposed files. Detecting any provider name adds +2 to the score, strongly indicating a virtualized server instance.

5. systemd-detect-virt Execution

Finally, the function executes a system utility:

subprocess.run(["systemd-detect-virt"], ...)

# Checks if output is NOT "none"

Why this matters: This tool reports kernel-level virtualization (KVM, LXC, VMware, etc.). A non-"none" result confirms virtualized hardware typical of server deployments, adding +1 to indicators.

The Scoring Threshold and Final Classification

After collecting indicators, _detect_environment() applies a simple threshold:

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

Any combination of two or more positive signals triggers server classification. For example:

• Docker container (+2) + no display (+1) = server (3 indicators)
• SSH session (+2) alone = local (insufficient—needs one more signal)
• Cloud VM (+2) + systemd-detect-virt (+1) = server (3 indicators)

This conservative approach avoids false positives while reliably identifying server-like environments.

Where Detection Results Are Used

The _cmd_install function (lines 274–284 in agent_reach/cli.py) consumes the detection result:

env = _detect_environment()  # When --env=auto is passed

According to the Agent Reach source code, this classification influences:

• OpenCLI channel filtering: Skipping GUI-dependent channels on headless servers
• Installation tips: Providing server-specific guidance when appropriate

Practical Usage Examples

Direct Detection Invocation

from agent_reach.cli import _detect_environment

env = _detect_environment()
print(f"Running in a {env} environment")

# → "Running in a server environment"

Auto-Detection with Installation

# Let Agent Reach automatically detect and adapt

agent-reach install --env=auto

Testing with Mocked Detection

def test_cli_auto_detect(monkeypatch):
    # Force server detection for test scenarios

    monkeypatch.setattr(cli, "_detect_environment", lambda: "server")
    result = cli._detect_environment()
    assert result == "server"

Summary

• _detect_environment() in agent_reach/cli.py (lines 1122–1161) implements five distinct environment checks
• Scoring system: SSH (+2), container (+2), no display (+1), cloud VM (+2), virtualization (+1)
• Threshold: Two or more indicators classifies as "server"; otherwise "local"
• Primary use case: The _cmd_install function uses this for --env=auto installations
• Design philosophy: Conservative multi-signal approach reduces false positives

Frequently Asked Questions

How reliable is the environment detection in Agent Reach?

The detection is designed to be conservative rather than aggressive. Requiring two or more independent signals minimizes false positives—no single indicator triggers server mode alone. However, edge cases exist: a local workstation with Docker Desktop and no display running might briefly score as server-like. Users can always override with --env=local or --env=server if auto-detection misclassifies.

Can I force a specific environment without auto-detection?

Yes. The --env parameter accepts explicit values. Use agent-reach install --env=server to force server-mode installation regardless of detected signals, or --env=local to enforce workstation behavior. Auto-detection only activates with --env=auto or when the flag is omitted and defaults apply.

Why does Agent Reach check both Docker and cloud VM indicators?

Container detection (/.dockerenv) and cloud VM parsing (/sys/hypervisor/uuid) serve complementary purposes. Docker containers can run anywhere—local laptops, on-premise servers, or cloud VMs. Cloud VM detection catches virtual machines that may not use containers. Together they cover the two dominant server deployment patterns: bare VM instances and containerized workloads.

What happens if systemd-detect-virt is not available?

The implementation wraps this check in error handling. If the command fails or returns unexpected output, it simply contributes zero indicators rather than crashing. The detection gracefully degrades to rely on the four remaining signals. Systems without systemd (Alpine Linux, some BSD variants) still classify correctly via SSH, container, display, and cloud VM checks.

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