# Agent Reach Safe Mode Installation: Complete Implementation Guide

> Learn Agent Reach safe mode installation to preview system changes before modifying your environment. Audit dependencies like GitHub CLI and Node.js with the --safe flag.

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

---

**Agent Reach safe mode installation lets you preview required system changes without modifying your environment by passing the `--safe` flag to audit dependencies like GitHub CLI, Node.js, and mcporter.**

Agent Reach safe mode installation provides a zero-impact way to validate prerequisites before committing to a full setup. In the `Panniantong/Agent-Reach` repository, this feature is implemented as a command-line flag that intercepts automatic system modifications and instead generates manual installation instructions. This approach ensures transparency when deploying in restricted environments or when auditing system requirements.

## How Agent Reach Safe Mode Installation Works

### The --safe CLI Flag Definition

In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) at lines 71-73, the installer defines the `--safe` argument using Python's argparse library:

```python
p_install.add_argument("--safe", action="store_true",
                       help="Safe mode: skip automatic system changes, show what's needed instead")

```

This flag is added to the `install` sub-command and defaults to `False` unless explicitly invoked.

### Flag Handling in _cmd_install

The installation command handler captures this flag at lines 77-78 and stores it in a local variable for later conditional checks:

```python
safe_mode = args.safe

```

This boolean determines whether the installer calls the standard dependency installer or the safe-mode variant.

### System Dependency Validation Without Modifications

When `safe_mode` evaluates to `True`, the code at lines 40-44 branches away from `_install_system_deps` and instead invokes `_install_system_deps_safe()`:

```python
elif safe_mode:
    _install_system_deps_safe()

```

The `_install_system_deps_safe` function (lines 843-870) walks through the same dependency list—including **GitHub CLI** and **Node.js**—but **does not modify the system**. It checks binary presence and prints manual installation commands for any missing components rather than invoking `apt`, `npm`, or other package managers.

### mcporter Backend Verification

The Exa-search backend follows an identical pattern. At lines 48-52, safe-mode redirects to `_install_mcporter_safe()`, which reports the presence of `mcporter` and displays the configuration command without executing it:

```python
elif safe_mode:
    _install_mcporter_safe()

```

This ensures the Exa backend setup remains transparent and manual.

### Blocking Automatic Channel Installation

Safe mode prevents automatic installation of optional channels (Twitter, Reddit, etc.). The code at lines 55-57 explicitly guards channel installation with a conditional that halts execution when safe mode is active:

```python
if requested_channels and not dry_run and not safe_mode:
    # npm, pipx, or other external tool invocations skipped

```

This check ensures no external package managers run automatically, preventing side effects in production or restricted environments.

### Safe Mode Reporting

Throughout execution, safe mode prints clear headings like `SAFE MODE — skipping automatic system changes` and lists each missing component with specific commands that users can run manually. This output format enables easy copy-paste into privileged shells when administrators are ready to proceed with actual installation.

## Running Agent Reach in Safe Mode

To perform an Agent Reach safe mode installation, execute:

```bash
agent-reach install --safe

```

For a comprehensive audit that shows both what would be done and what is currently missing, combine safe mode with dry-run:

```bash
agent-reach install --dry-run --safe

```

The output identifies missing dependencies and provides exact manual installation commands, such as:

```

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

```

## When to Use Safe Mode Installation

**Auditing**: Administrators can verify that the installer only requires specific binaries (`gh`, `node`, `mcporter`) before granting elevated privileges or network access.

**Restricted Environments**: On CI runners, minimal containers, or corporate machines without sudo access, safe mode reveals exact prerequisites without causing permission errors or failed installation attempts.

**Pre-installation Validation**: Combined with `--dry-run`, safe mode provides a complete picture of both planned configuration changes and current system readiness, ensuring a smooth deployment process.

## Summary

- **Agent Reach safe mode installation** uses the `--safe` flag in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) to disable automatic system modifications while validating prerequisites.
- The installer redirects to `_install_system_deps_safe()` and `_install_mcporter_safe()` instead of their standard counterparts when the flag is present.
- Safe mode checks for GitHub CLI, Node.js, and mcporter presence without invoking package managers or modifying system paths.
- Optional channel installations are explicitly blocked when safe mode is active, preventing unwanted `npm` or `pipx` executions.
- Output includes manual installation commands for missing dependencies, enabling deferred execution in privileged shells after audit completion.

## Frequently Asked Questions

### What does Agent Reach safe mode installation do?

Agent Reach safe mode installation audits your system for required dependencies—such as GitHub CLI, Node.js, and the mcporter backend—without making any automatic changes. According to the implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), it prints manual installation instructions for missing components rather than invoking package managers.

### How do I run Agent Reach in safe mode?

Run `agent-reach install --safe` from your terminal. This flag is defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) lines 71-73 and triggers the safe-mode code path at lines 40-44 that validates dependencies without system modification.

### What dependencies does safe mode check?

According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), safe mode validates the presence of GitHub CLI (`gh`), Node.js, and the `mcporter` binary required for Exa-search functionality. It also prevents automatic installation of optional channel backends like Twitter and Reddit by checking the `safe_mode` boolean at lines 55-57.

### Can I combine safe mode with dry-run?

Yes. Running `agent-reach install --dry-run --safe` provides a comprehensive audit showing both what configuration actions would be performed (dry-run) and which system dependencies are currently missing (safe-mode). This combination is ideal for pre-installation validation in restricted environments where automatic changes are prohibited.