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

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 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 (lines 71-80):

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, 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 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) 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:

# 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 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}