What Is Safe Mode Behavior in Agent Reach During Installation?

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. 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, 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.

# 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, 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.

# 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:

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:

• _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 — Environment detection logic that routes to safe mode
• 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}