# Agent Reach Safe Mode vs Dry-Run: Understanding the Difference During Installation

> Understand Agent Reach safe mode vs dry-run during installation. Safe mode prevents system package installs. Dry-run shows installer actions without changes. Learn the difference now.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-06

---

**Safe mode** prevents the installer from automatically installing system-level packages while completing Python-side setup, whereas **dry-run** generates a preview of every step the installer would perform without modifying your system.

When installing the Agent Reach toolkit from the `Panniantong/Agent-Reach` repository, understanding the distinction between **safe mode** and **dry-run** helps you maintain system security and verify installation steps before committing changes. These flags control how the `agent-reach install` command interacts with your operating system's package managers and whether it actually modifies your environment.

## Core Differences Between Safe Mode and Dry-Run

### What is Safe Mode?

In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the `--safe` flag configures the installer to skip all automatic system-level package installations. When activated, the installer will not invoke `brew`, `apt`, `yum`, or other package managers.

- **Effect**: Only Python packages and the Agent Reach library itself are installed; the host OS remains untouched.
- **Use Case**: Essential for locked-down workstations, CI environments that prohibit `sudo`, or scenarios requiring manual oversight of system dependencies.

### What is Dry-Run Mode?

The `--dry-run` flag, also defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), instructs the installer to simulate every action without executing it.

- **Effect**: The command prints a complete preview of planned installation steps and exits without creating files or installing packages.
- **Use Case**: Perfect for auditing which upstream tools would be fetched or validating installation logic in production deployment scripts.

## Technical Implementation

According to the source code in `Panniantong/Agent-Reach`, these behaviors are controlled through specific files:

- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)**: Defines the argument parsers for `--safe` and `--dry-run` flags that modify installer execution flow.
- **[`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md)**: Documents safe mode as preventing "auto-install of system packages" and dry-run as providing a "preview what would be done" capability.
- **[`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, particularly useful after running safe mode to identify missing manual dependencies.

## Practical CLI Examples

```bash

# Safe mode - installs Python components only, skips system package managers

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

# Dry-run - displays planned actions without executing them

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

# Combined with channel scoping while respecting safety constraints

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

```

## When to Use Each Mode

**Safe mode** is ideal for security-conscious environments where package manager access is restricted or when you require explicit control over system-level dependencies like compilers or system libraries.

**Dry-run** is essential for continuous integration pipelines requiring pre-validation, or when you need to audit the complete list of external tools the installer would retrieve before allocating resources.

Both flags can be combined with other installation parameters to scope the deployment while respecting your chosen safety constraints.

## Summary

- **Safe mode** (`--safe`) blocks automatic installation of system packages while completing Python library setup.
- **Dry-run** (`--dry-run`) simulates the entire installation process without modifying your file system or installing any packages.
- Both behaviors are 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).
- Safe mode suits restricted environments; dry-run suits pre-installation auditing and CI validation.
- Use [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) after safe mode installation to verify which components require manual setup.

## Frequently Asked Questions

### Can I use safe mode and dry-run together?

Yes. You can execute `agent-reach install --safe --dry-run` to preview only the Python-side installation steps without triggering system package checks or making any changes. This combination is useful for auditing the Python dependency tree in restricted environments.

### Does safe mode prevent all installations or just system packages?

Safe mode specifically prevents automatic installation of system-level packages through managers like `apt`, `brew`, or `yum` as described in [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md). It still installs the Python components of Agent Reach and its Python dependencies.

### Will dry-run detect missing system dependencies?

Dry-run will list the system packages it *would* attempt to install, effectively showing you what dependencies are missing. However, it does not validate whether those packages are available in your repositories or whether your user account has the privileges required to install them.

### How do I verify what was actually installed after using safe mode?

Run the diagnostic utility implemented in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) (typically invoked via `agent-reach doctor`). This checks which components were successfully set up and identifies any system-level packages you still need to install manually after using safe mode.