How XHS Cookie Configuration Works When the Docker Container Is Unavailable

When Docker is unavailable, Agent-Reach parses XHS cookies from JSON or header strings, saves them to a permission-restricted local file at ~/.agent-reach/xhs-cookies.json, and instructs the user to manually copy the file into the container once it becomes available.

The Agent-Reach CLI handles XiaoHongShu (XHS) authentication through a flexible cookie configuration system that functions regardless of container runtime status. When the xiaohongshu-mcp Docker container is absent, the tool gracefully degrades to local file storage with secure permissions. This article explains the exact code paths in agent_reach/cli.py that handle cookie parsing, Docker detection, and secure local persistence.

Parsing Cookie Input Formats

The agent-reach configure xhs-cookies "<value>" command forwards the raw value to _configure_xhs_cookies in [agent_reach/cli.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L75-L84). This function accepts two distinct input formats and normalizes them into a standard JSON structure.

Cookie-Editor JSON Export

If the input begins with [, the code attempts json.loads and validates that each element contains name and value fields (lines 99-108). This format exports directly from browser extensions like Cookie-Editor:

[{"name":"web_session","value":"abc123","domain":".xiaohongshu.com"}]

Classic Header String

If JSON parsing fails, the function falls back to a header-string parser (lines 119-134). It splits the input on semicolons and converts each name=value pair into a minimal cookie object with default fields such as domain=".xiaohongshu.com". This accepts strings commonly copied from browser developer tools:

agent-reach configure xhs-cookies "web_session=abc123; other_cookie=def456"

Docker Detection and Fallback Logic

After parsing, the function checks whether the docker binary exists on the system PATH (line 156). If Docker is not found, execution proceeds to the "no Docker" branch (line 158), skipping all container management logic.

When Docker is present, the code locates the running xiaohongshu-mcp container, determines the internal cookie path via printenv COOKIES_PATH (falling back to /app/cookies.json), copies the JSON into the container with docker cp, restarts the container, and verifies login using mcporter (lines 292-352).

Secure Local File Storage

In the absence of Docker, Agent-Reach persists cookies locally using defense-in-depth file permissions.

Private Directory Creation

The helper make_private_dir (defined in [agent_reach/utils/paths.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py)) creates ~/.agent-reach with mode 0o700 (owner-only read/write/execute).

Atomic File Writing

Inside that directory, the code creates xhs-cookies.json with mode 0o600 (owner-only read/write). This is performed atomically using os.open with O_CREAT | O_EXCL followed by os.fdopen (lines 267-278). If the atomic approach fails (e.g., on Windows), a fallback uses plain open plus explicit chmod (lines 280-286).

Manual Deployment Instructions

After saving the file, the CLI prints explicit instructions for manual container deployment (lines 288-290):

Cookies saved to /home/you/.agent-reach/xhs-cookies.json
Docker not found. Copy manually:
docker cp /home/you/.agent-reach/xhs-cookies.json xiaohongshu-mcp:/app/data/cookies.json

No secret data is printed to stdout, and the file permissions guarantee that only the owning user can read the cookies. When you later spin up the container, execute the printed command:

docker run -d --name xiaohongshu-mcp -p 18060:18060 xpzouying/xiaohongshu-mcp
docker cp ~/.agent-reach/xhs-cookies.json xiaohongshu-mcp:/app/data/cookies.json
docker restart xiaohongshu-mcp  # Forces the service to reload the file

Summary

Agent-Reach ensures XHS cookie configuration remains functional even without Docker by:

• Dual-format parsing – Accepts both Cookie-Editor JSON and semicolon-delimited header strings via _configure_xhs_cookies in cli.py
• Graceful degradation – Detects Docker absence on PATH and switches to local persistence
• Secure storage – Creates ~/.agent-reach/xhs-cookies.json with 0o600 permissions using atomic file operations
• Manual migration path – Provides exact docker cp commands for later container synchronization

Frequently Asked Questions

What file format should I use for XHS cookies?

Agent-Reach accepts two formats: a JSON array exported from Cookie-Editor (containing objects with name and value keys) or a classic HTTP header string like name1=value1; name2=value2. Both are normalized to the same internal structure before storage.

Where are cookies stored when Docker is not running?

Cookies are saved to ~/.agent-reach/xhs-cookies.json on the local filesystem. The ~/.agent-reach directory is created with 0o700 permissions, and the cookie file itself receives 0o600 permissions, ensuring only the file owner can read the sensitive authentication data.

How do I manually copy cookies to the Docker container?

After starting the xiaohongshu-mcp container, run the command printed by the CLI: docker cp ~/.agent-reach/xhs-cookies.json xiaohongshu-mcp:/app/data/cookies.json. Then restart the container with docker restart xiaohongshu-mcp to force the service to reload the authentication data.

Is the local cookie storage secure?

Yes. The code uses os.open with O_CREAT | O_EXCL flags to create the file atomically, preventing race conditions. If this fails, it falls back to chmod immediately after creation. The resulting 0o600 permissions restrict read access to the file owner only, and the tool never logs cookie values to stdout.

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