What Is Safe Mode During Installation in Agent Reach?

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, 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 (lines 84–89).

Check prerequisites with automatic environment detection:

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

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

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 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 (lines 84–89) and referenced in 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, 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 (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 (lines 84–89) with additional context in docs/README_en.md (lines 118–120). The implementation details reside in agent_reach/cli.py within the _install_system_deps_safe() and _install_mcporter_safe() helper functions.

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