# Safe Mode vs Dry-Run in Agent Reach: Installation Options Explained > Understand the differences between Agent Reach's safe mode and dry run installation options. Learn how safe mode avoids system packages while dry run simulates the process without changes. - Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach) - Tags: internals - Published: 2026-06-14 --- **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`](https://github.com/Panniantong/Agent-Reach/blob/main/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: ```bash 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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: ```bash 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md)**: Contains the user-facing documentation describing both modes and their typical use cases. - **[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) controls these behaviors, documented in [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), which controls the command-line interface behavior. User documentation for these options resides in [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md), while [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) handles post-installation verification of which components were actually configured.