# How to Run Agent-Reach in Safe Mode vs Dry-Run: A Complete Guide

> Learn how to run Agent-Reach in safe mode or dry-run. Audit system changes with --safe or simulate installation with --dry-run for zero side effects. A complete guide.

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

---

**Run `agent-reach install --safe` to audit system changes without installing dependencies, or use `--dry-run` to simulate the entire installation process without any side effects.**

The Agent-Reach installer provides two distinct non-destructive execution paths for the `agent-reach install` command. These modes allow you to preview changes before committing them or audit dependencies when you lack system privileges. Understanding how to run agent-reach in safe mode vs dry-run ensures you can deploy the tool safely across different environments, from shared servers to CI pipelines.

## Understanding Safe Mode vs Dry-Run

Both flags prevent unwanted system modifications, but they serve different purposes during the installation process.

### What is Safe Mode?

**Safe mode** (`--safe`) skips automatic system-level changes while providing manual installation instructions. When enabled, the installer prints the current status of each dependency and outputs explicit commands for manual configuration rather than executing them automatically.

This mode is ideal when you want to audit what would be changed or when you lack privileges to modify the host system. Use it on shared servers, restricted CI pipelines, or when you prefer to review changes before they happen.

### What is Dry-Run?

**Dry-run** (`--dry-run`) simulates the entire installation process without writing to disk, installing packages, or modifying the environment. It shows which steps would be taken, which optional channels would be added, and which cookies would be imported.

Use this mode when you want a quick "what-if" preview without any side effects, particularly for scripting or documentation purposes.

## CLI Flag Definitions in agent_reach/cli.py

The command-line interface defines both options in **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** using `argparse` (lines 71-74):

```python
p_install.add_argument("--safe", action="store_true",
                       help="Safe mode: skip automatic system changes, show what's needed instead")
p_install.add_argument("--dry-run", action="store_true",
                       help="Show what would be done without making any changes")

```

These arguments are stored in `args.safe` and `args.dry_run` and are consulted throughout the installer logic. The flags are mutually independent—you can combine them (`--safe --dry-run`) to get a safe-mode preview that also avoids any side effects.

## Safe Mode Implementation Details

When `--safe` is passed, the installer branches to dedicated helper functions that report status rather than mutate the system.

### System Dependency Checks

At the start of installation, the flag triggers a status message (lines 92-95):

```python
if safe_mode:
    print("SAFE MODE — skipping automatic system changes")

```

The system dependency handling then branches to `_install_system_deps_safe()` (lines 240-242):

```python
elif safe_mode:
    _install_system_deps_safe()

```

This helper function (lines 443-470) walks through a static list of required tools and prints installation hints for missing dependencies:

```python
def _install_system_deps_safe():
    """Safe mode: check what's installed, print instructions for what's missing."""
    for name, binaries, label, install_hint in deps:
        found = any(shutil.which(b) for b in binaries)
        if found:
            print(f"  ✅ {label} already installed")
        else:
            print(f"  -- {label} not found")
            missing.append((label, install_hint))

```

### McPorter Configuration

An analogous safe path exists for the **mcporter** tool via `_install_mcporter_safe()` (lines 440-452). This function reports the tool's presence and prints a manual configuration command if needed, without automatically modifying system settings.

## Dry-Run Implementation Details

The dry-run flag short-circuits each mutable step to prevent any system changes:

- **System dependencies**: `_install_system_deps_dryrun()` (lines 722-733) prints what would be checked or installed without invoking system commands.
- **McPorter**: `_install_mcporter_dryrun()` outputs a "would install" message.
- **Optional channels**: The installer skips actual channel installers when `dry_run` is true, printing a summary line instead (lines 267-270).
- **Cookie import**: When enabled, the code prints a placeholder message rather than reading the browser's cookie store (lines 296-298).

At completion (lines 389-391), the CLI outputs: "Dry run complete. No changes were made."

## Practical Code Examples

Run Agent-Reach in safe mode to audit dependencies:

```bash

# Safe mode – only reports missing system dependencies

agent-reach install --safe

```

Expected output:

```

SAFE MODE — skipping automatic system changes

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

```

Run a complete simulation with dry-run:

```bash

# Dry-run – full “what-will-happen” preview, no side-effects

agent-reach install --dry-run

```

Combine both flags for maximum safety:

```bash

# Combine both – safe-mode preview that never mutates the host

agent-reach install --safe --dry-run

```

Preview specific channel installations:

```bash

# Typical usage with optional channels (dry-run shows the channel list)

agent-reach install --channels=twitter,reddit --dry-run

```

## Summary

- **Safe mode** (`--safe`) audits system dependencies and prints manual installation instructions without automatically modifying the system, implemented in `_install_system_deps_safe()` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).
- **Dry-run** (`--dry-run`) simulates the entire installation process without writing to disk or executing system commands, using helpers like `_install_system_deps_dryrun()`.
- Both flags can be combined to preview safe-mode instructions without any side effects.
- The flags are defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) lines 71-74 and stored in `args.safe` and `args.dry_run` for conditional logic throughout the installer.

## Frequently Asked Questions

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

Yes. The flags are mutually independent and can be combined as `agent-reach install --safe --dry-run`. This combination provides a safe-mode preview that also avoids any side effects, showing you the manual installation instructions while ensuring zero system modifications.

### What files handle the safe mode and dry-run logic in Agent-Reach?

The primary implementation resides in **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)**. Safe mode logic is handled by `_install_system_deps_safe()` and `_install_mcporter_safe()` around lines 443-470, while dry-run logic uses `_install_system_deps_dryrun()` and related helpers around lines 722-733.

### When should I choose safe mode over dry-run?

Choose **safe mode** when you need to audit actual system dependencies and want specific manual installation instructions for your environment. Choose **dry-run** when you want a quick simulation of the entire process without detailed dependency checking, such as for scripting or documentation generation. Safe mode is preferred when you lack administrative privileges and need installation guidance.

### Does dry-run check if dependencies are already installed?

Yes, but differently than safe mode. In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the `_install_system_deps_dryrun()` function prints what would be checked or installed, showing the installation method that would be used (e.g., "would install via: curl NodeSource setup | bash"), whereas safe mode actually checks for binaries and reports their real-time presence using `shutil.which()`.