What's the Difference Between Safe Mode and Dry-Run During Agent Reach Installation?

Safe mode audits your environment and provides manual installation instructions without modifying the system, while dry-run previews every automated action the installer would perform without executing any changes.

When installing the Agent-Reach CLI tool from the Panniantong/Agent-Reach repository, you can use two mutually exclusive flags to prevent automatic system modifications. Understanding the distinction between safe mode (--safe) and dry-run (--dry-run) ensures you choose the right approach for auditing dependencies or previewing installation steps before committing to changes.

Safe Mode (--safe): Audit Without Automation

How Safe Mode Works

In agent_reach/cli.py, the safe mode flag triggers alternative "safe" variants of installation functions. Instead of executing system commands, the installer runs environment detection and proxy handling normally, but substitutes the actual install functions with reporting-only versions.

Specifically, the installer calls _install_system_deps_safe() (lines 65-73) and _install_mcporter_safe() (lines 62-70) to check for existing tools without installing them. The code guards optional channel installation and cookie imports with conditional checks: if not dry_run and not safe_mode and if env == "local" and needs_cookies and not safe_mode and not dry_run.

Safe Mode Output Behavior

When you run agent-reach install --safe, the CLI prints a list of missing dependencies alongside manual installation instructions. For example, if Node.js is absent, it outputs the download URL or package manager command rather than executing an automatic install.

Dry-Run Mode (--dry-run): Preview the Installation Plan

How Dry-Run Works

Dry-run mode extends the preview concept by echoing every potential action the installer would take. In agent_reach/cli.py, this mode invokes _install_system_deps_dryrun() (lines 94-102) to report which system packages would be installed, and prints placeholder messages for cookie imports and optional channel additions.

Unlike safe mode, dry-run explicitly states what automation would occur: [dry-run] Would install optional channels: twitter, xiaohongshu, reddit and [dry-run] Would try to import cookies from Chrome/Firefox.

Dry-Run Output Behavior

This mode provides a complete step-by-step plan, showing exactly which channels would be added and which dependencies would be fetched via package managers or curl commands, without requiring manual interpretation.

Key Differences at the Code Level

The two modes diverge in implementation strategy:

• Safe mode runs the standard installer logic but suppresses execution. It utilizes _install_system_deps_safe() and _install_mcporter_safe() to generate actionable manual steps.
• Dry-run replaces operations with echo statements. It uses _install_system_deps_dryrun() to summarize planned actions and prints explicit "would" statements for all operations including optional channels and cookie imports.

Both modes prevent the if not dry_run and not safe_mode guarded blocks from executing, but safe mode focuses on generating manual remediation steps while dry-run focuses on documenting automated behavior.

When to Use Each Mode

Use safe mode when:

• Auditing corporate workstations where automatic changes are prohibited
• Generating manual installation instructions for offline environments
• Verifying existing dependencies without triggering package manager operations

Use dry-run when:

• Reviewing the exact automated steps before production deployment
• Documenting installer behavior for compliance reviews
• Debugging which optional channels and cookies would be processed

Practical Examples

Running Safe Mode

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

Typical output:

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

Running Dry-Run Mode

agent-reach install --env=auto --dry-run

Typical output:

DRY RUN — showing what would be done (no changes)

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

[dry-run] Would install optional channels: twitter, xiaohongshu, reddit
[dry-run] Would try to import cookies from Chrome/Firefox
...
Dry run complete. No changes were made.

Summary

• Safe mode (--safe) audits the environment and generates manual installation instructions without executing system changes, using functions like _install_system_deps_safe() in agent_reach/cli.py.
• Dry-run (--dry-run) previews every automated action the installer would perform, including optional channels and cookie imports, without modifying the system.
• Both modes prevent automatic installation of optional channels and cookie extraction, but safe mode focuses on manual remediation steps while dry-run documents automated behavior.
• Choose safe mode for compliance auditing and dry-run for pre-installation verification.

Frequently Asked Questions

Can I use both --safe and --dry-run flags together?

No, these flags are mutually exclusive in the Agent-Reach CLI. The installer logic in agent_reach/cli.py treats them as separate pathways, with specific guards like if not dry_run and not safe_mode preventing execution of modification blocks when either flag is present.

Does safe mode check for optional channels?

Safe mode skips automatic installation of optional channels entirely. The code block responsible for channel installation is guarded by conditions checking both dry_run and safe_mode, meaning safe mode prevents both automatic installation and the dry-run preview of these channels.

Will dry-run attempt to import browser cookies?

No, dry-run only prints a placeholder message indicating it would attempt cookie import. According to the implementation in agent_reach/cli.py, the actual cookie extraction logic is bypassed when dry_run is true, printing [dry-run] Would try to import cookies from Chrome/Firefox instead.

Which mode should I use on a locked-down corporate workstation?

Use safe mode (--safe). This mode runs the standard detection logic but substitutes all installation functions with safe variants that only report missing dependencies, providing manual installation instructions without requiring administrative privileges or modifying system state.

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