How to Run Agent Reach in Safe Mode to Preview Changes

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 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, 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 lines 71‑73 defines the boolean --safe argument in the install sub‑parser
• Install command logic: 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 contains _install_system_deps_safe() and _install_mcporter_safe() functions that perform read‑only checks
• Documentation: 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:

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 at lines 71‑73, the install sub‑parser adds a boolean argument for the safe mode flag:

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:

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:

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

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

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

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:

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 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 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, 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, 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 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.

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