# How to Run Agent Reach in Safe Mode to Preview Changes

> Run Agent Reach in safe mode using the install SAFE flag to preview changes. This read-only inspection shows missing dependencies without altering your system.

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

---

**Use the `--safe` flag with the `install` command to run Agent Reach in safe mode, which performs a read-only inspection of your environment and prints a checklist of missing dependencies without making any automatic system modifications.**

Agent Reach, hosted in the [Panniantong/Agent-Reach](https://github.com/Panniantong/Agent-Reach) repository, provides a safe mode specifically designed for production servers and shared machines where automatic changes are undesirable. This preview-only execution path allows administrators to validate system requirements and view manual installation instructions before committing to actual system modifications.

## Understanding Safe Mode in Agent Reach

### What the `--safe` Flag Does

When you append `--safe` to the install command, Agent Reach switches to a **dry-run** mode that inspects the current environment without performing writes. According to the implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the safe mode flag triggers alternative helper functions that print "✔️ already installed" or "— not found" status messages alongside manual installation hints for missing components.

### Key Implementation Files

The safe mode functionality spans three critical areas in the source code:

- **CLI argument definition**: [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) lines **71‑73** defines the boolean `--safe` argument in the install sub‑parser
- **Install command logic**: [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) lines **77‑78** propagates the flag into the `safe_mode` variable within `_cmd_install()`
- **Safe helper implementations**: [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) contains `_install_system_deps_safe()` and `_install_mcporter_safe()` functions that perform read‑only checks
- **Documentation**: [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md) lines **84‑90** explains the safe mode behavior to end users

## Running Agent Reach in Safe Mode

To preview changes without modifying your system, execute the install command with the environment set to auto and the safe flag enabled:

```bash
agent-reach install --env=auto --safe

```

### Expected Output

When running in safe mode, Agent Reach prints a formatted report showing exactly what would be installed in a normal run:

```

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: mcporter config add exa https://mcp.exa.ai/mcp

```

## How Safe Mode Works Under the Hood

### CLI Argument Parsing

In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) at lines **71‑73**, the install sub‑parser adds a boolean argument for the safe mode flag:

```python
install_parser.add_argument(
    "--safe",
    action="store_true",
    help="Run in safe mode (preview only, no system changes)"
)

```

### Flag Propagation to Install Command

Inside the `_cmd_install` function at lines **77‑78**, the parsed argument value is stored in a local variable for conditional routing:

```python
def _cmd_install(args):
    safe_mode = args.safe  # Boolean flag propagation

    # ... additional setup

```

### Conditional Routing to Safe Helpers

The main install logic uses the `safe_mode` boolean to select between destructive and read‑only code paths. At lines **236‑242**, the router chooses `_install_system_deps_safe()` instead of the standard `_install_system_deps()` when safe mode is active:

```python

# cli.py L236-L242

if not safe_mode:
    _install_system_deps()
else:
    _install_system_deps_safe()

```

Similarly, for the Exa search helper (`mcporter`), lines **248‑252** invoke the safe variant:

```python

# cli.py L248-L252

if not safe_mode:
    _install_mcporter()
else:
    _install_mcporter_safe()

```

### Skipping Optional Channel Installers

Safe mode explicitly bypasses optional channel installation logic. At lines **55‑56**, the conditional block checks `not safe_mode` before executing channel setup:

```python

# cli.py L55-L56

if requested_channels and not safe_mode:
    # Channel installation logic skipped in safe mode

    install_channels(requested_channels)

```

## Safe Mode Dependency Checks

### System Dependencies

The `_install_system_deps_safe()` function (implemented around lines **49‑69** in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)) performs read‑only checks for the `gh` (GitHub CLI) and `node` (Node.js) binaries. When binaries are absent, it prints the specific URL or package manager command required for manual installation rather than executing automated installers.

### Exa Search Helper Verification

The `_install_mcporter_safe()` function (lines **44‑52**) verifies the presence of the `mcporter` binary. If missing, it outputs the exact `npm install -g mcporter` command and subsequent configuration instructions that a user must run manually.

## Programmatic Safe Mode Usage

You can integrate Agent Reach safe mode into Python automation scripts using the `subprocess` module:

```python
import subprocess

# Run the installer in safe mode and capture its output

result = subprocess.run(
    ["agent-reach", "install", "--env=auto", "--safe"],
    capture_output=True,
    text=True,
)
print(result.stdout)

# Check for specific missing dependencies

if "not found" in result.stdout:
    print("Manual intervention required")

```

For tools that wrap Agent Reach directly, you can invoke the internal command handler programmatically:

```python
from agent_reach.cli import _cmd_install

class DummyArgs:
    safe = True
    dry_run = False
    env = "auto"
    proxy = ""
    channels = ""

# Execute safe mode installation check

_cmd_install(DummyArgs())

```

## Summary

- **Safe mode is read‑only**: The `--safe` flag ensures [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) routes execution to helper functions that never modify system state.
- **Dependency previews**: Functions `_install_system_deps_safe()` and `_install_mcporter_safe()` print manual installation instructions for missing `gh`, `node`, and `mcporter` binaries.
- **Channel bypass**: Optional channel installers are automatically skipped when `safe_mode` is true, preventing any package modifications.
- **Documentation confirmed**: The [`docs/install.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/install.md) file explicitly documents this behavior as a "dry run" for production safety.

## Frequently Asked Questions

### What is the difference between safe mode and normal installation?

**Normal installation** automatically downloads and configures system dependencies like GitHub CLI, Node.js, and the Exa search helper. **Safe mode** (activated with `--safe`) only inspects the current environment and prints a checklist showing which dependencies are missing and the exact manual commands needed to install them, without performing any writes to the system.

### Does safe mode install any packages or dependencies?

No. Safe mode performs zero automatic installations. When examining the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the safe mode helpers explicitly lack any `subprocess` calls or package manager invocations that would modify the system. They only check for binary existence and print instructional text.

### Which dependencies does safe mode check for?

Safe mode validates three critical components: the **GitHub CLI** (`gh`), **Node.js** (`node`), and the **mcporter** binary. According to the implementation at lines **49‑69** and **44‑52** of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the checker prints specific manual install commands for each missing dependency, such as `apt install nodejs npm` or `npm install -g mcporter`.

### Can I use safe mode with other agent-reach commands?

Safe mode is currently implemented specifically for the `install` command. The `--safe` flag is defined in the install sub‑parser at [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) lines **71‑73**, and the conditional routing logic within `_cmd_install` (lines **77‑78**) only affects installation workflows. Other commands like `run` or `config` do not expose this flag in the current codebase.