# Difference Between --safe Mode and Normal Installation in Agent Reach

> Explore how Agent Reach's --safe mode differs from normal installation. Understand Agent Reach's safe mode to preview actions without system changes while normal install automates setup.

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

---

**Agent Reach's `--safe` mode skips all automatic system modifications and only displays what actions would be taken, while a normal installation performs system dependency setup, Exa search configuration, optional channel installations, and browser cookie imports automatically.**

The `install` sub-command in the Panniantong/Agent-Reach repository controls how the framework configures your environment. Understanding the difference between `--safe` mode and normal installation helps you choose between a fully automated setup versus a preview-only approach that respects restrictive system policies.

## System Dependency Handling

In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the installer checks the `--safe` flag at lines 22-27 to determine how to handle system dependencies. When `--safe` is active, the code calls `_install_system_deps_safe()`, which prints a list of required packages like `git`, `pip`, and `ffmpeg` without installing them. A normal installation invokes `_install_system_deps()` to automatically install these lightweight dependencies on your host system.

## Exa Search Configuration

The Exa search integration (mcporter) follows the same branching pattern. Safe mode triggers `_install_mcporter_safe()`, displaying manual download instructions for the `mcporter` binary and configuration steps. Regular mode executes `_install_mcporter()`, which automatically downloads, installs, and configures Exa search capabilities for immediate use.

## Optional Channel Installation

At lines 39-41 of [`cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cli.py), the installer evaluates the conditional block `if requested_channels and not dry_run and not safe_mode:`. In safe mode, this logic is bypassed entirely, meaning channel-specific dependencies for Twitter, Reddit, or other platforms are not installed. Normal installation processes this block and invokes handlers like `_install_twitter_deps()` or `_install_reddit_deps()` to set up platform-specific requirements automatically.

## Browser Cookie Auto-Import

Lines 52-57 contain the conditional `if env == "local" and needs_cookies and not safe_mode and not dry_run:`. Safe mode bypasses this logic, preventing automatic extraction of browser cookies needed for platforms like Twitter, Xueqiu, and Bilibili. Normal installation reads these cookies automatically when the local environment requires authentication data.

## Safe Mode vs. Dry-Run

Safe mode differs from `--dry-run` in that it still performs partial configuration. While safe mode avoids system modifications, it still creates the tools folder and performs other non-invasive setup steps. Dry-run prevents all changes, whereas safe mode installs only what is deemed safe while reporting everything else that would normally happen.

## CLI Usage Examples

Run a regular installation to enable full automation:

```bash
agent-reach install --env=auto --channels=twitter,reddit

```

Run safe mode to preview requirements without system changes:

```bash
agent-reach install --safe --env=auto --channels=twitter,reddit

```

Safe mode produces output like:

```

SAFE MODE — skipping automatic system changes

# System deps: you need git, python ≥3.10, ffmpeg, etc.

# mcporter: download from https://github.com/...

# Optional channels: twitter, reddit – install them manually if desired.

```

Regular installation produces output like:

```

✅ System dependencies installed
✅ mcporter installed for Exa search
Installing optional channels...
✅ Twitter deps installed
✅ Reddit deps installed
Importing cookies from browser...
✅ twitter: cookies loaded
✅ Installation complete! 7/7 channels active.

```

## Source Code Implementation

The `--safe` flag is defined at lines 67-68 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py). The installer logic branches based on this boolean to choose between safe variants (`_install_system_deps_safe`, `_install_mcporter_safe`) and standard implementation functions. Critical conditional blocks at lines 39-41 and 52-57 explicitly check `not safe_mode` before executing automatic configuration steps, ensuring that safe mode remains non-invasive.

## Summary

- Safe mode calls `_install_system_deps_safe()` and `_install_mcporter_safe()` to preview changes, while normal installation calls the non-safe variants to execute changes.
- Safe mode skips optional channel dependency installation and browser cookie imports entirely by failing the `not safe_mode` conditionals.
- Safe mode still creates the tools folder, unlike `--dry-run` which prevents all changes.
- Safe mode prints "SAFE MODE — skipping automatic system changes" while normal installation performs actions silently unless `--verbose` is set.

## Frequently Asked Questions

### Does safe mode install anything at all?

Yes. Safe mode still creates the tools folder and performs other non-invasive setup steps. It only skips automatic system modifications like package installation and cookie extraction. Pair it with `--dry-run` to prevent all changes.

### Can I use --channels with --safe mode?

You can specify the flag, but the installer will skip the channel installation block at lines 39-41 of [`cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cli.py). The code explicitly checks `not safe_mode` before calling channel-specific installers like `_install_twitter_deps()`, so no channel dependencies are installed automatically.

### Why does safe mode skip cookie imports?

The conditional at lines 52-57 requires `not safe_mode` to be true. This prevents automatic browser cookie extraction on restrictive systems where users may not want applications accessing their browser data or where cookie files require manual configuration for security compliance.

### Which mode should I use on a locked-down enterprise machine?

Use `--safe` mode first to generate the list of required system dependencies and manual steps. Review the output with your system administrator, then perform a normal installation once approvals are granted and dependencies are manually installed.