# How to Set Up XiaoHongShu on a Server vs. Desktop with Agent Reach: A Complete Guide

> Learn how to set up XiaoHongShu on a server versus desktop with Agent Reach. Discover the simple cookie file configuration for CLI access and streamline your agent operations.

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

---

**Agent Reach uses cookie‑based authentication for XiaoHongShu, and the only difference between server and desktop setups is how you expose the cookie file to the CLI.**

Setting up **XiaoHongShu (XHS)** with **Agent Reach** works identically across environments because the platform integration is handled through a pure Python channel adapter. Whether you're running on a local workstation or a headless server, the core logic in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) remains unchanged. This guide walks through the practical differences in cookie management, environment configuration, and deployment workflows.

---

## Understanding the XiaoHongShu Channel Architecture

Agent Reach organizes platform integrations as **channels** that implement a common contract defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py). The XHS channel ([`xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/xiaohongshu.py)) provides four required methods:

- **`can_handle(url)`** — Determines if a URL belongs to XiaoHongShu
- **`read(url)`** — Retrieves content from a specific post
- **`search(query)`** — Executes platform‑specific keyword searches
- **`check()`** — Validates that required cookies are present and valid

The channel contains **no embedded authentication logic**. Instead, it relies on externally provided cookie files, making environment portability straightforward.

---

## Desktop Setup (Interactive Environment)

A desktop installation emphasizes ease of use with direct file system access and immediate visual feedback.

### Installation

```bash
git clone https://github.com/Panniantong/Agent-Reach.git
cd Agent-Reach
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

pip install -e .

```

### Cookie Placement

Export your XHS cookies from a browser using a Cookie‑Editor extension, then save them to:

```bash
mkdir -p ~/.agent_reach/cookies
cp ~/Downloads/xhs_cookies.json ~/.agent_reach/cookies/xhs.json
chmod 600 ~/.agent_reach/cookies/xhs.json

```

The [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) module automatically resolves this path through the default cookie directory lookup.

### Running Commands

```bash
python -m agent_reach.cli xhs read https://www.xiaohongshu.com/explore/5f2a3b4c6d7e8f9a0b1c2d3e

```

Interactive output uses `rich` for formatted display, and the **Doctor** command provides immediate diagnostics:

```bash
python -m agent_reach.cli doctor

```

---

## Server Setup (Headless/Production Environment)

Server deployment requires explicit cookie file exposure but follows identical execution paths.

### Container Installation

```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install -e .
ENV AGENT_REACH_COOKIE_DIR=/opt/cookies
USER 1000:1000
CMD ["python", "-m", "agent_reach.cli"]

```

Build and run with mounted cookies:

```bash
docker build -t agent-reach .
docker run -v /secure/cookies:/opt/cookies:ro agent-reach xhs read <url>

```

### Cookie Deployment Options

**Option 1: Directory mount** (recommended for containers)

```bash
-v $HOME/.agent_reach/cookies:/root/.agent_reach/cookies:ro

```

**Option 2: Environment variable override**

```bash
export AGENT_REACH_COOKIE_DIR=/opt/agent-reach/.cookies

```

Verified in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), this variable redirects all cookie lookups to your specified path.

### Automated Workflow

```bash

# 1. Prepare cookie on trusted workstation

# 2. Secure transfer

scp ~/.agent_reach/cookies/xhs.json server:/opt/agent-reach/.cookies/

# 3. Validate server environment

ssh server 'python -m agent_reach.cli doctor'

# 4. Execute via cron or systemd

python -m agent_reach.cli xhs read <url> --log-file /var/log/agent-reach/xhs.log

```

---

## Server vs. Desktop: Configuration Comparison

| Aspect | Desktop | Server |
|--------|---------|--------|
| **Cookie storage** | `~/.agent_reach/cookies/xhs.json` | Mounted volume or `AGENT_REACH_COOKIE_DIR` |
| **Network** | Direct host stack | Firewall egress rules, optional `http_proxy`/`https_proxy` |
| **Security model** | User‑owned files (mode `600`) | Container user mapping, read‑only mounts |
| **Logging** | Interactive `rich` output | File streams or structured logging |
| **Scheduling** | Manual execution | `cron`, systemd timers, or orchestrators |

The [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) diagnostic runs identically in both environments and warns about world‑readable cookies or missing dependencies.

---

## Programmatic XiaoHongShu Access

For integration into larger applications, bypass the CLI entirely using [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py):

```python
from agent_reach.core import AgentReach

# Initialize router with auto‑loaded channels

ar = AgentReach()

# Verify XHS readiness

xhs = ar.channel('xiaohongshu')
assert xhs.check(), "XHS cookies missing or expired"

# Read specific post content

post_url = "https://www.xiaohongshu.com/explore/5f2a3b4c6d7e8f9a0b1c2d3e"
content = xhs.read(post_url)
print(f"Extracted {len(content)} characters")

# Execute search

for url in xhs.search("travel tips")[:5]:
    print(url)

```

This code executes identically on desktop or server—the `AgentReach` router resolves cookie paths through the same configuration layer used by the CLI.

---

## Key Source Files Reference

Understanding these locations enables debugging and customization:

- **[`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py)** — XHS‑specific implementation of `read()`, `search()`, and cookie validation
- **[`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py)** — Abstract `BaseChannel` contract all platforms implement
- **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)** — Cookie directory resolution and environment variable handling
- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** — Command‑line parsing and subcommand dispatch
- **[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)** — Environment validation including cookie permissions
- **[`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py)** — Central routing and channel loading
- **[`tests/test_xhs_format.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_xhs_format.py)** — Cookie format validation suite

---

## Summary

- **XiaoHongShu setup with Agent Reach is environment‑agnostic**—the [`xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/xiaohongshu.py) channel contains no GUI dependencies
- **Cookie management is the only differentiator**: desktop uses default paths, servers require explicit path exposure via mounts or `AGENT_REACH_COOKIE_DIR`
- **Always run `python -m agent_reach.cli doctor`** after deployment to verify cookie accessibility and permissions
- **Programmatic access** through `AgentReach.core()` works identically across environments
- **Security requires mode `600` permissions** on cookie files, enforced by diagnostic checks

---

## Frequently Asked Questions

### How does Agent Reach authenticate with XiaoHongShu?

Agent Reach uses **cookie‑based authentication** exclusively. You export cookies from an authenticated XHS browser session, save them as JSON, and make them available to the runtime. No username/password or API keys are required, as implemented in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py).

### Can I use the same cookie file on multiple servers?

Yes, provided the cookies remain valid and you secure the transfer. XHS cookies typically expire based on session duration or platform policies. Copy the file securely (SCP, encrypted secrets manager) and verify with `python -m agent_reach.cli doctor` on each target system.

### What if my server blocks outbound HTTPS requests?

Configure proxy environment variables before running Agent Reach:

```bash
export https_proxy=http://proxy.company.com:8080
python -m agent_reach.cli xhs read <url>

```

The underlying Python `requests` library respects these variables automatically.

### How do I rotate or refresh XHS cookies?

Re‑export cookies from a fresh browser session on your trusted workstation, then redeploy the file. The [`tests/test_xhs_format.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_xhs_format.py) suite can validate JSON structure before deployment, though actual authentication status is verified only at runtime via the `check()` method.