# Using Safe Mode vs Dry-Run During Agent-Reach Installation: A Complete Guide

> Learn the difference between Agent-Reach's safe mode and dry-run installation. Understand manual steps vs. full simulation for controlled setup. Get the complete guide here.

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

---

**Agent-Reach's installer supports `--safe` mode (which prints manual steps without system changes) and `--dry-run` mode (which simulates the full installation flow without side effects), both implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) to give you complete control over the setup process.**

Agent-Reach provides a one-shot installer (`agent-reach install`) that can operate in three distinct modes depending on your security requirements and environment constraints. When you need to understand exactly what the installer will modify without actually touching your system, you can leverage either **safe mode** or **dry-run mode** during installation. These flags are parsed in the CLI entry point and propagated through the entire installation orchestration logic defined in the `Panniantong/Agent-Reach` repository.

## Understanding the Three Installation Modes

The installer distinguishes between normal execution, safe mode, and dry-run through boolean flags extracted at the start of `_cmd_install` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 71-80):

```python
safe_mode = args.safe          # <-- True when --safe is passed

dry_run   = args.dry_run       # <-- True when --dry-run is passed

```

### Normal Mode

In normal mode, the installer executes all installation steps, modifies the system by installing dependencies, writes configuration files, imports cookies from browsers, and registers skills. Use this for first-time installations on trusted machines where you want the tool fully set up.

### Safe Mode (--safe)

**Safe mode** (`--safe`) never runs any automatic system changes. Instead, it inspects the environment, prints a checklist of missing prerequisites, and tells you exactly which commands you need to run manually. This is ideal when you have limited permissions on a corporate workstation or when you want to verify what the installer would do without affecting the system.

### Dry-Run Mode (--dry-run)

**Dry-run** mode (`--dry-run`) simulates the whole install flow, printing the same messages as a normal run but skipping every step that would change the filesystem or install software. This provides a quick preview of actions (including optional channel installations) without any side effects.

## How Safe Mode Works Under the Hood

When you pass `--safe`, the installer routes execution through specialized functions that audit rather than modify your environment.

### System Dependency Checking

In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the function `_install_system_deps_safe()` (lines 44-70) merely reports which binaries are present and prints manual installation hints. It does not invoke package managers or modify system paths.

### Channel Installation Guards

The logic that would invoke optional installers (`_install_twitter_deps`, `_install_xhs_deps`, etc.) is guarded by the condition `if not safe_mode and not dry_run`. Therefore, none of the channel-specific binaries are fetched or compiled when safe mode is active.

### Cookie Import Bypass

Cookie extraction from the browser is also skipped when `safe_mode` is true. The block at lines 730-770 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) is completely bypassed, preventing any access to browser data directories.

### Final Manual Guidance

After completing the safe-mode inspection, the installer prints specific guidance on how to proceed manually, such as "Run `pipx install twitter-cli`" or "Install Node.js via your package manager."

## How Dry-Run Works Under the Hood

The dry-run path mirrors the normal flow but substitutes every mutating call with a "what-would-be-done" message, making it completely side-effect-free while exercising the same decision logic.

### Simulated System Dependencies

The function `_install_system_deps_dryrun()` (lines 72-89 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)) prints a checklist of tools that would be installed without executing any external commands.

### Channel Simulation

For optional channel installers, the dry-run path prints a summary line like `[dry-run] Would install optional channels: …` (see the block at lines 660-670). No network requests or compilation occurs.

### Cookie Import Simulation

The installer prints `[dry-run] Would try to import cookies from Chrome/Firefox` (lines 730-740) without accessing browser databases or writing cookie files to disk.

### Environment Detection

Both modes still execute `_detect_environment()` (lines 55-94), which distinguishes "local" vs "server" environments based on SSH variables, container files, display variables, and cloud-VM markers. This ensures the simulation accurately reflects what would happen in your specific context.

## Code Examples and CLI Usage

Here are practical examples showing how to use these flags with the `agent-reach` CLI:

```bash

# Show a dry-run of a full install (no changes made)

agent-reach install --dry-run --channels=all

# Run in safe-mode – the installer prints manual steps only

agent-reach install --safe --channels=twitter,reddit

# Normal install on a local machine (default mode)

agent-reach install --env=local --channels=twitter,xhs

# Combine flags – safe-mode overrides dry-run

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

# → behaves like safe-mode (dry-run is ignored because safe-mode already skips actions)

```

## Summary

- **Safe mode** (`--safe`) in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) audits your environment and outputs manual instructions without executing system commands or installing dependencies.
- **Dry-run** (`--dry-run`) simulates the complete installation flow, printing what would happen at each step (lines 660-670, 730-740) without modifying the filesystem or importing cookies.
- Both modes respect the same environment detection logic (`_detect_environment`) and channel selection, ensuring accurate previews.
- When combined, safe mode takes precedence over dry-run, as the safer option always wins.

## Frequently Asked Questions

### What is the difference between safe mode and dry-run in Agent-Reach?

Safe mode (`--safe`) inspects your system and prints a checklist of manual commands you need to run, while dry-run (`--dry-run`) simulates the automatic installation flow showing what *would* be executed without actually performing the actions. Safe mode is designed for environments where you cannot run automated installers, whereas dry-run is for previewing changes before committing to them.

### Can I combine the --safe and --dry-run flags?

Yes, you can pass both flags simultaneously, but safe mode overrides dry-run when combined. According to the implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), if `--safe` is true, the installer prioritizes the safe-mode path (lines 44-70), meaning you will see the manual checklist rather than the dry-run simulation.

### Does dry-run check system dependencies?

Yes, dry-run performs environment detection and dependency checking through `_install_system_deps_dryrun()` (lines 72-89), which prints a checklist of tools that would be installed. It exercises the same logic as the normal install to identify missing prerequisites, but it never executes `subprocess.run` calls or writes to the filesystem.

### Will safe mode attempt to import my browser cookies?

No, safe mode explicitly skips cookie extraction. The cookie import block at lines 730-770 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) is bypassed when `safe_mode` is true, preventing any access to Chrome or Firefox data directories and ensuring no personal data is processed during the inspection.