# What Is Safe Mode During Installation in Agent Reach?

> Understand safe mode during installation in Agent Reach. This feature verifies system dependencies without installation, ensuring your environment is ready before Agent Reach is installed.

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

---

**Safe mode during installation is a dry-run verification feature that audits system dependencies without installing them, ensuring your environment meets Agent Reach requirements before any changes occur.**

When deploying Agent Reach from the `Panniantong/Agent-Reach` repository, administrators need a way to validate system readiness without triggering unintended package modifications. Safe mode during installation serves this exact purpose, functioning as a read-only health check that scans for GitHub CLI, Node.js, and mcporter while explicitly avoiding system alterations.

## How Safe Mode Works During Installation

Safe mode operates as a **check-only variant** of the standard `agent-reach install` command. When activated, it performs a complete prerequisite audit but halts before executing any installation commands.

### Non-Intrusive Dependency Scanning

When invoked, the installer scans for required binaries including GitHub CLI (`gh`), Node.js (`node`), and the `mcporter` package. For each dependency detected, it prints a status line confirming availability. Unlike the standard installation flow, safe mode **never executes** `npm install -g mcporter`, `pipx install`, or system package manager calls.

### Manual Installation Guidance

Rather than automatically pulling in missing packages, safe mode displays explicit manual-install instructions for any absent components. This approach gives security-conscious users full control over what software enters their system, presenting URLs or package manager commands (such as `apt install nodejs npm`) without executing them.

## Implementation in agent_reach/cli.py

The safe mode logic lives in two dedicated helper functions within [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), separated from the standard installation pathways to guarantee side-effect-free operation.

### System Dependency Verification

The `_install_system_deps_safe()` function (lines 665–692) checks for the presence of `gh` and `node` binaries on the system path. When running, it prints a *"safe mode — no auto-install"* banner to clearly indicate that the process will not modify the environment. This function iterates through required system tools and reports their status without invoking any installers.

### McPorter Availability Check

Similarly, the `_install_mcporter_safe()` function (lines 662–674) verifies whether `mcporter` is already accessible on the path. If the package is missing, the function outputs specific installation instructions—typically `npm install -g mcporter` followed by configuration steps for Exa—while explicitly refraining from running these commands automatically.

## Running Agent Reach in Safe Mode

To verify your environment without triggering installations, append the `--safe` flag to the install command as documented in [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md) (lines 84–89).

Check prerequisites with automatic environment detection:

```bash
agent-reach install --env=auto --safe

```

Combine safe mode with dry-run for a complete installation preview:

```bash
agent-reach install --env=auto --dry-run --safe

```

Typical output demonstrates the verification-only behavior:

```

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 installed
  To install: npm install -g mcporter
  Then configure Exa: mcporter config add exa https://mcp.exa.ai/mcp

```

## Summary

- **Safe mode** provides a read-only verification of GitHub CLI, Node.js, and mcporter availability without system modifications.
- The implementation resides in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) within `_install_system_deps_safe()` (lines 665–692) and `_install_mcporter_safe()` (lines 662–674).
- Users activate the feature via the `--safe` flag, documented in [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md) (lines 84–89) and referenced in [`docs/README_en.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/README_en.md) (lines 118–120).
- Unlike standard installation, safe mode explicitly avoids executing `npm install`, `pipx install`, or system package manager calls, presenting only manual instructions for missing dependencies.

## Frequently Asked Questions

### What dependencies does safe mode check during installation?

Safe mode verifies the presence of **GitHub CLI** (`gh`), **Node.js** (`node`), and the **mcporter** package. According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), these checks occur in `_install_system_deps_safe()` and `_install_mcporter_safe()` respectively, ensuring all required binaries are present before proceeding.

### How do I run Agent Reach installation in safe mode?

Execute `agent-reach install --env=auto --safe` to enable safe mode. You can combine it with `--dry-run` for a complete preview. This flag is documented in [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md) (lines 84–89) and prevents any automatic installations while displaying the environment audit results.

### Will safe mode install missing dependencies automatically?

No. Safe mode explicitly avoids side effects such as `npm install -g mcporter`, `pipx install`, or system package manager calls. Instead, it prints manual installation instructions for any missing components, allowing users to install them at their discretion while maintaining system integrity.

### Where is the safe mode feature documented?

The primary documentation appears in [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md) (lines 84–89) with additional context in [`docs/README_en.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/README_en.md) (lines 118–120). The implementation details reside in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) within the `_install_system_deps_safe()` and `_install_mcporter_safe()` helper functions.