Agent Reach Installation: Safe Mode vs Dry-Run Explained

TLDR: Safe mode performs the Python-side installation while blocking automatic system-level package installations, whereas dry-run only simulates and previews every step without modifying your system.

When installing the Agent Reach toolkit from the Panniantong/Agent-Reach repository, you can control how the installer interacts with your operating system using two distinct command-line flags. Understanding the functional difference between --safe and --dry-run helps you avoid unwanted system modifications in production environments, locked-down workstations, or CI pipelines. This guide analyzes the actual implementation in agent_reach/cli.py and documentation in docs/install.md to explain exactly how each mode behaves.

Understanding Safe Mode (--safe)

Safe mode restricts the installer to Python-level operations only, deliberately preventing any automatic invocation of system package managers. When you pass the --safe flag during Agent Reach installation, the installer skips attempts to install external tools like brew, apt, or yum, focusing solely on setting up the Python library and its dependencies.

According to the installation documentation in docs/install.md, safe mode is designed for security-conscious environments where you cannot or should not modify system files. This includes locked-down workstations, containers with restricted permissions, or CI environments where sudo access is prohibited. The Python packages for Agent Reach install normally, but any missing system-level prerequisites are left for manual installation by the user.

Understanding Dry-Run Mode (--dry-run)

Dry-run mode takes a completely non-destructive approach, executing the installer's logic without applying any changes to your system. When invoked with --dry-run, the Agent Reach installer processes all configuration steps and prints a detailed preview of what actions it would perform, including which system packages it would fetch and which Python components it would configure.

As documented in docs/install.md, dry-run serves as an audit mechanism that allows you to verify the complete list of upstream tools and dependencies before committing to the actual installation. The command finishes after displaying the planned execution steps, leaving your environment entirely untouched. This mode performs no writes to the filesystem, makes no network requests for package installation, and triggers no privilege escalations.

Key Functional Differences

The distinction between these modes lies in their execution scope and system impact:

• System modifications: Safe mode modifies your Python environment but preserves system-level package managers, while dry-run makes absolutely no changes to host OS or Python environments.
• Installation scope: Safe mode installs the Agent Reach library and its Python dependencies, whereas dry-run only simulates the installation process.
• Use cases: Safe mode suits production deployments requiring restricted permissions, while dry-run fits pre-installation auditing and verification workflows.

Practical Usage Examples

The flags are defined in agent_reach/cli.py and accept standard installation parameters. You can invoke them as follows:

To install only Python components while skipping system package auto-installation:

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

To preview the complete installation plan without executing any changes:

agent-reach install --env=auto --dry-run

Both flags support additional scoping parameters such as --channels=twitter,weibo to filter which components the installer processes while respecting your chosen safety mode.

Verification with Agent Reach Doctor

After running installations—particularly in safe mode where system dependencies might be manually managed—you can verify which components were actually configured using the diagnostic utility. The agent_reach/doctor.py module provides post-installation verification to confirm which external tools and channels are properly set up in your environment.

Summary

• Safe mode (--safe) completes the Python installation of Agent Reach but blocks automatic system-level package manager invocations, requiring manual installation of external tools like brew or apt packages.
• Dry-run (--dry-run) executes a complete simulation of the installation process, outputting a preview of all planned actions without modifying the filesystem or installing any packages.
• Safe mode is implemented in agent_reach/cli.py and documented in docs/install.md for security-conscious deployment scenarios.
• Dry-run serves as an audit tool to review upstream dependencies before committing to system changes.
• Use agent_reach/doctor.py after installation to verify which components are actually configured.

Frequently Asked Questions

Can I combine safe mode with other installation flags?

Yes, the --safe flag works alongside other parameters such as --env=auto and --channels=twitter,weibo to scope the installation while preventing system-level package modifications. This allows you to specify exactly which components to install while maintaining the security constraints of safe mode.

What happens if I run dry-run without safe mode on a restricted system?

Dry-run executes without attempting any actual installations or modifications, so it will not trigger permission errors or attempt to use sudo regardless of whether you specify --safe. It purely simulates the process and outputs the planned actions, making it safe to run in any environment regardless of privileges.

Does safe mode install Python dependencies for Agent Reach?

Yes, safe mode installs the Agent Reach library and all required Python packages via pip or similar Python package managers. It only blocks the automatic installation of system-level packages like those managed by apt, yum, or brew, leaving those for manual installation by the user or administrator.

What happens if system packages are missing when I use safe mode?

When running in safe mode, the installer skips attempts to install missing system packages and continues with the Python setup. You must manually install any required external tools afterward; the agent_reach/doctor.py utility can help identify which system dependencies remain unconfigured after the installation completes.

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