Agent Reach Safe Mode vs Regular Installation: Key Differences Explained

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, and both can be validated afterward with 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 (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 around lines 39–41:

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 (lines 52–57):

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

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

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

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

Typical safe mode output:

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:

✅ 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 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 (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 (lines 52–57). When this passes, the installer uses 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.

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