Agent Reach Safe Mode vs Dry-Run: Understanding the Difference During Installation

Safe mode prevents the installer from automatically installing system-level packages while completing Python-side setup, whereas dry-run generates a preview of every step the installer would perform without modifying your system.

When installing the Agent Reach toolkit from the Panniantong/Agent-Reach repository, understanding the distinction between safe mode and dry-run helps you maintain system security and verify installation steps before committing changes. These flags control how the agent-reach install command interacts with your operating system's package managers and whether it actually modifies your environment.

Core Differences Between Safe Mode and Dry-Run

What is Safe Mode?

In agent_reach/cli.py, the --safe flag configures the installer to skip all automatic system-level package installations. When activated, the installer will not invoke brew, apt, yum, or other package managers.

• Effect: Only Python packages and the Agent Reach library itself are installed; the host OS remains untouched.
• Use Case: Essential for locked-down workstations, CI environments that prohibit sudo, or scenarios requiring manual oversight of system dependencies.

What is Dry-Run Mode?

The --dry-run flag, also defined in agent_reach/cli.py, instructs the installer to simulate every action without executing it.

• Effect: The command prints a complete preview of planned installation steps and exits without creating files or installing packages.
• Use Case: Perfect for auditing which upstream tools would be fetched or validating installation logic in production deployment scripts.

Technical Implementation

According to the source code in Panniantong/Agent-Reach, these behaviors are controlled through specific files:

• agent_reach/cli.py: Defines the argument parsers for --safe and --dry-run flags that modify installer execution flow.
• docs/install.md: Documents safe mode as preventing "auto-install of system packages" and dry-run as providing a "preview what would be done" capability.
• agent_reach/doctor.py: Provides post-installation verification to check which components were actually set up, particularly useful after running safe mode to identify missing manual dependencies.

Practical CLI Examples

# Safe mode - installs Python components only, skips system package managers

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

# Dry-run - displays planned actions without executing them

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

# Combined with channel scoping while respecting safety constraints

agent-reach install --env=auto --safe --channels=twitter,weibo

When to Use Each Mode

Safe mode is ideal for security-conscious environments where package manager access is restricted or when you require explicit control over system-level dependencies like compilers or system libraries.

Dry-run is essential for continuous integration pipelines requiring pre-validation, or when you need to audit the complete list of external tools the installer would retrieve before allocating resources.

Both flags can be combined with other installation parameters to scope the deployment while respecting your chosen safety constraints.

Summary

• Safe mode (--safe) blocks automatic installation of system packages while completing Python library setup.
• Dry-run (--dry-run) simulates the entire installation process without modifying your file system or installing any packages.
• Both behaviors are implemented in agent_reach/cli.py and documented in docs/install.md.
• Safe mode suits restricted environments; dry-run suits pre-installation auditing and CI validation.
• Use agent_reach/doctor.py after safe mode installation to verify which components require manual setup.

Frequently Asked Questions

Can I use safe mode and dry-run together?

Yes. You can execute agent-reach install --safe --dry-run to preview only the Python-side installation steps without triggering system package checks or making any changes. This combination is useful for auditing the Python dependency tree in restricted environments.

Does safe mode prevent all installations or just system packages?

Safe mode specifically prevents automatic installation of system-level packages through managers like apt, brew, or yum as described in docs/install.md. It still installs the Python components of Agent Reach and its Python dependencies.

Will dry-run detect missing system dependencies?

Dry-run will list the system packages it would attempt to install, effectively showing you what dependencies are missing. However, it does not validate whether those packages are available in your repositories or whether your user account has the privileges required to install them.

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

Run the diagnostic utility implemented in agent_reach/doctor.py (typically invoked via agent-reach doctor). This checks which components were successfully set up and identifies any system-level packages you still need to install manually after using safe mode.

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