# How Agent-Reach Safe Mode Installation Works with the `--safe` Flag

> Learn how Agent-Reach safe mode installation uses the --safe flag for non-destructive audits. Get manual instructions instead of automatic modifications.

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

---

**The `--safe` flag in `agent-reach install` performs a non-destructive audit by checking for required system dependencies and the `mcporter` backend without making any automatic modifications, outputting manual installation instructions instead.**

The Agent-Reach CLI provides a safe mode installation option for users who need to audit requirements without allowing the tool to modify their system. When you append the `--safe` flag to the install command, the utility switches from automatic dependency installation to a read-only verification mode that reports missing components and provides manual setup instructions.

## How the `--safe` Flag Alters Installation Behavior

The `--safe` option is defined in the argument parser at lines 71-73 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py). When invoked, the CLI sets `safe_mode = args.safe` at lines 177-178 and branches the installation logic into a verification-only pathway. This changes the behavior across three critical areas of the setup process.

### System Dependency Verification vs. Installation

In normal mode, the installer calls `_install_system_deps()` which attempts to automatically install missing tools like the GitHub CLI and Node.js. When `--safe` is active, the code instead invokes `_install_system_deps_safe()` (implemented at lines 665-692).

This safe variant iterates over the required tool list (`gh`, `node`) and uses `shutil.which` to verify their presence on the system PATH. It makes **no subprocess calls** to install missing software. Instead, it collects absent binaries and prints manual installation instructions with links to official documentation.

### Exa Search Backend Handling

The installer normally calls `_install_mcporter()` to automatically set up the Exa search backend. Under safe mode, it executes `_install_mcporter_safe()` (lines 962-970), which checks whether the `mcporter` executable exists on the PATH. If found, it confirms the installation; otherwise, it prints the manual installation command (`npm install -g mcporter`) without executing it.

### Channel Installer Suppression

When `--safe` is set, the installer skips all channel-specific installers (e.g., Twitter, Reddit) even if the `--channels` flag is supplied. This prevents any automatic package installations beyond the core system dependency and backend checks mentioned above.

## Source Code Implementation Details

The safe-mode functions are implemented directly in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and follow a consistent pattern of read-only system inspection.

The `_install_system_deps_safe()` function (lines 665-692) maintains a strict separation between detection and modification. It uses Python's standard library `shutil.which()` to locate binaries, ensuring it never triggers package managers or curl-pipe scripts. Missing dependencies are aggregated into a list and displayed with platform-specific installation commands.

Similarly, `_install_mcporter_safe()` (lines 962-970) avoids any network calls or npm executions. It relies solely on filesystem PATH resolution to determine if the Exa backend is available, making it safe for air-gapped or restricted environments where automatic package management is prohibited.

## Using Agent-Reach Safe Mode in Practice

To audit your system without making changes, run:

```bash
agent-reach install --safe

```

The output will display a "SAFE MODE" banner followed by checkmarks or warnings for each dependency:

```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

```

### Combining with `--dry-run`

You can combine safe mode with the dry-run flag for an additional preview layer:

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

```

The `--dry-run` flag prepends a "DRY RUN" banner to the output, but the behavior of the safe-mode checks remains unchanged. Safe mode takes precedence for all modification decisions, ensuring no system changes occur regardless of the dry-run flag's presence.

## Summary

- **The `--safe` flag** (defined at lines 71-73 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)) triggers a non-destructive installation audit that verifies but never modifies system state.
- **System dependencies** are checked via `shutil.which` in `_install_system_deps_safe()` (lines 665-692) rather than installed automatically.
- **The `mcporter` backend** is verified for presence on PATH via `_install_mcporter_safe()` (lines 962-970) without invoking npm.
- **Channel installers** are completely bypassed in safe mode, preventing any automatic package installations.
- **No subprocess calls** are made for software installation when `--safe` is active, making it suitable for restricted environments and CI pipelines.

## Frequently Asked Questions

### What is the difference between `--safe` and `--dry-run` in Agent-Reach?

The `--safe` flag prevents any automatic system modifications by replacing installation functions with verification-only counterparts (`_install_system_deps_safe`, `_install_mcporter_safe`), while `--dry-run` simply prints a preview banner without changing the underlying execution logic. They can be used together, but `--safe` is the stronger guarantee against system changes.

### Does safe mode install any packages automatically?

No. According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), safe mode explicitly avoids all `subprocess` calls that would trigger package managers. It only checks for the existence of `gh`, `node`, and `mcporter` using `shutil.which`, then outputs manual instructions for anything missing.

### Which system tools does the safe mode check for?

The `_install_system_deps_safe()` function checks for the GitHub CLI (`gh`) and Node.js (`node`). Additionally, `_install_mcporter_safe()` verifies the presence of the `mcporter` executable required for Exa search functionality. These checks occur at lines 665-692 and 962-970 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) respectively.

### Can I use `--safe` with specific channel installation flags?

Yes, but the channels will not be installed. Even if you specify `--channels` (e.g., `--channels twitter,reddit`), the safe mode flag forces the installer to skip all channel-specific setup routines. Only the core system dependency and backend checks are performed.