# Agent Reach Installation: Safe Mode vs Dry-Run Explained > Understand the Agent Reach installation difference between safe mode and dry run. Safemode installs Python packages, while dry run only simulates the process without making changes. - Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach) - Tags: how-to-guide - Published: 2026-06-20 --- **TLDR:** Safe mode performs the Python-side installation while blocking automatic system-level package installations, whereas dry-run only simulates and previews every step without modifying your system. When installing the Agent Reach toolkit from the `Panniantong/Agent-Reach` repository, you can control how the installer interacts with your operating system using two distinct command-line flags. Understanding the functional difference between `--safe` and `--dry-run` helps you avoid unwanted system modifications in production environments, locked-down workstations, or CI pipelines. This guide analyzes the actual implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and documentation in [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md) to explain exactly how each mode behaves. ## Understanding Safe Mode (`--safe`) Safe mode restricts the installer to **Python-level operations only**, deliberately preventing any automatic invocation of system package managers. When you pass the `--safe` flag during Agent Reach installation, the installer skips attempts to install external tools like `brew`, `apt`, or `yum`, focusing solely on setting up the Python library and its dependencies. According to the installation documentation in [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md), safe mode is designed for **security-conscious environments** where you cannot or should not modify system files. This includes locked-down workstations, containers with restricted permissions, or CI environments where `sudo` access is prohibited. The Python packages for Agent Reach install normally, but any missing system-level prerequisites are left for manual installation by the user. ## Understanding Dry-Run Mode (`--dry-run`) Dry-run mode takes a **completely non-destructive approach**, executing the installer's logic without applying any changes to your system. When invoked with `--dry-run`, the Agent Reach installer processes all configuration steps and prints a detailed preview of what actions it *would* perform, including which system packages it would fetch and which Python components it would configure. As documented in [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md), dry-run serves as an **audit mechanism** that allows you to verify the complete list of upstream tools and dependencies before committing to the actual installation. The command finishes after displaying the planned execution steps, leaving your environment entirely untouched. This mode performs no writes to the filesystem, makes no network requests for package installation, and triggers no privilege escalations. ## Key Functional Differences The distinction between these modes lies in their execution scope and system impact: - **System modifications:** Safe mode modifies your Python environment but preserves system-level package managers, while dry-run makes absolutely no changes to host OS or Python environments. - **Installation scope:** Safe mode installs the Agent Reach library and its Python dependencies, whereas dry-run only simulates the installation process. - **Use cases:** Safe mode suits production deployments requiring restricted permissions, while dry-run fits pre-installation auditing and verification workflows. ## Practical Usage Examples The flags are defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and accept standard installation parameters. You can invoke them as follows: To install only Python components while skipping system package auto-installation: ```bash agent-reach install --env=auto --safe ``` To preview the complete installation plan without executing any changes: ```bash agent-reach install --env=auto --dry-run ``` Both flags support additional scoping parameters such as `--channels=twitter,weibo` to filter which components the installer processes while respecting your chosen safety mode. ## Verification with Agent Reach Doctor After running installations—particularly in safe mode where system dependencies might be manually managed—you can verify which components were actually configured using the diagnostic utility. The [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) module provides post-installation verification to confirm which external tools and channels are properly set up in your environment. ## Summary - **Safe mode** (`--safe`) completes the Python installation of Agent Reach but blocks automatic system-level package manager invocations, requiring manual installation of external tools like `brew` or `apt` packages. - **Dry-run** (`--dry-run`) executes a complete simulation of the installation process, outputting a preview of all planned actions without modifying the filesystem or installing any packages. - Safe mode is implemented 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) for security-conscious deployment scenarios. - Dry-run serves as an audit tool to review upstream dependencies before committing to system changes. - Use [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) after installation to verify which components are actually configured. ## Frequently Asked Questions ### Can I combine safe mode with other installation flags? Yes, the `--safe` flag works alongside other parameters such as `--env=auto` and `--channels=twitter,weibo` to scope the installation while preventing system-level package modifications. This allows you to specify exactly which components to install while maintaining the security constraints of safe mode. ### What happens if I run dry-run without safe mode on a restricted system? Dry-run executes without attempting any actual installations or modifications, so it will not trigger permission errors or attempt to use `sudo` regardless of whether you specify `--safe`. It purely simulates the process and outputs the planned actions, making it safe to run in any environment regardless of privileges. ### Does safe mode install Python dependencies for Agent Reach? Yes, safe mode installs the Agent Reach library and all required Python packages via pip or similar Python package managers. It only blocks the automatic installation of system-level packages like those managed by `apt`, `yum`, or `brew`, leaving those for manual installation by the user or administrator. ### What happens if system packages are missing when I use safe mode? When running in safe mode, the installer skips attempts to install missing system packages and continues with the Python setup. You must manually install any required external tools afterward; the [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) utility can help identify which system dependencies remain unconfigured after the installation completes.