# Difference Between --safe Mode and --dry-run During Agent Reach Installation > Understand the difference between --safe mode and --dry-run for Agent Reach installation. Learn how safe mode handles packages and dry-run previews changes. - Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach) - Tags: how-to-guide - Published: 2026-06-30 --- **Safe mode prevents automatic installation of system-level packages while still installing Python components, whereas dry-run only previews actions without making any changes to the system.** When installing the **Panniantong/Agent-Reach** toolkit, understanding the difference between `--safe` mode and `--dry-run` flags helps you control exactly how the installer modifies your environment. These two options serve distinct purposes—one restricts system-level modifications while the other simulates the entire process. This guide explains the technical distinction between these installation flags based on the actual source code implementation. ## Understanding Safe Mode (--safe) ### Purpose and System Impact Safe mode is designed for security-conscious environments where you want to prevent the installer from automatically installing any system-level packages such as `brew`, `apt`, or `yum`. According to [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md), this flag ensures the installer only performs Python-side setup, leaving you to manually install any required external tools. When you run with `--safe`, the command completes after setting up the Agent Reach library itself without invoking `sudo` or touching system package managers. ### When to Use Safe Mode Use this mode when working on locked-down workstations, corporate machines with strict policies, or CI environments where automatic system modifications are prohibited. The installer will check dependencies but skip any automatic installation of operating system packages, making it ideal for situations where you need a **security-conscious** installation that respects host system boundaries. ## Understanding Dry-Run (--dry-run) ### Purpose and System Impact Dry-run operates as a simulation layer. Rather than executing installation steps, the installer prints a preview of every action it would perform without actually changing the system or installing anything. As implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), this flag allows you to audit the complete list of upstream tools and configuration changes before committing to them. The command finishes immediately after displaying the planned actions. ### When to Use Dry-Run Employ dry-run when you need to **verify** what the installer plans to do before making permanent changes. This is particularly useful for auditing dependencies, reviewing which external channels (such as `--channels=twitter,weibo`) will be configured, or confirming that the installer won't attempt unauthorized system modifications. ## Side-by-Side Comparison **Safe Mode** (`--safe`) - **Behavior**: Executes the Python installation but blocks automatic system package installations. - **System Impact**: Only Agent Reach Python libraries are installed; the host OS remains unchanged. - **Best For**: Locked-down workstations, CI pipelines, or environments where `sudo` access is restricted. **Dry-Run** (`--dry-run`) - **Behavior**: Simulates every step the installer would take without executing them. - **System Impact**: Zero changes—reports actions and terminates immediately. - **Best For**: Pre-installation verification, dependency auditing, and reviewing installation steps before execution. ## Implementation in the Source Code The flag definitions reside in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), where the argument parser distinguishes between these two modes. The [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md) file provides user-facing documentation, noting that safe mode "won't auto-install system packages" while dry-run offers a "preview what would be done." After installation completes, you can use [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) to verify which components were actually configured on your system. ## Command-Line Examples ```bash # Safe mode: Install Python components only, skip system packages agent-reach install --env=auto --safe # Dry-run: Preview all planned actions without executing agent-reach install --env=auto --dry-run # Combining with other flags (works with both modes) agent-reach install --env=auto --safe --channels=twitter,weibo ``` ## Summary - **Safe mode** performs the actual Python installation but prevents automatic system-level package management, making it ideal for restricted environments. - **Dry-run** executes no installation steps whatsoever, providing only a preview of actions for verification purposes. - Both flags can be combined with other options like `--channels` to scope the installation while respecting the chosen safety level. - Configuration details 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). ## Frequently Asked Questions ### Can I use --safe and --dry-run together? Yes, you can combine these flags. When used together, the installer will simulate the safe mode installation, showing you exactly which Python packages would be installed while confirming that no system packages would be touched. ### Does safe mode skip all installations or just system packages? Safe mode only skips automatic installation of system-level tools like `brew`, `apt`, or `yum`. It still installs the Agent Reach Python library and its Python dependencies, as clarified in the [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md) documentation. ### Where are these flags implemented in the codebase? The argument definitions and initial flag processing are located in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py). The actual behavior enforcement—whether to skip system package installation or simulate the entire process—is handled within the installation logic that references these CLI arguments. ### How can I verify what was actually installed after using safe mode? After running the installer, use the [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) utility to verify which components are present on your system. This tool checks the actual state of your installation against the expected configuration, helping you identify which system packages you still need to install manually.