# Agent Reach Safe Mode vs Regular Installation: Key Differences Explained

> Understand Agent Reach safe mode vs regular installation. Learn how --safe mode reports changes without executing them, unlike a standard install that modifies your system automatically.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: deep-dive
- Published: 2026-06-07

---

**Agent Reach's `--safe` flag skips all automatic system modifications and only reports what would be required, while a regular installation executes every system change, optional channel setup, and cookie import automatically.**

Agent Reach is an open-source automation framework whose installer behavior changes significantly depending on whether you invoke the `install` command with the `--safe` flag. Understanding the distinction between safe mode and regular installation helps you decide which approach fits restricted environments versus standard setups. Both paths are driven by the `install` sub-command in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), and both can be validated afterward with [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py).

## How the `--safe` Flag Is Parsed

The installer receives the `--safe` argument through the CLI definition in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 67–68). When this flag is present, the script sets an internal `safe_mode` boolean that gates every destructive operation. Without the flag, the same boolean remains `False`, and the installer proceeds to modify the host automatically.

## System Dependency Handling

**Safe mode** delegates dependency reporting to `_install_system_deps_safe()`. This helper prints a short “What you need” list—typically `git`, `pip`, `ffmpeg`, and Python ≥3.10—without invoking the package manager.

**Regular installation** calls `_install_system_deps()` instead. According to the Panniantong/Agent-Reach source code, this function installs the lightweight system packages directly so the user does not have to fetch them manually.

## Exa Search (`mcporter`) Setup

Agent Reach relies on `mcporter` for Exa search capabilities. The installer chooses between two implementations based on `safe_mode`:

- **`_install_mcporter_safe()`** — Called when `--safe` is active. It prints the manual steps required to download and configure `mcporter`, but it writes nothing to the system.
- **`_install_mcporter()`** — Called during a regular installation. It actually installs `mcporter` and wires up Exa search automatically.

## Optional Channel Installation Behavior

If you pass `--channels` (for example, `twitter` or `reddit`), the installer evaluates the block in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) around lines 39–41:

```python
if requested_channels and not dry_run and not safe_mode:
    # Install channel-specific dependencies

```

**In safe mode**, this block is skipped entirely. You will see a note that channels such as Twitter or Reddit need manual installation, but no channel-specific dependencies are pulled.

**In regular mode**, the condition passes and the installer invokes helpers like `_install_twitter_deps` or `_install_reddit_deps`, leaving the channels ready for immediate use.

## Browser Cookie Auto-Import Logic

Some channels require browser cookies. The installer handles this in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 52–57):

```python
if env == "local" and needs_cookies and not safe_mode and not dry_run:
    # Import cookies from the browser

```

**In safe mode**, the cookie import is bypassed. The user must later supply credentials or cookies manually.

**In regular mode**, the installer reads browser cookies for platforms that need them—such as Twitter, Xueqiu, and Bilibili—via [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) so the channels can authenticate out of the box.

## Safe Mode Is Not the Same as `--dry-run`

A common misconception is that `--safe` prevents all file system changes. In reality, safe mode still performs limited setup work, such as creating the tools folder, unless you also add `--dry-run`.

| Flag combination | Effect |
|---|---|
| `--safe` alone | Skips automatic system modifications, but may still create directories |
| `--dry-run` alone | Previews changes without writing them, but assumes a regular install plan |
| `--safe --dry-run` | Previews only; makes no system changes and no channel installations |

Choose `--safe` when you need to inspect required steps on a locked-down machine. Add `--dry-run` if you want a true no-op preview.

## Practical Examples

Run a **regular installation** that installs system deps, `mcporter`, optional channels, and imports cookies:

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

```

Run a **safe-mode installation** that only reports what would be done:

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

```

**Typical safe mode output:**

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

```

**Typical regular mode output:**

```text
✅ 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.

```

## Summary

- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** drives both installation paths and evaluates the `--safe` flag at lines 67–68.
- **Safe mode** calls `_install_system_deps_safe()` and `_install_mcporter_safe()` to list requirements rather than fulfilling them.
- **Regular installation** calls `_install_system_deps()` and `_install_mcporter()` to modify the system automatically.
- Optional channel dependencies are installed only during regular mode; safe mode skips the `requested_channels` block entirely.
- Browser cookie imports are gated by `not safe_mode`; safe mode always defers authentication setup.
- `--safe` is not `--dry-run`: safe mode may still create folders, so pair the flags if you need a zero-change preview.

## Frequently Asked Questions

### Does safe mode install anything at all?

Safe mode may still create the tools folder and perform lightweight setup steps. It only guarantees that automatic system modifications—such as package installation and cookie imports—are skipped. If you need a completely non-destructive preview, run `agent-reach install --safe --dry-run`.

### Can I use `--channels` with `--safe` to see what would be installed?

Yes, but the installer will only print a notice. The conditional block `if requested_channels and not dry_run and not safe_mode:` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 39–41) prevents `_install_twitter_deps`, `_install_reddit_deps`, and similar helpers from executing, so no channel packages are actually pulled.

### Why does regular installation import browser cookies automatically?

Regular mode evaluates `if env == "local" and needs_cookies and not safe_mode and not dry_run:` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 52–57). When this passes, the installer uses [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) to read cookies from your browser for channels like Twitter, Xueqiu, and Bilibili so they are ready for immediate authentication.

### Which installation mode should I choose for a production or locked-down server?

Start with `--safe`. It gives you the exact checklist of system dependencies, manual `mcporter` steps, and channel requirements without requiring root access or package managers. Once you have reviewed the output, you can rerun without `--safe` if the environment permits full automation.