How the Agent-Reach Install Command Detects System Dependencies

The agent-reach install command detects missing system tools—including GitHub CLI, Node.js, and npm—and installs them automatically using platform-specific logic, while --dry-run and --safe flags let you preview or restrict system changes.

The agent-reach install command in the Panniantong/Agent-Reach repository is a deterministic one-shot installer designed to prepare a host for Agent Reach channels. Understanding how its system dependency detection works helps operators decide when to use automatic installation versus guarded modes on local workstations or remote servers. The core logic lives in agent_reach/cli.py, where environment sensing and dependency verification run before any system modifications occur.

High-Level Execution Flow

The installation process defined in _cmd_install inside agent_reach/cli.py follows a strict sequence before it modifies the host:

1. Parse user flags such as --dry-run, --safe, --env, and --channels.
2. Detect the execution environment by calling _detect_environment(). This routine counts indicators like SSH variables, Docker markers, headless displays, cloud VM identifiers, and output from systemd-detect-virt. If two or more server-like indicators appear, it returns "server"; otherwise it returns "local" (see lines 975–1014).
3. Select an installer routine based on flags. Normal runs invoke _install_system_deps(), while --dry-run triggers _install_system_deps_dryrun and --safe triggers _install_system_deps_safe.
4. Detect and install core system dependencies inside _install_system_deps() (lines 484–560).
5. Run optional channel installers only when the user passes --channels and the run is not in dry-run or safe mode (see lines 80–89 of _cmd_install).
6. Extract browser cookies automatically for channels that require them—such as Twitter, Xueqiu, or Bilibili—via agent_reach.cookie_extract.configure_from_browser, but only on local machines and outside safe/dry-run modes (lines 52–74 of _cmd_install).
7. Verify health by calling doctor.check_all from agent_reach/doctor.py and printing a concise report.

Core System Dependency Detection in _install_system_deps

Inside agent_reach/cli.py, the _install_system_deps function (lines 484–560) performs three independent checks to confirm the host can support Agent Reach.

GitHub CLI (gh) Detection

The installer uses shutil.which("gh") to verify that the GitHub CLI is on the system PATH. If the binary is absent, the script attempts a platform-specific installation: it prefers APT on Linux distributions and Homebrew on macOS. When automated installation is not possible, it prints user-friendly fallback URLs so the operator can complete the step manually (see lines 94–124 of _install_system_deps).

Node.js and npm Verification

Agent Reach requires both the node and npm binaries. The function calls shutil.which("node") and shutil.which("npm") to confirm their presence. If either binary is missing, the installer downloads the NodeSource setup script, executes it, and runs apt-get install nodejs. Any errors are caught and surfaced as a concise fallback message instead of a stack trace (see lines 141–172 of _install_system_deps).

undici npm Package Check

Because some channels rely on Node.js fetch with proxy support, the installer confirms that the undici package is available globally. It runs npm root -g to locate the global package directory and checks for undici/index.js. If the file is missing, it executes npm install -g undici to add the package (see lines 173–180 of _install_system_deps).

Environment Detection and Installer Modes

Before any dependency check runs, the installer decides how aggressively it should act based on runtime signals and user flags.

Local vs. Server Detection

The _detect_environment() function in agent_reach/cli.py (lines 975–1014) inspects the runtime for server-like characteristics. It tallies evidence such as active SSH sessions, Docker containers, headless displays, cloud VM identity files, and virtualization data from systemd-detect-virt. When the count reaches two or more indicators, the function classifies the host as "server", which influences downstream decisions like cookie extraction eligibility.

Dry-Run and Safe Mode Implementations

• --dry-run activates _install_system_deps_dryrun, which prints every intended action without writing to the system. This mode is useful for CI pipelines and pre-check audits.
• --safe activates _install_system_deps_safe, which reports the current presence or absence of dependencies but refuses to modify the system. It is designed for fragile VMs or shared hosts where automatic package management is restricted.

Both modes skip the optional channel installers and cookie extraction steps regardless of the --channels flag.

Optional Channels and Cookie Extraction

After core dependencies are satisfied, the installer evaluates the --channels argument. Valid channels are mapped in CHANNEL_INSTALLERS (around lines 80–89 of _cmd_install). Each selected channel’s installer runs only in normal mode.

If a requested channel requires authentication cookies—such as Twitter, Xueqiu, or Bilibili—the installer invokes agent_reach.cookie_extract.configure_from_browser to import cookies from Chrome or Firefox. This step is deliberately disabled on server-classified hosts and blocked in dry-run and safe modes.

Final Verification with the Doctor Check

Regardless of which mode runs, the command ends by calling doctor.check_all from agent_reach/doctor.py. This routine audits every enabled channel and emits a concise report. If the installer performed work, the doctor output confirms whether the environment is now healthy; if the run was a dry-run or safe check, the report describes what remains missing.

Practical Examples

Use these commands to control how system dependency detection behaves on your host.

# Normal installation—detects missing deps and installs them

agent-reach install

# Preview what would change without modifying the system

agent-reach install --dry-run

# Audit dependencies without installing anything

agent-reach install --safe

# Install optional channels in addition to core dependencies

agent-reach install --channels=twitter,reddit,bilibili

# Force server-type detection on a remote VPS

agent-reach install --env=server

Summary

• The agent-reach install command detects core system dependencies—GitHub CLI, Node.js, npm, and the undici package—using shutil.which and global npm path checks inside agent_reach/cli.py.
• Environment detection in _detect_environment() classifies the host as "local" or "server" based on SSH, Docker, display, and virtualization indicators.
• --dry-run previews changes, and --safe audits the system without making modifications.
• Optional channel installers and cookie extraction run only after core dependencies are resolved, and only when explicitly requested.
• Every run concludes with a health report from doctor.check_all to confirm channel readiness.

Frequently Asked Questions

What system dependencies does agent-reach install check for?

The installer checks for the GitHub CLI (gh) via shutil.which("gh"), Node.js and npm via shutil.which("node") and shutil.which("npm"), and the undici npm package by reading the global npm root for undici/index.js inside agent_reach/cli.py.

How does the installer decide whether the host is a local workstation or a server?

The _detect_environment() function in agent_reach/cli.py inspects SSH variables, Docker markers, headless displays, cloud VM identifiers, and systemd-detect-virt output. If two or more server-like indicators are present, it returns "server"; otherwise it returns "local".

Will agent-reach install --safe modify my system packages?

No. Safe mode uses _install_system_deps_safe to report the presence or absence of dependencies without installing anything. It also skips optional channel installers and browser cookie extraction.

Why does the installer require the undici npm package globally?

Agent Reach leverages Node.js fetch with proxy support for certain channels. The installer verifies that undici/index.js exists in the global npm directory, and if not, it runs npm install -g undici to ensure the runtime requirement is met.

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