# How Dry-Run and Safe Mode Function During Agent Reach Installation > Learn how dry-run and safe mode function during Agent Reach installation. Safe mode prevents package installs, while dry-run shows a complete installation preview without system modification. - Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach) - Tags: how-to-guide - Published: 2026-06-21 --- **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`](https://github.com/Panniantong/Agent-Reach/blob/main/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: ```bash 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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: ```bash 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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: ```bash 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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and documented in [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md). - Use [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), which handles the command-line argument parsing. The behavior for safe mode is documented in [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py) utility ([`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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.