Safe Mode vs Dry-Run During Agent Reach Installation: Key Differences Explained

Safe mode skips automatic system changes and provides manual installation instructions, while dry-run previews every action the installer would take without executing any of them.

When installing the Panniantong/Agent-Reach framework using the agent-reach install command, you can use two mutually exclusive flags to prevent automatic system modifications. Understanding the difference between safe mode and dry-run ensures you choose the right audit or preview strategy for your environment before the installer touches any dependencies.

Core Differences Between Safe Mode and Dry-Run

What Safe Mode Does

In safe mode, the installer runs the standard environment detection, proxy handling, and final channel testing logic, but replaces the actual installation functions with "safe" variants that only report missing tools. According to the source code in agent_reach/cli.py, the functions _install_system_deps_safe() (lines 65-73) and _install_mcporter_safe() (lines 62-70) verify existing system tools and output manual installation instructions rather than installing them automatically.

Safe mode also suppresses automatic cookie imports from Chrome/Firefox and prevents the installation of optional channels. The code explicitly guards these actions with conditional blocks like if not dry_run and not safe_mode for optional channels, and if env == "local" and needs_cookies and not safe_mode and not dry_run for cookie imports.

What Dry-Run Does

Dry-run performs a complete preview of the installation flow without touching the system. The installer echoes every planned action, including which system packages would be installed and which optional channels would be added. In agent_reach/cli.py, the function _install_system_deps_dryrun() (lines 94-102) demonstrates this behavior by showing exactly which dependencies are missing and the specific installation commands that would be executed.

Unlike safe mode, dry-run simulates the full execution path, printing placeholders like [dry-run] Would try to import cookies from Chrome/Firefox and [dry-run] Would install optional channels: twitter, xiaohongshu, reddit.

Technical Implementation in Agent Reach

System Dependency Handling

The installer implements separate pathways for each mode in agent_reach/cli.py:

• Safe mode: Uses _install_system_deps_safe() to verify existing tools and output manual fix instructions for missing dependencies.
• Dry-run: Uses _install_system_deps_dryrun() to display the exact installation commands that would be executed, including package manager calls and setup scripts.

Optional Channels and Cookie Import

Both flags prevent automatic modifications, but behave differently:

• Safe mode: Completely skips optional channel installation and cookie extraction.
• Dry-run: Prints preview messages indicating which channels would be installed and which browser cookies would be imported.

Command Examples and Expected Output

To audit your environment with safe mode:

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

Typical safe-mode 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

...

To preview the installation without making changes:

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

Typical dry-run 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.

When to Use Each Mode

Use safe mode when you need to audit a corporate workstation or production environment where automatic package installation is prohibited. It tells you exactly what's missing and provides the manual steps required to fix it.

Use dry-run when you want to see the complete execution plan before committing to changes. This is ideal for CI/CD pipelines or automation scripts where you need to verify the installer's behavior in agent_reach/cli.py beforehand.

Summary

• Safe mode runs installer logic but reports missing dependencies instead of installing them, providing manual instructions via _install_system_deps_safe() in agent_reach/cli.py.
• Dry-run previews every action without system changes, using _install_system_deps_dryrun() to echo planned installations and optional channel additions.
• Both flags prevent automatic cookie imports and optional channel installation, but dry-run shows what would happen while safe mode simply skips these steps.
• Safe mode is designed for auditing environments where no automatic changes are permitted, while dry-run is designed for previewing the full installation workflow step-by-step.

Frequently Asked Questions

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

No, these flags are mutually exclusive. The agent-reach install command in agent_reach/cli.py treats them as separate operational modes—safe mode runs the detection logic with manual reporting, while dry-run simulates the full installation flow. Attempting to use both typically results in the last flag taking precedence or the installer rejecting the combination.

Will safe mode detect missing Node.js or GitHub CLI installations?

Yes, safe mode actively checks for system dependencies using _install_system_deps_safe() and reports the status of each tool. It prints specific manual installation instructions for any missing dependencies, such as Node.js download URLs or package manager commands like apt install nodejs npm.

Does dry-run actually download any packages or modify configuration files?

No, dry-run makes zero system changes. According to the source code in agent_reach/cli.py, dry-run functions only print messages indicating what would be done. No network requests are made, no packages are downloaded, and no files are modified during a dry-run execution.

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

Use safe mode (--safe). It ensures no automatic system changes occur while still providing you with a complete audit of missing dependencies and manual installation steps required to prepare the environment without violating IT policies.

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