How Dry-Run and Safe Mode Function During Agent Reach Installation

Safe mode prevents the installer from automatically installing system-level packages while completing Python-side setup, whereas dry-run displays a complete preview of installation steps without modifying the system.

When installing the Panniantong/Agent-Reach framework, understanding how dry-run and safe mode function during Agent Reach installation helps you control system modifications and preview changes before execution. These CLI flags provide distinct levels of protection—safe mode restricts system-level changes while proceeding with Python package installation, while dry-run simulates the entire process without touching the filesystem.

Understanding Safe Mode (--safe)

Purpose and Security Constraints

Safe mode is designed for security-conscious environments where system-level modifications are restricted. When invoked with --safe, the installer skips automatic installation of external tools like brew, apt, or yum and limits operations to Python-side setup only. According to the documentation in docs/install.md, this mode "won't auto-install system packages," making it ideal for locked-down workstations or CI environments where sudo or package manager access is prohibited.

Command Usage

To execute a safe mode installation that handles Python dependencies while leaving system packages untouched:

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

This command installs the Agent Reach library and its Python dependencies while requiring you to manually install any required external tools.

Understanding Dry-Run Mode (--dry-run)

Preview Without System Changes

Dry-run mode provides a complete audit trail of what the installer would execute without performing any actual changes. As documented in docs/install.md, dry-run lets you "preview what would be done" by parsing all configuration flags, calculating dependencies, and outputting the exact sequence of actions—including system packages that would be fetched—then exiting without modifying the host.

Command Usage

To preview an installation before committing changes:

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

The output lists every planned step, allowing you to verify upstream tools and dependencies before the real installation begins.

Key Differences Between Safe Mode and Dry-Run

While both flags protect your system, they operate at different stages:

• Safe mode (--safe): Runs the installation but blocks automatic system-package installation. It modifies the Python environment by installing the Agent Reach library and its dependencies, but leaves the host OS and external tools untouched.
• Dry-run (--dry-run): Performs no installation whatsoever. It only simulates the process and reports what would happen, making zero changes to the system state.

Use safe mode when you need the Python components installed but must manually control system-level dependencies. Use dry-run when you need to audit or verify the installer’s behavior before allowing any modifications.

Implementation in the Source Code

According to the Panniantong/Agent-Reach source code, these behaviors are defined across three key files:

• docs/install.md: Contains the user-facing documentation describing safe mode as preventing auto-installation of system packages, and dry-run as a preview mechanism.
• agent_reach/cli.py: Defines the --safe and --dry-run argument flags that the CLI parser accepts, routing control flow to skip system package managers or simulate execution.
• agent_reach/doctor.py: Provides post-installation verification to check which components were actually set up, useful for validating installations performed in safe mode.

Combining Flags with Installation Options

Both modes can be combined with other CLI arguments to scope the installation. For example, you can restrict the installation to specific channels while maintaining safe mode restrictions:

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

This flexibility allows you to verify or install specific components without triggering unnecessary system-level operations.

Summary

• Safe mode (--safe) installs Python packages while skipping automatic system-level package installation, suitable for restricted environments.
• Dry-run (--dry-run) simulates the entire installation process and outputs planned actions without making any filesystem changes.
• Both flags are defined in agent_reach/cli.py and documented in docs/install.md.
• Use agent_reach/doctor.py to verify component status after installation.
• These flags can be combined with other options like --channels to control installation scope.

Frequently Asked Questions

What is the difference between safe mode and dry-run in Agent Reach?

Safe mode performs the Python installation but blocks automatic system-package installation, whereas dry-run only shows what would be installed without making any changes. Safe mode modifies the Python environment; dry-run modifies nothing.

Can I use safe mode and dry-run together when installing Agent Reach?

Yes, you can combine both flags in a single command. The installer will simulate the safe mode installation, showing you Python packages that would be installed while confirming that no system packages would be auto-installed.

Where are the safe mode and dry-run flags defined in the Agent Reach codebase?

The flags are defined in agent_reach/cli.py, which handles the command-line argument parsing. The behavior for safe mode is documented in docs/install.md as preventing auto-installation of system packages, while dry-run is implemented as a simulation mode that logs intended actions without execution.

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

Run the doctor.py utility (agent_reach/doctor.py) to check which components were successfully set up. This tool validates the installation state and identifies any missing system-level dependencies that you must install manually after using safe mode.

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