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

> Learn how the Agent-Reach install command identifies and manages diverse environments through its three-phase workflow, ensuring optimal installation rules.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-14

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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):

```bash
agent-reach install --channels=twitter,reddit

```

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

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

```

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

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

```

Preview installation steps without making changes:

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

```

Audit missing dependencies safely:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.