How Agent-Reach Safe Mode Installation Works with the `--safe` Flag

The --safe flag in agent-reach install performs a non-destructive audit by checking for required system dependencies and the mcporter backend without making any automatic modifications, outputting manual installation instructions instead.

The Agent-Reach CLI provides a safe mode installation option for users who need to audit requirements without allowing the tool to modify their system. When you append the --safe flag to the install command, the utility switches from automatic dependency installation to a read-only verification mode that reports missing components and provides manual setup instructions.

How the --safe Flag Alters Installation Behavior

The --safe option is defined in the argument parser at lines 71-73 of agent_reach/cli.py. When invoked, the CLI sets safe_mode = args.safe at lines 177-178 and branches the installation logic into a verification-only pathway. This changes the behavior across three critical areas of the setup process.

System Dependency Verification vs. Installation

In normal mode, the installer calls _install_system_deps() which attempts to automatically install missing tools like the GitHub CLI and Node.js. When --safe is active, the code instead invokes _install_system_deps_safe() (implemented at lines 665-692).

This safe variant iterates over the required tool list (gh, node) and uses shutil.which to verify their presence on the system PATH. It makes no subprocess calls to install missing software. Instead, it collects absent binaries and prints manual installation instructions with links to official documentation.

Exa Search Backend Handling

The installer normally calls _install_mcporter() to automatically set up the Exa search backend. Under safe mode, it executes _install_mcporter_safe() (lines 962-970), which checks whether the mcporter executable exists on the PATH. If found, it confirms the installation; otherwise, it prints the manual installation command (npm install -g mcporter) without executing it.

Channel Installer Suppression

When --safe is set, the installer skips all channel-specific installers (e.g., Twitter, Reddit) even if the --channels flag is supplied. This prevents any automatic package installations beyond the core system dependency and backend checks mentioned above.

Source Code Implementation Details

The safe-mode functions are implemented directly in agent_reach/cli.py and follow a consistent pattern of read-only system inspection.

The _install_system_deps_safe() function (lines 665-692) maintains a strict separation between detection and modification. It uses Python's standard library shutil.which() to locate binaries, ensuring it never triggers package managers or curl-pipe scripts. Missing dependencies are aggregated into a list and displayed with platform-specific installation commands.

Similarly, _install_mcporter_safe() (lines 962-970) avoids any network calls or npm executions. It relies solely on filesystem PATH resolution to determine if the Exa backend is available, making it safe for air-gapped or restricted environments where automatic package management is prohibited.

Using Agent-Reach Safe Mode in Practice

To audit your system without making changes, run:

agent-reach install --safe

The output will display a "SAFE MODE" banner followed by checkmarks or warnings for each dependency:

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
Checking mcporter (safe mode)...
  mcporter not found
  To install manually: npm install -g mcporter

Combining with --dry-run

You can combine safe mode with the dry-run flag for an additional preview layer:

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

The --dry-run flag prepends a "DRY RUN" banner to the output, but the behavior of the safe-mode checks remains unchanged. Safe mode takes precedence for all modification decisions, ensuring no system changes occur regardless of the dry-run flag's presence.

Summary

• The --safe flag (defined at lines 71-73 of agent_reach/cli.py) triggers a non-destructive installation audit that verifies but never modifies system state.
• System dependencies are checked via shutil.which in _install_system_deps_safe() (lines 665-692) rather than installed automatically.
• The mcporter backend is verified for presence on PATH via _install_mcporter_safe() (lines 962-970) without invoking npm.
• Channel installers are completely bypassed in safe mode, preventing any automatic package installations.
• No subprocess calls are made for software installation when --safe is active, making it suitable for restricted environments and CI pipelines.

Frequently Asked Questions

What is the difference between --safe and --dry-run in Agent-Reach?

The --safe flag prevents any automatic system modifications by replacing installation functions with verification-only counterparts (_install_system_deps_safe, _install_mcporter_safe), while --dry-run simply prints a preview banner without changing the underlying execution logic. They can be used together, but --safe is the stronger guarantee against system changes.

Does safe mode install any packages automatically?

No. According to the source code in agent_reach/cli.py, safe mode explicitly avoids all subprocess calls that would trigger package managers. It only checks for the existence of gh, node, and mcporter using shutil.which, then outputs manual instructions for anything missing.

Which system tools does the safe mode check for?

The _install_system_deps_safe() function checks for the GitHub CLI (gh) and Node.js (node). Additionally, _install_mcporter_safe() verifies the presence of the mcporter executable required for Exa search functionality. These checks occur at lines 665-692 and 962-970 of agent_reach/cli.py respectively.

Can I use --safe with specific channel installation flags?

Yes, but the channels will not be installed. Even if you specify --channels (e.g., --channels twitter,reddit), the safe mode flag forces the installer to skip all channel-specific setup routines. Only the core system dependency and backend checks are performed.

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