# What Does the `--safe` Flag Do in `agent-reach install`?

> Discover what the --safe flag does in agent-reach install. Run the installer in read-only diagnostic mode, verifying system dependencies without altering your system.

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

---

**The `--safe` flag runs the Agent Reach installer in read-only diagnostic mode, checking for system dependencies and optional components without making any changes to your system.**

When you run the installation command for the Panniantong/Agent-Reach CLI, the `--safe` flag transforms the process from an automated setup into a non-invasive audit. Instead of installing GitHub CLI, Node.js, or the `mcporter` binary, the tool scans your environment and reports what is missing along with manual installation instructions. This mode is ideal for production environments, CI/CD pipelines, or any system where you want complete control over package installation.

## How the `--safe` Flag Works

The flag is defined in the CLI argument parser at [[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) lines 71-73](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L71-L73). When parsing completes, the value is stored in the variable `safe_mode = args.safe` at [line 77](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L77).

This boolean flag controls execution flow through four major decision points:

- **System dependencies** ([lines 45-52](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L45-L52)): Skips automatic installation of GitHub CLI and Node.js
- **McPorter binary** ([lines 54-62](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L54-L62)): Skips the `npm install -g mcporter` execution
- **Optional channels** ([lines 69-70](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L69-L70)): Completely bypasses installation of Twitter, Reddit, Bilibili, and other channel backends
- **Cookie imports** ([lines 85-86](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L85-L86)): Guards against auto-importing browser cookies for Twitter, Reddit, and XiaoHongShu

## System-Level Dependency Checks

In standard mode, the installer automatically fetches and installs missing system binaries. With `--safe`, the logic routes through `_install_system_deps_safe` ([lines 665-692](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L665-L692)), which performs a read-only verification.

The function checks for the presence of required binaries and prints a concise status report:

- **Green checkmarks** for existing tools
- **Manual installation hints** for missing dependencies, including package manager commands or URLs

This allows administrators to review exactly what the installer would have done before granting permission to modify the system.

## McPorter Binary Verification

The `mcporter` binary is required for Exa search functionality. Normally, the installer runs `npm install -g mcporter` automatically. Under `--safe`, the execution branches to `_install_mcporter_safe` ([lines 662-674](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L662-L674)).

This helper function verifies whether `mcporter` exists in your `$PATH` and outputs instructions for manual installation if needed. It also displays configuration commands for connecting Exa search, ensuring you have the complete setup sequence without the tool touching your Node.js environment.

## Optional Components Disabled in Safe Mode

Safe mode explicitly prevents two categories of optional system modifications:

**Channel Backends:** The installer prints "SAFE MODE — skipping automatic system changes" and bypasses all optional channel installations. This includes social media integrations that would normally configure API access for Twitter, Reddit, Bilibili, and other platforms.

**Browser Cookie Imports:** The auto-import feature that extracts authentication cookies from your browser is completely disabled. This ensures the installer never reads browser data or writes cookie files to disk, addressing privacy and security concerns in shared or sensitive environments.

## Running Safe Mode in Practice

Execute a diagnostic installation check without system modifications:

```bash
$ agent-reach install --safe
Agent Reach Installer
========================================
SAFE MODE — skipping automatic system changes

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

Checking mcporter (safe mode)...
  -- mcporter not installed
  To install: npm install -g mcporter
  Then configure Exa search: mcporter config add exa https://mcp.exa.ai/mcp

```

The `--safe` flag is independent of `--dry-run`. You can combine both flags to see the dry-run output format while maintaining the guarantee of zero system changes:

```bash
$ agent-reach install --safe --dry-run
[dry-run] System dependency check:
  GitHub CLI: already installed, skip
  Node.js: would install via: curl NodeSource setup | bash + apt install nodejs
...

```

## Summary

- The `--safe` flag in `agent-reach install` activates a **read-only diagnostic mode** that audits your system without making changes.
- It routes execution through `_install_system_deps_safe` and `_install_mcporter_safe` to check for missing binaries rather than installing them.
- **Optional channel backends** and **browser cookie imports** are completely skipped when safe mode is active.
- The flag is parsed in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and stored in the `safe_mode` variable that guards four major installation phases.
- Safe mode can be combined with `--dry-run` for additional safety in CI/CD environments.

## Frequently Asked Questions

### Can I combine `--safe` with other installation flags?

Yes. The `--safe` flag operates independently of other options like `--dry-run` or `--verbose`. Combining `--safe --dry-run` provides the most conservative approach, showing you exactly what the installer would do in a completely non-invasive format. The `safe_mode` boolean simply forces the conditional checks at lines 69-70 and 85-86 to skip all mutation operations.

### Why does safe mode skip the mcporter binary installation?

According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the `mcporter` binary requires a global npm install (`npm install -g mcporter`), which modifies your Node.js environment. The `_install_mcporter_safe` function (lines 662-674) replaces this with a presence check and manual instructions, ensuring you maintain control over global package installations while still receiving guidance on configuring Exa search.

### Does `--safe` prevent the installer from touching my browser data?

Yes. Lines 85-86 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) explicitly guard cookie import operations with `if not safe_mode`. When the flag is present, the installer will not attempt to read browser cookies for Twitter, Reddit, or XiaoHongShu, nor will it write any cookie files to disk. This ensures complete privacy regarding your browser session data.

### How do I install dependencies manually after running `--safe`?

After running `agent-reach install --safe`, the CLI outputs specific manual installation commands for each missing dependency. For Node.js, it suggests either visiting https://nodejs.org or using `apt install nodejs npm`. For `mcporter`, it provides the exact `npm install -g mcporter` command and the configuration string for Exa search. You can execute these commands with your preferred package manager before re-running the standard installation.