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

Safe mode audits your system and provides manual installation instructions without making changes, while dry-run mode previews the exact automated steps the installer would execute without performing them.

When installing the Agent-Reach framework using the agent-reach install command, you can invoke two mutually exclusive safety flags to control how the installer interacts with your system. Understanding the distinction between safe mode (--safe) and dry-run mode (--dry-run) is critical for auditing corporate environments or validating installation procedures before execution.

Core Differences Between Safe Mode and Dry-Run Mode

Both flags prevent the installer from modifying your system, but they differ significantly in scope and output:

• Safe mode performs a complete environment audit and provides manual remediation steps. It executes the standard installer logic—including environment detection, proxy handling, and final channel testing—but substitutes installation functions with reporting variants that only list missing dependencies.
• Dry-run mode generates a complete preview of the automated installation flow, showing exactly which system packages would be installed, which optional channels would be added, and what cookie imports would be attempted.

How Safe Mode Works Under the Hood

In agent_reach/cli.py, invoking --safe triggers alternative "safe" variants of the installation functions. Specifically, the installer calls _install_system_deps_safe() (lines 65-73) and _install_mcporter_safe() (lines 62-70) instead of their standard counterparts.

Safe mode executes the full installer logic but automatically suppresses several automated components through specific conditional guards:

• Optional channels: The installation block is guarded by if not dry_run and not safe_mode, meaning these channels are not installed at all in safe mode.
• Cookie import: Extraction from Chrome or Firefox is skipped when the condition if env == "local" and needs_cookies and not safe_mode and not dry_run evaluates false due to the safe_mode flag.

How Dry-Run Mode Works Under the Hood

When you pass --dry-run, the installer replaces execution functions with preview variants that merely echo intended actions. In agent_reach/cli.py, the function _install_system_deps_dryrun() (lines 94-102) handles system dependency reporting by printing what would be installed without invoking package managers.

Dry-run mode provides granular visibility into the installation plan through placeholder messages:

• System dependencies: Reports which packages would be installed and through which method (e.g., "would install via: curl NodeSource setup | bash + apt install nodejs").
• Optional channels: Prints a summary line formatted as [dry-run] Would install optional channels: twitter, xiaohongshu, reddit.
• Cookie import: Displays [dry-run] Would try to import cookies from Chrome/Firefox.

Unlike safe mode, dry-run explicitly shows the automated actions the installer would take, making it ideal for pre-flight validation in CI/CD pipelines.

Practical Usage Examples

Use safe mode when you need to audit a corporate workstation or environment where automatic system changes are prohibited:

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

Typical output includes dependency checks and manual instructions:

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

Use dry-run mode when you want to preview the exact automated steps before executing them:

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

Expected output shows the complete execution plan:

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

Summary

• Safe mode (--safe) runs the full installer logic but replaces modification functions with reporting variants, providing manual installation instructions rather than executing changes.
• Dry-run mode (--dry-run) previews every automated action the installer would perform, including system package installation, optional channel setup, and cookie imports.
• Both modes suppress automatic installation of optional channels and cookie extraction, but safe mode focuses on manual remediation guidance while dry-run focuses on execution preview.
• In agent_reach/cli.py, safe mode utilizes _install_system_deps_safe() and _install_mcporter_safe(), while dry-run uses _install_system_deps_dryrun().

Frequently Asked Questions

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

No. These flags are mutually exclusive. The installer logic in agent_reach/cli.py treats them as distinct operational modes, and using both simultaneously would create conflicting execution paths for system dependency handling.

Does safe mode check if dependencies are already installed?

Yes. Safe mode performs complete environment detection and proxy handling. It executes the standard installer logic but substitutes the installation functions with _install_system_deps_safe(), which verifies the presence of tools like GitHub CLI and Node.js and reports their status without attempting automatic remediation.

Will dry-run mode detect my existing system configuration?

Yes. Dry-run mode performs environment detection to determine what is already present versus what would need installation. The _install_system_deps_dryrun() function reports existing installations (e.g., "gh CLI: already installed, skip") while listing the specific commands that would be executed for missing components.

Which mode should I use on a production server?

Use dry-run mode first to preview the automated changes, then execute the standard installation if the preview is acceptable. Safe mode is better suited for development environments or restricted corporate workstations where you need manual control over every system modification. Neither mode makes changes, but dry-run provides the clearest picture of what the automated installer intends to modify.

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