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

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

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

Run safe mode to preview requirements without system changes:

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

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