Safe Mode vs Dry Run During Agent Reach Installation: What's the Difference?

Safe mode audits your environment and provides manual installation instructions while skipping automatic changes, whereas dry run previews every action the installer would take without executing any system modifications.

When installing the Agent Reach CLI from the Panniantong/Agent-Reach repository, you can use two mutually exclusive flags—--safe and --dry-run—to control how the installer modifies your system. Understanding the difference between safe mode and dry run during Agent Reach installation helps you decide whether to audit existing dependencies or preview the complete installation workflow before committing changes.

What is Safe Mode?

Safe mode is designed for environments where automatic system modifications are restricted or prohibited. When you pass the --safe flag to agent-reach install, the tool executes its standard environment detection and proxy handling logic, but replaces all installation functions with "safe" variants that only report missing dependencies.

In agent_reach/cli.py, the safe mode implementation calls _install_system_deps_safe() and _install_mcporter_safe() to check for tools like GitHub CLI and Node.js without installing them. The installer also suppresses optional channel installation and cookie auto-import by guarding those blocks with conditional checks: if not dry_run and not safe_mode.

When to Use Safe Mode

Use --safe when you need to audit a corporate workstation or production environment where automatic package installation violates security policies. The output provides explicit manual installation instructions for any missing dependencies, allowing you to satisfy requirements through approved channels.

What is Dry Run?

Dry run provides a complete preview of the installation workflow without touching the system. Unlike safe mode, which still executes the installer logic, dry run replaces installation functions with "dry-run" versions that merely echo what would happen.

According to the source code in agent_reach/cli.py, the --dry-run flag invokes _install_system_deps_dryrun() to print messages like "would install via: curl NodeSource setup | bash". It also reports which optional channels would be added and displays placeholder text for cookie import operations: [dry-run] Would try to import cookies from Chrome/Firefox.

When to Use Dry Run

Use --dry-run when you want to see the exact sequence of system changes—including package installations, channel configurations, and cookie extraction—before allowing the installer to modify your environment. This mode is ideal for CI/CD pipeline validation or pre-deployment verification.

Technical Differences Between Safe Mode and Dry Run

While both flags prevent system modifications, they differ in execution depth and output format:

• Safe mode runs the actual installer logic but substitutes "safe" function variants that report missing tools rather than installing them. It skips optional channels entirely and suppresses cookie import.
• Dry run simulates the full installation flow, printing preview messages for every action including system dependencies, optional channels, and cookie imports.

In agent_reach/cli.py, the critical distinction appears in the conditional blocks: optional channels are bypassed when safe_mode is true, but reported as "would install" when dry_run is true. Similarly, cookie import is guarded by if env == "local" and needs_cookies and not safe_mode and not dry_run, meaning both flags suppress this feature, but only dry run explicitly acknowledges the skipped step in its output.

Practical Usage Examples

To run the installer in safe mode and receive manual installation instructions:

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

Typical output includes:

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 entire installation workflow without making changes:

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

Typical output includes:

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) audits your environment and provides manual fix instructions while skipping automatic system changes, optional channels, and cookie imports.
• Dry run (--dry-run) previews every action the installer would take, including system package installations, channel additions, and cookie extraction steps.
• Both flags prevent modifications, but safe mode runs installer logic with safe variants (_install_system_deps_safe), while dry run echoes planned actions (_install_system_deps_dryrun).
• Use safe mode for security-audited environments; use dry run for pre-installation verification and CI/CD validation.

Frequently Asked Questions

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

No, these flags are mutually exclusive. The agent-reach install command accepts only one mode at a time because they serve different purposes—safe mode provides actionable manual instructions, while dry run provides a preview of automatic actions.

Does safe mode check for optional channels?

Safe mode detects optional channels but does not install them. According to the source code in agent_reach/cli.py, the optional channel installation block is guarded by if not dry_run and not safe_mode, meaning both flags prevent automatic installation, though only dry run explicitly reports what would have been installed.

Will dry run attempt to import browser cookies?

No, dry run only prints a placeholder message indicating that cookie import would be attempted. The actual cookie extraction is suppressed by the conditional check if env == "local" and needs_cookies and not safe_mode and not dry_run, preventing any access to browser data during the preview.

Which mode should I use on a restricted corporate workstation?

Use --safe mode. It respects security policies by avoiding automatic system changes while providing explicit manual installation instructions for missing dependencies like Node.js or GitHub CLI, allowing you to satisfy requirements through approved IT channels.

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