What Does the `--safe` Flag Do in `agent-reach install`?

The --safe flag runs the Agent Reach installer in read-only diagnostic mode, checking for system dependencies and optional components without making any changes to your system.

When you run the installation command for the Panniantong/Agent-Reach CLI, the --safe flag transforms the process from an automated setup into a non-invasive audit. Instead of installing GitHub CLI, Node.js, or the mcporter binary, the tool scans your environment and reports what is missing along with manual installation instructions. This mode is ideal for production environments, CI/CD pipelines, or any system where you want complete control over package installation.

How the --safe Flag Works

The flag is defined in the CLI argument parser at [agent_reach/cli.py lines 71-73](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L71-L73). When parsing completes, the value is stored in the variable safe_mode = args.safe at line 77.

This boolean flag controls execution flow through four major decision points:

• System dependencies (lines 45-52): Skips automatic installation of GitHub CLI and Node.js
• McPorter binary (lines 54-62): Skips the npm install -g mcporter execution
• Optional channels (lines 69-70): Completely bypasses installation of Twitter, Reddit, Bilibili, and other channel backends
• Cookie imports (lines 85-86): Guards against auto-importing browser cookies for Twitter, Reddit, and XiaoHongShu

System-Level Dependency Checks

In standard mode, the installer automatically fetches and installs missing system binaries. With --safe, the logic routes through _install_system_deps_safe (lines 665-692), which performs a read-only verification.

The function checks for the presence of required binaries and prints a concise status report:

• Green checkmarks for existing tools
• Manual installation hints for missing dependencies, including package manager commands or URLs

This allows administrators to review exactly what the installer would have done before granting permission to modify the system.

McPorter Binary Verification

The mcporter binary is required for Exa search functionality. Normally, the installer runs npm install -g mcporter automatically. Under --safe, the execution branches to _install_mcporter_safe (lines 662-674).

This helper function verifies whether mcporter exists in your $PATH and outputs instructions for manual installation if needed. It also displays configuration commands for connecting Exa search, ensuring you have the complete setup sequence without the tool touching your Node.js environment.

Optional Components Disabled in Safe Mode

Safe mode explicitly prevents two categories of optional system modifications:

Channel Backends: The installer prints "SAFE MODE — skipping automatic system changes" and bypasses all optional channel installations. This includes social media integrations that would normally configure API access for Twitter, Reddit, Bilibili, and other platforms.

Browser Cookie Imports: The auto-import feature that extracts authentication cookies from your browser is completely disabled. This ensures the installer never reads browser data or writes cookie files to disk, addressing privacy and security concerns in shared or sensitive environments.

Running Safe Mode in Practice

Execute a diagnostic installation check without system modifications:

$ agent-reach install --safe
Agent Reach Installer
========================================
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 installed
  To install: npm install -g mcporter
  Then configure Exa search: mcporter config add exa https://mcp.exa.ai/mcp

The --safe flag is independent of --dry-run. You can combine both flags to see the dry-run output format while maintaining the guarantee of zero system changes:

$ agent-reach install --safe --dry-run
[dry-run] System dependency check:
  GitHub CLI: already installed, skip
  Node.js: would install via: curl NodeSource setup | bash + apt install nodejs
...

Summary

• The --safe flag in agent-reach install activates a read-only diagnostic mode that audits your system without making changes.
• It routes execution through _install_system_deps_safe and _install_mcporter_safe to check for missing binaries rather than installing them.
• Optional channel backends and browser cookie imports are completely skipped when safe mode is active.
• The flag is parsed in agent_reach/cli.py and stored in the safe_mode variable that guards four major installation phases.
• Safe mode can be combined with --dry-run for additional safety in CI/CD environments.

Frequently Asked Questions

Can I combine --safe with other installation flags?

Yes. The --safe flag operates independently of other options like --dry-run or --verbose. Combining --safe --dry-run provides the most conservative approach, showing you exactly what the installer would do in a completely non-invasive format. The safe_mode boolean simply forces the conditional checks at lines 69-70 and 85-86 to skip all mutation operations.

Why does safe mode skip the mcporter binary installation?

According to the source code in agent_reach/cli.py, the mcporter binary requires a global npm install (npm install -g mcporter), which modifies your Node.js environment. The _install_mcporter_safe function (lines 662-674) replaces this with a presence check and manual instructions, ensuring you maintain control over global package installations while still receiving guidance on configuring Exa search.

Does --safe prevent the installer from touching my browser data?

Yes. Lines 85-86 in agent_reach/cli.py explicitly guard cookie import operations with if not safe_mode. When the flag is present, the installer will not attempt to read browser cookies for Twitter, Reddit, or XiaoHongShu, nor will it write any cookie files to disk. This ensures complete privacy regarding your browser session data.

How do I install dependencies manually after running --safe?

After running agent-reach install --safe, the CLI outputs specific manual installation commands for each missing dependency. For Node.js, it suggests either visiting https://nodejs.org or using apt install nodejs npm. For mcporter, it provides the exact npm install -g mcporter command and the configuration string for Exa search. You can execute these commands with your preferred package manager before re-running the standard installation.

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