# Safe Mode vs Dry-Run During Agent Reach Installation: Key Differences Explained

> Understand the critical differences between Safe Mode and Dry-Run for Agent Reach installation. Learn when to use each to ensure a smooth and controlled setup process.

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

---

**Safe mode skips automatic system changes and provides manual installation instructions, while dry-run previews every action the installer would take without executing any of them.**

When installing the Panniantong/Agent-Reach framework using the `agent-reach install` command, you can use two mutually exclusive flags to prevent automatic system modifications. Understanding the difference between **safe mode** and **dry-run** ensures you choose the right audit or preview strategy for your environment before the installer touches any dependencies.

## Core Differences Between Safe Mode and Dry-Run

### What Safe Mode Does

In safe mode, the installer runs the standard environment detection, proxy handling, and final channel testing logic, but replaces the actual installation functions with "safe" variants that only report missing tools. According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the functions `_install_system_deps_safe()` (lines 65-73) and `_install_mcporter_safe()` (lines 62-70) verify existing system tools and output manual installation instructions rather than installing them automatically.

Safe mode also suppresses automatic cookie imports from Chrome/Firefox and prevents the installation of optional channels. The code explicitly guards these actions with conditional blocks like `if not dry_run and not safe_mode` for optional channels, and `if env == "local" and needs_cookies and not safe_mode and not dry_run` for cookie imports.

### What Dry-Run Does

Dry-run performs a complete preview of the installation flow without touching the system. The installer echoes every planned action, including which system packages would be installed and which optional channels would be added. In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the function `_install_system_deps_dryrun()` (lines 94-102) demonstrates this behavior by showing exactly which dependencies are missing and the specific installation commands that would be executed.

Unlike safe mode, dry-run simulates the full execution path, printing placeholders like `[dry-run] Would try to import cookies from Chrome/Firefox` and `[dry-run] Would install optional channels: twitter, xiaohongshu, reddit`.

## Technical Implementation in Agent Reach

### System Dependency Handling

The installer implements separate pathways for each mode in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py):

- **Safe mode**: Uses `_install_system_deps_safe()` to verify existing tools and output manual fix instructions for missing dependencies.
- **Dry-run**: Uses `_install_system_deps_dryrun()` to display the exact installation commands that would be executed, including package manager calls and setup scripts.

### Optional Channels and Cookie Import

Both flags prevent automatic modifications, but behave differently:

- **Safe mode**: Completely skips optional channel installation and cookie extraction.
- **Dry-run**: Prints preview messages indicating which channels would be installed and which browser cookies would be imported.

## Command Examples and Expected Output

To audit your environment with safe mode:

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

```

Typical safe-mode output:

```

Agent Reach Installer
========================================
SAFE MODE — skipping automatic system changes

Checking system dependencies (safe mode — no auto‑install)...
  ✅ GitHub CLI already installed
  -- Node.js not found
  To install missing dependencies manually:
    Node.js: https://nodejs.org — or: apt install nodejs npm

...

```

To preview the installation without making changes:

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

```

Typical dry-run output:

```

DRY RUN — showing what would be done (no changes)

[dry-run] System dependency check:
  gh CLI: already installed, skip
  Node.js: would install via: curl NodeSource setup | bash + apt install nodejs

[dry-run] Would install optional channels: twitter, xiaohongshu, reddit
[dry-run] Would try to import cookies from Chrome/Firefox
...
Dry run complete. No changes were made.

```

## When to Use Each Mode

Use **safe mode** when you need to audit a corporate workstation or production environment where automatic package installation is prohibited. It tells you exactly what's missing and provides the manual steps required to fix it.

Use **dry-run** when you want to see the complete execution plan before committing to changes. This is ideal for CI/CD pipelines or automation scripts where you need to verify the installer's behavior in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) beforehand.

## Summary

- **Safe mode** runs installer logic but reports missing dependencies instead of installing them, providing manual instructions via `_install_system_deps_safe()` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).
- **Dry-run** previews every action without system changes, using `_install_system_deps_dryrun()` to echo planned installations and optional channel additions.
- Both flags prevent automatic cookie imports and optional channel installation, but dry-run shows what would happen while safe mode simply skips these steps.
- Safe mode is designed for auditing environments where no automatic changes are permitted, while dry-run is designed for previewing the full installation workflow step-by-step.

## Frequently Asked Questions

### Can I use both --safe and --dry-run flags together?

No, these flags are mutually exclusive. The `agent-reach install` command in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) treats them as separate operational modes—safe mode runs the detection logic with manual reporting, while dry-run simulates the full installation flow. Attempting to use both typically results in the last flag taking precedence or the installer rejecting the combination.

### Will safe mode detect missing Node.js or GitHub CLI installations?

Yes, safe mode actively checks for system dependencies using `_install_system_deps_safe()` and reports the status of each tool. It prints specific manual installation instructions for any missing dependencies, such as Node.js download URLs or package manager commands like `apt install nodejs npm`.

### Does dry-run actually download any packages or modify configuration files?

No, dry-run makes zero system changes. According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), dry-run functions only print messages indicating what would be done. No network requests are made, no packages are downloaded, and no files are modified during a dry-run execution.

### Which mode should I use on a locked-down corporate workstation?

Use **safe mode** (`--safe`). It ensures no automatic system changes occur while still providing you with a complete audit of missing dependencies and manual installation steps required to prepare the environment without violating IT policies.