xianyu-super-butler: a multi account automation console for Xianyu sellers

What one backend has to do to hold thirty accounts

The premise is stated in one line at the top of the README: one person, dozens of Xianyu accounts, running as an unattended business. Everything under that is the consequence. Multi account management with QR code sign in and per account strategy. Automatic delivery of card codes with multiple specs and quantities. Automatic buyer interaction after delivery is confirmed: rating the buyer, asking for the little red flower, sending a thank you message. Keyword replies plus AI negotiation with a floor price and a round limit.

The module table is the best single view of the scope, and it is longer than a feature list usually is. Overview, accounts, items, item automation, orders, card codes, auto reply, AI reply, auto delivery, message management, notifications and logs, settings, and an announcements panel that pulls version information from a self hosted address. Reading it as a feature list undersells it: item automation includes scheduled deletion, short link repair and compensation tasks, and message management includes a decision log recording why each reply fired or did not.

That last one is the detail that tells you the author has run this in anger. A system that replies to buyers on its own needs to be auditable, and a log explaining why it stayed silent is the feature that makes an autonomous reply engine tolerable to trust.

Two Playwright forks, one Chromium, and a pinned version

The dependencies explain the shape of the whole project better than any description would. Under browser automation there are three libraries: `playwright==1.60.0`, `patchright>=1.52.0`, and `DrissionPage>=4.0.0`. The comments next to them are unusually candid.

Playwright is pinned to an exact version because its Chromium revision is bound tightly to it. Install a newer Playwright against an older browser and `launch` fails outright, and the comment says what that breaks: slider verification, QR code login and account profile fetching all fail silently. The upgrade therefore has to be paired with `python -m playwright install chromium`.

Patchright is there for the slider specifically. The note is precise about the reason: under the same Chromium, Playwright exposes `navigator.webdriver` as true, which is the most easily checked automation flag, while Patchright reports false. The API is compatible and it reuses the same browser binary, with the path passed explicitly, so nothing extra is downloaded. Two Playwright forks in one dependency list is unusual, and it is here because the project is fighting a detection heuristic rather than automating a page nobody is checking.

The rest of `requirements.txt` is a conventional FastAPI service: uvicorn, pydantic, loguru, websockets, aiohttp, PyExecJS for running the marketplace's own JavaScript, blackboxprotobuf for parsing traffic, PyJWT with passlib and bcrypt for auth, openai for the reply engine, and pandas with openpyxl for spreadsheet handling of card codes.

Shipping card codes means watching inventory and quantity, not just firing a message

Auto delivery has three levels of rule in this design: global, per account, and per item, with a risk check before anything is sent. Card codes are managed as grouped vouchers with import, status tracking, and multi spec, multi quantity handling. That structure is a response to a specific failure, and the v3.0.0-beta notes name it: per order quantity delivery used to default to off and had to be enabled per item, so a buyer ordering three of something received one code.

The fix turned the default on and backfilled existing items on upgrade, while keeping the per item switch. That is the shape of a real bug report turned into a real fix, and it is worth reading as a description of what the feature actually does in practice.

A related fix from the same release is more revealing about the AI side. Replies failed intermittently even with a working endpoint, because the code read `content` directly from a response and errored when it was empty. Truncated replies, content filter hits, and reasoning models that put the body in `reasoning_content` instead, which the notes name as deepseek-r1 and qwq, all hit that path. Empty content is now handled and transient failures are retried, and the reply length ceiling moved from a hardcoded 100 to configurable, on the grounds that 100 tokens in Chinese is only 50 to 70 characters.

Why the prebuilt image matters more than the Dockerfile

The repository ships two Dockerfiles, three compose files and a China mirror variant, and the README spends more space telling you not to build locally than describing what is in the Dockerfile. The v3.0.0-beta notes explain why: NAS users were reporting pegged CPUs, failed installs and machines that hung. The root cause was local building, where `npm ci`, the frontend bundle, Python dependency compilation and the Chromium download all compete at once, and a machine short on memory gets OOM killed and restart loops.

So the recommended path pulls a prebuilt image instead. Both amd64 and arm64 are published.

docker compose -f docker-compose.nas.yml up -d

The nas compose file exists for a specific reason stated in the README: graphical Docker interfaces on fnOS, Synology and similar devices often have nowhere to put a `.env` file, so that configuration writes its variables directly into the compose file, with the admin credentials at a `CHANGE_ME` placeholder. The ordinary `.env` path still exists, and `.env.example` is short enough to read in one go: web port, timezone, log level, the auto reply and auto delivery flags, AI reply off by default, plus optional memory and CPU limits.

The local build path is a multi stage Dockerfile worth reading if you plan to modify the code. A Node 20 alpine stage runs `npm ci` and builds the Vite frontend into `dist`, a Python 3.11 slim stage creates a virtualenv at `/opt/venv` and installs `requirements.txt`, and the runtime stage copies both in, installs Chromium with `playwright install-deps chromium` and `playwright install chromium`, and also pulls in xvfb, x11 utilities, nodejs and npm.

Release notes that admit the automation can fail

The most valuable text in the repository is the v3.1.0 release body from 2026-08-16, and the reason is that it does not oversell. It says the slider problem was fixed after repeated testing, then immediately qualifies the claim: a headed browser is required, it should not take over your mouse, and a server deployment is recommended. Using a VPN or headless mode affects the success rate. A newly logged in account needs about two minutes after the QR scan.

The README repeats the same caution in a single line: passing the slider automatically is subject to platform risk control and is not guaranteed, and when it fails the account page offers a switch to manual verification. For a tool whose entire value is unattended operation, saying that plainly is worth more than a feature list.

The same release covers a migration detail that tells you about the upgrade path. Database migration is automatic on upgrade, with no manual step. Buyer interaction became three per account switches, rating, asking for the red flower and the thank you, inheriting the previous global setting on upgrade and defaulting to off for new accounts. Order confirmation triggers immediately on a transaction success message instead of waiting for a fallback poll, with the fallback interval configurable in the interface. Items the marketplace no longer returns are marked as delisted and hidden by default without deleting data, so delivery configuration survives.

The last push was on 2026-09-20 and the repository is not archived, with 22 open issues. The release cadence is roughly every six months between v2.3 in February 2026 and v3.0.0-beta in August, then v3.1.0 two days later.

Editorial conclusion

The thing this project actually does well is bookkeeping at volume. Order history import, per account configuration, card code inventory, and a reply decision log are the parts a seller running thirty accounts cannot do by hand, and they are built. Where it is honest is about its limits: the v3.1.0 notes say outright that the slider verification needs a headed browser, that a VPN or headless mode lowers the success rate, and that a server deployment is the sensible target. The dependency file explains why too, pinning playwright to 1.60.0 so its Chromium revision matches. Start with the prebuilt image on amd64 or arm64 from ghcr.io, change the admin password before anything else, and read docs/deployment.md, which is where the verification troubleshooting the README defers actually lives.

Frequently asked questions

Official sources

1. 23Star/xianyu-super-butler on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases