Agent Reach Safe Mode Installation: Complete Implementation Guide

Agent Reach safe mode installation lets you preview required system changes without modifying your environment by passing the --safe flag to audit dependencies like GitHub CLI, Node.js, and mcporter.

Agent Reach safe mode installation provides a zero-impact way to validate prerequisites before committing to a full setup. In the Panniantong/Agent-Reach repository, this feature is implemented as a command-line flag that intercepts automatic system modifications and instead generates manual installation instructions. This approach ensures transparency when deploying in restricted environments or when auditing system requirements.

How Agent Reach Safe Mode Installation Works

The --safe CLI Flag Definition

In agent_reach/cli.py at lines 71-73, the installer defines the --safe argument using Python's argparse library:

p_install.add_argument("--safe", action="store_true",
                       help="Safe mode: skip automatic system changes, show what's needed instead")

This flag is added to the install sub-command and defaults to False unless explicitly invoked.

Flag Handling in _cmd_install

The installation command handler captures this flag at lines 77-78 and stores it in a local variable for later conditional checks:

safe_mode = args.safe

This boolean determines whether the installer calls the standard dependency installer or the safe-mode variant.

System Dependency Validation Without Modifications

When safe_mode evaluates to True, the code at lines 40-44 branches away from _install_system_deps and instead invokes _install_system_deps_safe():

elif safe_mode:
    _install_system_deps_safe()

The _install_system_deps_safe function (lines 843-870) walks through the same dependency list—including GitHub CLI and Node.js—but does not modify the system. It checks binary presence and prints manual installation commands for any missing components rather than invoking apt, npm, or other package managers.

mcporter Backend Verification

The Exa-search backend follows an identical pattern. At lines 48-52, safe-mode redirects to _install_mcporter_safe(), which reports the presence of mcporter and displays the configuration command without executing it:

elif safe_mode:
    _install_mcporter_safe()

This ensures the Exa backend setup remains transparent and manual.

Blocking Automatic Channel Installation

Safe mode prevents automatic installation of optional channels (Twitter, Reddit, etc.). The code at lines 55-57 explicitly guards channel installation with a conditional that halts execution when safe mode is active:

if requested_channels and not dry_run and not safe_mode:
    # npm, pipx, or other external tool invocations skipped

This check ensures no external package managers run automatically, preventing side effects in production or restricted environments.

Safe Mode Reporting

Throughout execution, safe mode prints clear headings like SAFE MODE — skipping automatic system changes and lists each missing component with specific commands that users can run manually. This output format enables easy copy-paste into privileged shells when administrators are ready to proceed with actual installation.

Running Agent Reach in Safe Mode

To perform an Agent Reach safe mode installation, execute:

agent-reach install --safe

For a comprehensive audit that shows both what would be done and what is currently missing, combine safe mode with dry-run:

agent-reach install --dry-run --safe

The output identifies missing dependencies and provides exact manual installation commands, such as:

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

When to Use Safe Mode Installation

Auditing: Administrators can verify that the installer only requires specific binaries (gh, node, mcporter) before granting elevated privileges or network access.

Restricted Environments: On CI runners, minimal containers, or corporate machines without sudo access, safe mode reveals exact prerequisites without causing permission errors or failed installation attempts.

Pre-installation Validation: Combined with --dry-run, safe mode provides a complete picture of both planned configuration changes and current system readiness, ensuring a smooth deployment process.

Summary

• Agent Reach safe mode installation uses the --safe flag in agent_reach/cli.py to disable automatic system modifications while validating prerequisites.
• The installer redirects to _install_system_deps_safe() and _install_mcporter_safe() instead of their standard counterparts when the flag is present.
• Safe mode checks for GitHub CLI, Node.js, and mcporter presence without invoking package managers or modifying system paths.
• Optional channel installations are explicitly blocked when safe mode is active, preventing unwanted npm or pipx executions.
• Output includes manual installation commands for missing dependencies, enabling deferred execution in privileged shells after audit completion.

Frequently Asked Questions

What does Agent Reach safe mode installation do?

Agent Reach safe mode installation audits your system for required dependencies—such as GitHub CLI, Node.js, and the mcporter backend—without making any automatic changes. According to the implementation in agent_reach/cli.py, it prints manual installation instructions for missing components rather than invoking package managers.

How do I run Agent Reach in safe mode?

Run agent-reach install --safe from your terminal. This flag is defined in agent_reach/cli.py lines 71-73 and triggers the safe-mode code path at lines 40-44 that validates dependencies without system modification.

What dependencies does safe mode check?

According to the source code in agent_reach/cli.py, safe mode validates the presence of GitHub CLI (gh), Node.js, and the mcporter binary required for Exa-search functionality. It also prevents automatic installation of optional channel backends like Twitter and Reddit by checking the safe_mode boolean at lines 55-57.

Can I combine safe mode with dry-run?

Yes. Running agent-reach install --dry-run --safe provides a comprehensive audit showing both what configuration actions would be performed (dry-run) and which system dependencies are currently missing (safe-mode). This combination is ideal for pre-installation validation in restricted environments where automatic changes are prohibited.

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