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

Safe mode performs the Python installation while skipping system-level package managers, whereas dry-run only previews what would be installed without making any changes to your system.

When installing the Agent Reach framework from the Panniantong/Agent-Reach repository, you can control how the installer interacts with your system using two distinct CLI flags. Understanding the difference between safe mode and dry-run during Agent Reach installation helps you choose between a security-conscious setup that avoids system modifications and a preview mode that audits changes before they occur.

Core Differences Between Safe Mode and Dry-Run

What is Safe Mode?

According to the installation documentation in docs/install.md, safe mode prevents the installer from automatically installing any system-level packages such as brew, apt, or yum. When you invoke the --safe flag, the installer only performs Python-side setup, installing the Agent Reach library itself while leaving external tool installation to the user.

This mode ensures no changes to the host OS or package manager, making it ideal for locked-down workstations or CI environments that must not invoke sudo.

What is Dry-Run?

As implemented in agent_reach/cli.py, the dry-run flag (--dry-run) shows a preview of every step the installer would perform without actually changing the system or installing anything. The command finishes after printing the actions it would take, allowing you to audit the list of upstream tools that will be fetched before committing to changes.

This mode makes zero modifications to your environment and serves purely as a verification mechanism.

When to Use Each Mode

• Safe mode: Use when you need a security-conscious installation that won't touch system files, such as on restricted workstations or in automated CI pipelines where package manager access is prohibited.
• Dry-run: Use when you want to verify what the installer will do before allowing changes, such as auditing dependencies or reviewing system-level modifications in advance.

Command Line Examples

# Safe mode – installs Python components only, skips system packages

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

# Dry-run – previews actions without system modifications

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

Both commands can be combined with other flags like --channels=twitter,weibo to scope the installation while respecting your chosen safety level.

Implementation and Verification

The behavior of these flags is defined in agent_reach/cli.py, which handles the CLI argument parsing for the installation process. The docs/install.md file marks safe mode with the note that "it won't auto-install system packages" and describes dry-run as a way to "preview what would be done."

After installation, you can use agent_reach/doctor.py to verify which components were actually set up, confirming whether system-level tools were skipped (safe mode) or would have been installed (dry-run).

Summary

• Safe mode (--safe) runs the installer but skips automatic system-package installation, handling only Python-side setup.
• Dry-run (--dry-run) skips installation entirely and merely reports what would happen, making zero system changes.
• Safe mode is ideal for security-conscious environments; dry-run is perfect for pre-installation auditing.
• Both flags are defined in agent_reach/cli.py and documented in docs/install.md.

Frequently Asked Questions

Can I use safe mode and dry-run together during Agent Reach installation?

Yes, you can combine both flags in a single command such as agent-reach install --env=auto --safe --dry-run, which would preview the Python-side installation steps while confirming that no system packages would be touched.

Does safe mode install the Agent Reach Python library?

Yes, safe mode installs the Agent Reach library and Python dependencies according to agent_reach/cli.py. It only excludes system-level package managers like brew, apt, or yum from executing automatically.

Will dry-run detect missing system dependencies?

The dry-run flag shows a preview of every step the installer would perform, including which system packages it would attempt to install. However, it does not validate whether those packages are already present or would succeed in installation—it merely simulates the installation logic without making changes.

How do I verify what was actually installed after using safe mode?

After installation, run the doctor utility from agent_reach/doctor.py to verify which components were set up. This helps confirm that system-level tools were skipped as expected while Python components were successfully installed.

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