# How Agent Reach Install --safe Mode Works: Non-Destructive System Audits

> Discover how Agent Reach install --safe mode performs non-destructive system audits. This read-only verification shows missing dependencies without making changes.

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

---

**The `--safe` flag in `agent-reach install` performs a read-only verification of system dependencies without making any modifications, displaying manual installation instructions for missing components instead of automatically installing them.**

The `install` command in the [Panniantong/Agent-Reach](https://github.com/Panniantong/Agent-Reach) repository provides a protective `--safe` option designed for constrained environments. When you invoke `agent-reach install` with this flag, the tool switches from an automatic installer to a non-destructive auditor. This mode is particularly valuable for corporate machines, CI pipelines, or any system where you need to verify requirements before granting installation permissions.

## Parsing the --safe Flag in agent_reach/cli.py

The `--safe` argument is defined at lines 71–73 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) as a boolean flag. When the CLI parses user input at lines 177–178, it assigns the value to `safe_mode = args.safe`, which later determines the entire installation flow. This single boolean triggers a branch between two distinct execution paths: the standard automatic installation versus the safe-mode verification.

## Safe Mode vs. Normal Mode: Key Differences

When `--safe` is present, the `install` command swaps its implementation functions for read-only alternatives. The behavior differs across three critical areas:

**System Dependencies Handling**

- **Normal Mode**: Calls `_install_system_deps()`, which attempts to automatically install missing tools like GitHub CLI and Node.js.
- **Safe Mode**: Calls `_install_system_deps_safe()` (lines 665–692), which only checks for required binaries and prints manual installation instructions.

**Exa Search Backend (mcporter)**

- **Normal Mode**: Executes `_install_mcporter()` to automatically install the `mcporter` tool via package managers.
- **Safe Mode**: Executes `_install_mcporter_safe()` (lines 962–970), which reports the presence of `mcporter` and displays the manual configuration command without executing it.

**Optional Channel Installers**

- **Normal Mode**: Runs channel-specific installers (e.g., Twitter, Reddit) when the `--channels` flag is provided.
- **Safe Mode**: Skips all channel-specific installers entirely, preventing any automatic package installations beyond the two core dependency checks.

## How the Safe Mode Checks Work Under the Hood

The safe-mode functions implement straightforward presence checks using Python's standard library, making no subprocess calls that would modify the system.

### System Dependency Validation (_install_system_deps_safe)

Located at lines 665–692 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), this function iterates over a small list of required tools including `gh` (GitHub CLI) and `node` (Node.js). It uses `shutil.which` to detect whether each binary exists on the system PATH. Missing tools are collected into a list and displayed with links to their official installation instructions. No `subprocess` commands are executed to install missing dependencies.

### Exa Search Backend Verification (_install_mcporter_safe)

This function, found at lines 962–970, checks whether the `mcporter` executable is available on the PATH. If the binary is found, the function confirms its presence; otherwise, it prints a hint suggesting `npm install -g mcporter` for manual installation. Like its system dependency counterpart, this function performs zero automatic installations.

## Using --safe with --dry-run

The `--safe` and `--dry-run` flags operate independently according to the source implementation. When you combine both flags:

```bash
agent-reach install --safe --dry-run

```

The `--dry-run` flag prints a "DRY RUN" banner before the safe-mode checks execute. However, the safe-mode behavior remains unchanged—it still suppresses any automatic system modifications and only reports what would be required. The combination provides a complete preview of both the installation plan and the dependency audit without touching the system.

## Practical Example: Running a Safe Installation Check

To verify your system readiness without modifications, run:

```bash
agent-reach install --safe

```

The output follows this structure:

```text
SAFE MODE — skipping automatic system changes

Checking system dependencies (safe mode — no auto-install)...
  ✅ GitHub CLI already installed
  -- Node.js not found
  To install missing dependencies manually:
    Node.js: https://nodejs.org — or: apt install nodejs npm
Checking mcporter (safe mode)...
  mcporter not found
  To install manually: npm install -g mcporter

```

This output allows you to review exactly which components need manual installation before proceeding with a full install.

## Summary

- **The `--safe` flag** in `agent-reach install` switches the CLI from automatic installation to read-only verification mode.
- **Two core functions** handle the safe checks: `_install_system_deps_safe()` at lines 665–692 and `_install_mcporter_safe()` at lines 962–970 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).
- **System impact** is zero—safe mode uses `shutil.which` to detect binaries but never executes installation commands via `subprocess`.
- **Channel installers** are completely bypassed when `--safe` is active, even if `--channels` is specified.
- **Combine with `--dry-run`** to see a complete preview of the installation plan alongside the dependency audit.

## Frequently Asked Questions

### Does --safe modify any files on my system?

No. The `--safe` flag explicitly prevents any file system modifications. According to the implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), safe mode only executes detection logic using `shutil.which` and prints instructions. It does not invoke `subprocess` calls that would install packages, write configuration files, or alter your environment.

### Can I use --safe and --dry-run together?

Yes. These flags are independent and complementary. When used together (`agent-reach install --safe --dry-run`), the CLI displays the dry-run banner followed by the safe-mode dependency audit. The dry-run flag adds preview messaging while the safe flag ensures no automatic changes occur, giving you a complete picture of what the installer would do under normal circumstances.

### What dependencies does the safe mode check for?

Safe mode checks for two categories of dependencies. First, it verifies **system tools** including GitHub CLI (`gh`) and Node.js (`node`) through `_install_system_deps_safe()`. Second, it checks for the **mcporter** executable, which serves as the Exa search backend, through `_install_mcporter_safe()`. All other optional channel-specific dependencies are skipped entirely when `--safe` is active.

### Why does safe mode skip channel installers?

Channel installers (for platforms like Twitter or Reddit) typically require additional package installations or API configurations that could modify the system. The `--safe` flag is designed to provide a **non-destructive audit** of only the core requirements needed to run Agent Reach. By skipping channel-specific installers, safe mode ensures it only reports on fundamental binary dependencies without triggering any package manager operations or network-based installations.