# How to Install Agent Reach for Python: Complete Setup Guide

> Learn how to install Agent Reach for Python with this comprehensive guide. Set up core channels and backends like Twitter and Reddit easily.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: getting-started
- Published: 2026-06-25

---

**Agent Reach installs via `pipx` or `pip` directly from GitHub, then runs `agent-reach install --env=auto` to configure core channels and optional platform backends like Twitter, Reddit, and XiaoHongShu.**

Agent Reach is a lightweight Python router that enables AI agents to read and search content from more than a dozen internet platforms. Developed in the **Panniantong/Agent-Reach** repository, this tool acts as glue between your agent and various upstream tools rather than a monolithic wrapper. When you install Agent Reach for Python, you get a command-line interface that automatically detects your environment and wires together necessary dependencies.

## Prerequisites

Before running the installer, ensure your system meets these baseline requirements:

- **Python 3.8+** installed and available in your PATH
- **pipx** (strongly recommended for isolated installs) or **pip** with virtual environment support
- **GitHub CLI** (`gh`) and **Node.js** (optional but required for certain channels; the installer can auto-download these)

## Installation Steps

### 1. Install the Package

The recommended method uses `pipx` to create an isolated environment and automatically add the `agent-reach` command to your PATH:

```bash
pipx install https://github.com/Panniantong/agent-reach/archive/main.zip

```

If you prefer a traditional virtual environment, use this alternative:

```bash
python3 -m venv ~/.agent-reach-venv
source ~/.agent-reach-venv/bin/activate
pip install https://github.com/Panniantong/agent-reach/archive/main.zip

```

### 2. Run the Core Installer

Execute the installation command with auto-detection mode to configure the minimal core plus zero-config channels (Web, YouTube, GitHub, RSS, Exa, and Bilibili):

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

```

According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the `_cmd_install` function performs three deterministic phases:

1. **System-level prerequisites** – Checks for GitHub CLI, Node.js, and proxy support, auto-installing missing components unless running in safe mode.
2. **mcporter & Exa search** – Installs the `mcporter` Node package required for free Exa search and configures the default `exa` endpoint.
3. **Optional channel back-ends** – Pulls upstream tools like `twitter-cli`, `opencli`, `rdt-cli`, or `bili-cli` based on your `--channels` selection.

### 3. Configure Credentials

Many platforms require authentication tokens or browser cookies. The configuration manager in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) persists settings to `~/.agent-reach/config.json`.

Extract cookies automatically from Chrome or Firefox:

```bash
agent-reach configure --from-browser chrome

```

Or set credentials manually for specific services:

```bash
agent-reach configure twitter-cookies "auth_token=AAA; ct0=BBB"
agent-reach configure groq-key gsk_XXXXXXXXXXXXXXXX

```

### 4. Validate the Installation

Run the built-in diagnostics to verify each channel's health:

```bash
agent-reach doctor

```

The doctor routine, implemented in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), iterates over all channel classes and calls their `check()` method, aggregating results into a machine-readable report. Status indicators display as `✅` (ok), `⚠️` (warning), or `❌` (failed).

## Installation Modes and Options

### Auto-Detect vs. Manual Environment

The `--env=auto` flag detects whether you are running on a local desktop or headless server, adjusting the installation profile accordingly. Desktop environments receive additional Chrome extension guidance for platforms requiring browser automation.

### Safe and Dry-Run Modes

Preview changes without modifying your system using these flags:

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

```

**`--dry-run`** reports what would be installed without executing changes. **`--safe`** mode performs read-only system checks and lists missing prerequisites without attempting auto-installation.

### Adding Optional Channels

Extend Agent Reach beyond core platforms by specifying additional channels during installation:

```bash
agent-reach install --env=auto --channels=twitter,xiaohongshu,reddit

```

For a complete installation including all supported platforms:

```bash
agent-reach install --env=auto --channels=all

```

Note that desktop-only channels (like those requiring the OpenCLI Chrome extension) will print setup guides rather than auto-installing binaries.

## Architecture Overview

Understanding the codebase structure helps troubleshoot installation issues:

- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** – Contains the CLI entry point and `_cmd_install` logic that orchestrates the three-phase installation flow.
- **[`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py)** – Implements the core router that dispatches read and search requests to appropriate channels.
- **[`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py)** – Defines the abstract base class enforcing channel contracts (`can_handle()`, `read()`, `search()`, `check()`).
- **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)** – Handles persistent JSON configuration storage in `~/.agent-reach/config.json`.

The installer is pure Python; all external binaries are obtained via system package managers (`apt`, `brew`) or by invoking `npm`/`pipx`, making Agent Reach a router rather than a wrapper that preserves upstream tool performance.

## Summary

- **Install Agent Reach for Python** using `pipx install https://github.com/Panniantong/agent-reach/archive/main.zip` for isolated, PATH-available execution.
- Run **`agent-reach install --env=auto`** to execute the three-phase installation (system prerequisites, mcporter/Exa setup, and optional channels).
- Use **`--dry-run`** or **`--safe`** flags to preview changes without system modification.
- Configure authentication via **`agent-reach configure`** commands, storing data in `~/.agent-reach/config.json`.
- Validate setup using **`agent-reach doctor`**, which leverages [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) to check each channel's `check()` method.
- The architecture relies on [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) for orchestration and [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) for routing, with channel contracts defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py).

## Frequently Asked Questions

### What is the difference between --dry-run and --safe mode?

**`--dry-run`** simulates the entire installation process and reports what actions would be taken without executing any system changes. **`--safe`** mode performs actual read-only system checks to identify missing prerequisites (like GitHub CLI or Node.js) but stops before auto-installing anything, providing a compatibility report instead.

### Where does Agent Reach store configuration files?

Agent Reach stores persistent settings in **`~/.agent-reach/config.json`**, managed by the `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). This JSON file contains user-provided tokens, proxy settings, and extracted browser cookies. The CLI provides commands like `agent-reach configure` to modify these values without manual file editing.

### Can I install Agent Reach without root privileges?

Yes. When using **`pipx`**, Agent Reach installs into a user-level isolated environment without requiring sudo or root access. The `agent-reach` command becomes available in your user PATH. Even when using `pip` with a virtual environment, the installation remains within your user directory, though some optional channel dependencies (like system-wide Node.js) may require elevated permissions if not already present.

### How do I add support for additional platforms after initial installation?

Simply re-run the installer with the new channels specified: **`agent-reach install --env=auto --channels=twitter,xiaohongshu`**. The installer is idempotent and will only fetch and configure the missing upstream tools (like `twitter-cli` or `opencli`) without breaking existing functionality. For desktop platforms requiring Chrome extensions, follow the printed one-click guide after installation.