# How XHS Cookie Configuration Works When the Docker Container Is Unavailable

> Learn how Agent Reach handles XHS cookie configuration when Docker is unavailable. Discover secure local storage and manual file transfer methods for seamless restoration.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-07-16

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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)](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:

```json
[{"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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main//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)](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`](https://github.com/Panniantong/Agent-Reach/blob/main/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):

```text
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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.