Safe Mode vs Dry-Run in Agent Reach: Installation Options Explained

Safe mode (--safe) prevents automatic installation of system-level packages while completing Python setup, whereas dry-run (--dry-run) simulates the entire installation process without modifying your system.

The Agent Reach installer from the Panniantong/Agent-Reach repository provides distinct flags for controlling installation behavior. While both --safe and --dry-run protect your system from unwanted changes, they serve fundamentally different purposes during the setup process.

Understanding Safe Mode

Purpose and System Impact

Safe mode is designed for security-conscious installations that must not invoke system package managers. When enabled, the installer prevents automatic installation of external tools like brew, apt, or yum, performing only the Python-side setup.

According to docs/install.md in the repository, this mode ensures the installer "won't auto-install system packages" while still installing the Agent Reach library itself. Your host OS remains untouched by package manager commands, making this ideal for locked-down workstations or CI environments where sudo access is restricted.

CLI Usage

Execute safe mode installation using:

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

You can combine this with other flags such as --channels=twitter,weibo to scope the installation while maintaining the safety restrictions against system package installation.

Understanding Dry-Run Mode

Purpose and System Impact

Dry-run serves as a preview mechanism that displays every step the installer would perform without actually changing the system. As documented in docs/install.md, this mode allows you to "preview what would be done" before committing to changes.

Unlike safe mode, which performs actual Python package installation, dry-run makes no changes whatsoever. It merely reports the actions it would take, including which upstream tools would be fetched and configured, then exits without modifying Python or system packages.

CLI Usage

Run a dry-run to audit planned actions:

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

This command finishes after printing the planned actions, making it valuable for auditing installer behavior before execution.

Key Differences Between Safe Mode and Dry-Run

While both flags protect your system, they differ in execution scope:

• Safe mode (--safe): Performs the Python installation but skips system-level package manager calls. It modifies your Python environment by installing the Agent Reach library but leaves system files untouched.
• Dry-run (--dry-run): Performs no installation at all. It simulates the entire process for verification purposes without modifying Python or system packages.

Implementation in the Source Code

The behavior of these flags is defined in the Agent Reach codebase:

• agent_reach/cli.py: Defines the --safe and --dry-run argument flags that control installer behavior at the command-line interface level.
• docs/install.md: Contains the user-facing documentation describing both modes and their typical use cases.
• agent_reach/doctor.py: Provides post-installation verification to confirm which components were actually set up, useful for validating safe mode installations.

Summary

• Safe mode prevents automatic system package installation while completing Python-side setup, ideal for restricted environments that cannot invoke brew, apt, or yum.
• Dry-run provides a complete preview of installer actions without making any system changes, useful for auditing before execution.
• Both flags can be combined with channel selection flags like --channels=twitter,weibo.
• Source code in agent_reach/cli.py controls these behaviors, documented in docs/install.md.

Frequently Asked Questions

Can I use safe mode and dry-run together?

Yes, you can combine both flags to preview what a safe installation would look like. Running agent-reach install --env=auto --safe --dry-run shows the planned actions while ensuring the preview respects the safe mode restrictions against system package installation.

Does safe mode install Python packages?

Yes, safe mode installs Python packages including the Agent Reach library itself. It only prevents automatic installation of system-level dependencies managed by external package managers like brew, apt, or yum.

Will dry-run show system package installations?

Yes, dry-run displays all planned actions including which system packages would be installed if you ran the command without the --dry-run flag. This allows you to audit the complete list of upstream tools that the installer would fetch before making any changes to your system.

Where are these installation flags defined in the source code?

The --safe and --dry-run flags are defined in agent_reach/cli.py, which controls the command-line interface behavior. User documentation for these options resides in docs/install.md, while agent_reach/doctor.py handles post-installation verification of which components were actually configured.

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