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

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 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. The XHS channel (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

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:

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 module automatically resolves this path through the default cookie directory lookup.

Running Commands

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:

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

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:

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)

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

Option 2: Environment variable override

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

Verified in agent_reach/config.py, this variable redirects all cookie lookups to your specified path.

Automated Workflow

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

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 — XHS‑specific implementation of read(), search(), and cookie validation
• agent_reach/channels/base.py — Abstract BaseChannel contract all platforms implement
• agent_reach/config.py — Cookie directory resolution and environment variable handling
• agent_reach/cli.py — Command‑line parsing and subcommand dispatch
• agent_reach/doctor.py — Environment validation including cookie permissions
• agent_reach/core.py — Central routing and channel loading
• tests/test_xhs_format.py — Cookie format validation suite

---

Summary

• XiaoHongShu setup with Agent Reach is environment‑agnostic—the 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.

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:

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 suite can validate JSON structure before deployment, though actual authentication status is verified only at runtime via the check() method.

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