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

> Understand Agent-Reach installation differences between safe mode and dry-run mode. Safely audit system changes or preview installer actions without execution.

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

---

**Safe mode audits your system and provides manual installation instructions without making changes, while dry-run mode previews the exact automated steps the installer would execute without performing them.**

When installing the **Agent-Reach** framework using the `agent-reach install` command, you can invoke two mutually exclusive safety flags to control how the installer interacts with your system. Understanding the distinction between **safe mode** (`--safe`) and **dry-run mode** (`--dry-run`) is critical for auditing corporate environments or validating installation procedures before execution.

## Core Differences Between Safe Mode and Dry-Run Mode

Both flags prevent the installer from modifying your system, but they differ significantly in scope and output:

- **Safe mode** performs a complete environment audit and provides manual remediation steps. It executes the standard installer logic—including environment detection, proxy handling, and final channel testing—but substitutes installation functions with reporting variants that only list missing dependencies.
- **Dry-run mode** generates a complete preview of the automated installation flow, showing exactly which system packages would be installed, which optional channels would be added, and what cookie imports would be attempted.

## How Safe Mode Works Under the Hood

In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), invoking `--safe` triggers alternative "safe" variants of the installation functions. Specifically, the installer calls `_install_system_deps_safe()` (lines 65-73) and `_install_mcporter_safe()` (lines 62-70) instead of their standard counterparts.

Safe mode executes the full installer logic but automatically suppresses several automated components through specific conditional guards:

- **Optional channels**: The installation block is guarded by `if not dry_run and not safe_mode`, meaning these channels are **not installed at all** in safe mode.
- **Cookie import**: Extraction from Chrome or Firefox is skipped when the condition `if env == "local" and needs_cookies and not safe_mode and not dry_run` evaluates false due to the `safe_mode` flag.

## How Dry-Run Mode Works Under the Hood

When you pass `--dry-run`, the installer replaces execution functions with preview variants that merely echo intended actions. 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) handles system dependency reporting by printing what would be installed without invoking package managers.

Dry-run mode provides granular visibility into the installation plan through placeholder messages:

- **System dependencies**: Reports which packages would be installed and through which method (e.g., "would install via: curl NodeSource setup | bash + apt install nodejs").
- **Optional channels**: Prints a summary line formatted as `[dry-run] Would install optional channels: twitter, xiaohongshu, reddit`.
- **Cookie import**: Displays `[dry-run] Would try to import cookies from Chrome/Firefox`.

Unlike safe mode, dry-run explicitly shows the automated actions the installer would take, making it ideal for pre-flight validation in CI/CD pipelines.

## Practical Usage Examples

Use **safe mode** when you need to audit a corporate workstation or environment where automatic system changes are prohibited:

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

```

Typical output includes dependency checks and manual instructions:

```

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

```

Use **dry-run mode** when you want to preview the exact automated steps before executing them:

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

```

Expected output shows the complete execution plan:

```

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

```

## Summary

- **Safe mode** (`--safe`) runs the full installer logic but replaces modification functions with reporting variants, providing manual installation instructions rather than executing changes.
- **Dry-run mode** (`--dry-run`) previews every automated action the installer would perform, including system package installation, optional channel setup, and cookie imports.
- Both modes suppress automatic installation of optional channels and cookie extraction, but safe mode focuses on manual remediation guidance while dry-run focuses on execution preview.
- In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), safe mode utilizes `_install_system_deps_safe()` and `_install_mcporter_safe()`, while dry-run uses `_install_system_deps_dryrun()`.

## Frequently Asked Questions

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

No. These flags are mutually exclusive. The installer logic in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) treats them as distinct operational modes, and using both simultaneously would create conflicting execution paths for system dependency handling.

### Does safe mode check if dependencies are already installed?

Yes. Safe mode performs complete environment detection and proxy handling. It executes the standard installer logic but substitutes the installation functions with `_install_system_deps_safe()`, which verifies the presence of tools like GitHub CLI and Node.js and reports their status without attempting automatic remediation.

### Will dry-run mode detect my existing system configuration?

Yes. Dry-run mode performs environment detection to determine what is already present versus what would need installation. The `_install_system_deps_dryrun()` function reports existing installations (e.g., "gh CLI: already installed, skip") while listing the specific commands that would be executed for missing components.

### Which mode should I use on a production server?

Use **dry-run mode** first to preview the automated changes, then execute the standard installation if the preview is acceptable. Safe mode is better suited for development environments or restricted corporate workstations where you need manual control over every system modification. Neither mode makes changes, but dry-run provides the clearest picture of what the automated installer intends to modify.