How the Agent-Reach Install Command Detects and Handles Different Environment Types

The agent-reach install command executes a three-phase workflow—parsing CLI arguments, auto-detecting the environment via heuristic scoring, and applying environment-specific installation rules that skip desktop-only channels on headless servers.

The install sub-command is the core one-shot installer for the Agent-Reach framework, designed to adapt its behavior based on whether it’s running on a local workstation or a remote server. Understanding how the agent-reach install command handles different environment types ensures you deploy the correct dependencies and channel configurations for your specific infrastructure.

The Three-Phase Installation Workflow

The installation process implemented in _cmd_install within agent_reach/cli.py follows a structured pipeline that begins with argument parsing and ends with environment-specific dependency installation.

Phase 1: CLI Argument Parsing

The command entry point at lines 71-78 of agent_reach/cli.py processes user inputs including --env, --proxy, --safe, --dry-run, and optional --channels parameters. The --env flag accepts three values: auto (default), local, or server. When --env=auto is specified (or omitted), the installer proceeds to the detection phase.

Phase 2: Environment Auto-Detection

If --env=auto is set, the installer invokes _detect_environment() (lines 77-97 of agent_reach/cli.py) to determine the runtime environment using a weighted scoring system:

• SSH environment variables detected → +2 points
• Docker or container markers (/.dockerenv or /run/.containerenv) → +2 points
• Missing DISPLAY or Wayland (indicating headless operation) → +1 point
• Cloud provider identifiers in /sys files → +2 points
• Virtualization detected via systemd-detect-virt → +1 point

A cumulative score of ≥ 2 classifies the environment as server; otherwise, it’s classified as local. This heuristic allows the installer to distinguish between a developer’s laptop and a headless VPS or CI runner without manual configuration.

Phase 3: Environment-Specific Installation Logic

Based on the detected or explicitly provided environment type, the core logic around lines 120-138 and 30-38 of _cmd_install applies specific rules:

• Server Mode: Automatically filters out OpenCLI-only channels (opencli, facebook, instagram) from the installation set, as these require a desktop Chrome session. The installer prints a notification indicating which channels were skipped.
• Local Mode: Proceeds with all requested channel installers and triggers automatic browser cookie import from Chrome (with Firefox fallback) for channels requiring authentication.

Environment-Specific Channel Handling

The installer maintains a registry of channel-specific installation functions that respect the environment classification:

• _install_twitter_deps(), _install_xhs_deps(), _install_xiaoyuzhou_deps(), _install_bili_deps(), and _install_reddit_deps() execute on both environment types
• _install_opencli_deps() (handling Facebook, Instagram, and OpenCLI backends) executes only in local mode
• _install_reddit_deps() intelligently chooses between OpenCLI for desktop environments or rdt-cli for server environments

When running in local mode with cookie-dependent channels, the installer automatically imports existing browser credentials before proceeding with skill file generation.

Additional Installation Modes

The install command supports two diagnostic modes for testing and validation:

• --safe: Invokes _install_system_deps_safe() and corresponding safe variants for each channel. These functions report missing system dependencies without modifying the system, allowing you to audit requirements first.
• --dry-run: Activates _install_system_deps_dryrun() and related dry-run handlers, displaying the complete list of actions that would be taken without executing any system changes or network requests.

Practical Usage Examples

Run the installer with automatic environment detection (default behavior):

agent-reach install --channels=twitter,reddit

Force a local installation on a desktop where display is available:

agent-reach install --env=local --channels=all

Force a server installation on a headless VPS (OpenCLI channels will be automatically excluded):

agent-reach install --env=server --channels=twitter,facebook,instagram

Preview installation steps without making changes:

agent-reach install --dry-run --channels=twitter,xiaohongshu

Audit missing dependencies safely:

agent-reach install --safe --channels=reddit

Summary

• The agent-reach install command uses a weighted heuristic system in _detect_environment() to classify environments as local or server based on SSH variables, container markers, display availability, and virtualization status.
• Server environments (score ≥ 2) automatically exclude OpenCLI-only channels (facebook, instagram, opencli) that require desktop browser automation.
• Local environments receive full channel support including automatic browser cookie import from Chrome and Firefox.
• The --safe and --dry-run flags enable non-destructive testing of the installation process using dedicated helper functions like _install_system_deps_safe() and _install_system_deps_dryrun().
• Explicit environment overrides via --env=local or --env=server bypass auto-detection for controlled deployments.

Frequently Asked Questions

How does Agent-Reach determine if I'm running on a server or local machine?

The _detect_environment() function in agent_reach/cli.py assigns points based on system indicators: SSH variables and container markers contribute +2 points each, missing display servers add +1, cloud provider signatures in /sys add +2, and virtualization detection adds +1. If the total score reaches 2 or higher, the system is classified as a server environment.

Which channels are skipped when running in server mode?

The installer maintains a constant OPENCLI_ONLY_CHANNELS containing {"opencli", "facebook", "instagram"}. When the environment is classified as server (or explicitly set via --env=server), the installer removes these channels from the requested set before executing _install_opencli_deps() or related functions, as they require a local Chrome browser instance.

Can I override the automatic environment detection?

Yes. The --env CLI argument accepts explicit values of local or server that bypass the _detect_environment() heuristic entirely. Use agent-reach install --env=local to force desktop-mode installation on systems that might otherwise be misclassified, or --env=server to ensure headless-compatible installation on ambiguous systems.

What is the difference between --safe and --dry-run modes?

The --safe flag executes variant functions like _install_system_deps_safe() that check for and report missing dependencies without installing them, returning a list of required system packages. The --dry-run flag simulates the entire installation workflow—including channel setup and configuration—printing every action that would occur without making any filesystem changes or network requests.

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