# What Is Safe Mode Behavior in Agent Reach During Installation?

> Understand Agent Reach safe mode during installation. It checks dependencies, reports status, and provides manual commands without installing anything.

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

---

**Agent Reach's safe mode verifies required system dependencies without automatically installing anything, reporting tool status with ✅ or -- markers and providing exact manual commands for missing requirements.**

Safe mode is a core protective feature of the Agent Reach installer that prevents unauthorized system modifications. When you run the installation command, safe mode performs read-only detection of GitHub CLI, Node.js, npm, and the optional **mcporter** search backend—never invoking `subprocess.run` to install packages. This makes it ideal for restricted environments like CI pipelines and servers where automatic downloads are prohibited.

## How Safe Mode Works in the Installation Flow

The installer invokes safe mode through two primary functions in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py). Both functions follow the same pattern: detect, report status, and output precise remediation steps.

### System Dependencies Check: `_install_system_deps_safe()`

Located at **lines 884–910** in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), this function handles validation of core binaries.

The function prints a clear header: *"Checking system dependencies (safe mode — no auto-install)..."* It then iterates over the required binary list (`gh`, `node`, `npm`), emitting **✅** for present tools and **--** for missing ones. At completion, it outputs a consolidated manual install block.

```bash

# Trigger the system dependencies safe check

python -m agent_reach.cli install --env=auto

# Sample output when tools are missing

Checking system dependencies (safe mode — no auto-install)...
  ✅ GitHub CLI already installed
  -- Node.js not found
  -- npm not found

To install missing dependencies manually:
  Node.js: https://nodejs.org — or: apt install nodejs npm

```

### mcporter Backend Check: `_install_mcporter_safe()`

Found at **lines 1071–1119** in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), this function validates the optional **mcporter** search backend.

The function prints *"Checking mcporter (safe mode)..."* When `mcporter` is absent from PATH, it outputs the exact `npm install -g mcporter` command plus Exa configuration instructions—never executing these commands automatically.

```bash

# Sample mcporter safe mode output when not installed

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 --scope home

```

When mcporter and Exa are properly configured, the output confirms:

```bash
Checking mcporter (safe mode)...
  ✅ mcporter already installed
  ✅ Exa search already configured

```

## Key Safe Mode Guarantees

Safe mode provides three critical protections during Agent Reach installation:

- **Zero automatic execution** — No `subprocess.run` calls install packages; all actions require explicit user approval
- **Clear visual status** — ✅ indicates present tools; -- indicates missing dependencies
- **Exact remediation commands** — Missing tools trigger copy-paste-ready install instructions

These guarantees ensure the installer **does not alter the host system state** while still guiding users to a fully functional setup.

## Safe Mode vs. Automatic Installation

| Aspect | Safe Mode | Automatic Mode |
|--------|-----------|----------------|
| **Tool detection** | Reads PATH and reports | Reads PATH and reports |
| **Package installation** | Never executes | May invoke package managers |
| **Output format** | Status symbols + manual commands | Silent or progress indicators |
| **Use case** | Restricted environments, audits | Interactive, trusted environments |

According to the Panniantong/Agent-Reach source code, safe mode is the **default behavior** when `--env=auto` is specified, making it the recommended approach for first-time assessments.

## Source Code References

The safe mode implementation resides in these critical sections of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py):

- **`_install_system_deps_safe`** (lines 884–910) — Core binary validation
- **`_install_mcporter_safe`** (lines 1071–1119) — Search backend validation

Supporting files include:

- [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) — Environment detection logic that routes to safe mode
- [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) — Post-install verification that safe mode checks succeeded

## Summary

- Safe mode in Agent Reach **verifies without modifying** — it detects GitHub CLI, Node.js, npm, and mcporter presence strictly via PATH inspection
- The **`_install_system_deps_safe`** and **`_install_mcporter_safe`** functions in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) implement all safe mode behavior
- Output uses **✅** for found tools and **--** for missing ones, followed by exact manual install commands
- Safe mode never invokes `subprocess.run` for package installation, making it safe for CI pipelines and restricted servers
- Run `python -m agent_reach.cli install --env=auto` to execute the installer in safe mode

## Frequently Asked Questions

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

Execute `python -m agent_reach.cli install --env=auto`. This triggers the default safe mode behavior without requiring additional flags. The installer immediately begins dependency detection and reports tool status without attempting any automatic installations.

### What happens if a required dependency is missing in safe mode?

The installer prints **--** next to the missing tool name, followed by a concise "To install missing dependencies manually:" section with exact commands. For example, missing Node.js produces `apt install nodejs npm` or the official Node.js download URL. You must copy and execute these commands yourself.

### Is safe mode suitable for production deployment pipelines?

Yes. Safe mode guarantees **zero system modifications** — it only reads PATH variables and prints status. This satisfies security policies that prohibit automatic downloads in production environments. Run safe mode first in your pipeline to validate the environment, then execute the reported manual install steps through your approved change management process.

### Can I skip the mcporter check in safe mode?

The mcporter check runs automatically as part of `install --env=auto` at lines 1071–1119 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py). There is no built-in skip flag for this specific check in safe mode. However, since safe mode never installs mcporter automatically, you can simply ignore the output if you do not require Exa search functionality.