Guide · Open source

How to use ai-goofish-monitor: Docker setup, tasks and alerts

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

ai-goofish-monitor is a self-hosted, MIT-licensed web app that watches the Xianyu second-hand marketplace for items matching your keywords, price range and filters. It uses Playwright to browse the site and an AI model that accepts images to judge each new listing against your requirements. This guide shows you how to start it with Docker, connect a Xianyu account, create a monitoring task and receive notifications.

ai-goofish-monitorUsagi-org/ai-goofish-monitor · ★ 15.9k · MIT Install options & downloads

Quick start

1Clone the repository. Run the git clone command from the README and enter the ai-goofish-monitor folder.
2Create the environment file. Copy .env.example to .env with cp .env.example .env.
3Fill in the AI settings. Set OPENAI_API_KEY, OPENAI_BASE_URL and OPENAI_MODEL_NAME to an OpenAI-compatible model that accepts image input.
4Start the containers. Run docker compose up -d and open http://127.0.0.1:8000, then log in.
5Add a Xianyu login state. Export your login JSON with the Chrome extension in the README and paste it into the account page. It is saved under state/.
6Create a task. Choose AI or keyword mode, set your criteria, bind an account and optionally add a Cron schedule.
7Configure a notification channel. Add the matching variable, such as NTFY_TOPIC_URL or TELEGRAM_BOT_TOKEN, to .env and restart the containers.

What you need before you install

The project is designed for self-hosting. The README's install path uses Docker, so you need Docker and Docker Compose available on your machine.

You also need an AI model API key. The required settings are OPENAI_API_KEY, OPENAI_BASE_URL and OPENAI_MODEL_NAME. The model must be OpenAI-compatible and support image input, because the analysis looks at listing photos.

Docker (the README's stated prerequisite)
An OpenAI-compatible API key for a model that accepts image input
A Xianyu account you can log into in Chrome or Edge

Install and start ai-goofish-monitor with Docker

Clone the repository, create your environment file and start the containers in the background. Then open the Web UI at the default address.

Edit the .env file to fill in your settings before starting. The README includes the official image address ghcr.io/usagi-org/ai-goofish:latest and the update command docker compose pull && docker compose up -d.

Default Web UI address: http://127.0.0.1:8000
Default login is admin / admin123. Change WEB_USERNAME and WEB_PASSWORD for any real deployment.
If you change SERVER_PORT in .env, update the port mapping in docker-compose.yaml to match.
If the image is slow to download, the README mentions a mirror at ghcr.nju.edu.cn, which you retag as ghcr.io/usagi-org/ai-goofish:latest.

git clone https://github.com/Usagi-org/ai-goofish-monitor && cd ai-goofish-monitor
cp .env.example .env
vim .env # 填写相关配置项
docker compose up -d
docker compose logs -f app
docker compose down

Connect a Xianyu account

Log in to the Web UI and open the Xianyu account management page. The README says to use a Chrome extension to export your Xianyu login state as JSON, then paste it into the page. The login state is saved under the state/ folder, for example state/acc_1.json.

Tasks can be bound to a specific account, or left unbound so the system picks one automatically.

Export the login state with the Chrome extension linked in the README
Paste the JSON into the account management page
Check that the file appears in state/

Create your first monitoring task

Go to task management and create a task. There are two decision modes. AI mode takes a detailed requirement description and generates the analysis criteria in a background job, which shows a progress dialog. Keyword mode uses keyword rules directly and skips the AI generation step.

Tasks can also set price ranges, a listing recency window, free-shipping filters and province, city and district filters. The README notes that the region filter can narrow results a lot, so leave it empty when you are first exploring the market. Scheduled runs use Cron expressions.

AI mode (decision_mode=ai): describe what you want in natural language
Keyword mode: use keyword rules for simple matching
Region filter: default empty, as it significantly shrinks results

Set up notifications

When a listing is judged a match, the app can send an alert. The README lists ntfy.sh, WeChat Work, Bark, Telegram and generic Webhook channels. Each channel is set through environment variables in .env. Telegram needs a bot token and chat ID, and ntfy needs a topic URL.

NTFY_TOPIC_URL for ntfy.sh
WX_BOT_URL for WeChat Work
BARK_URL for Bark
TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID and TELEGRAM_API_BASE_URL for Telegram
WEBHOOK_* variables for a custom webhook
GOTIFY_URL and GOTIFY_TOKEN also appear in the config list

Review results and logs

Matched listings are saved to SQLite, at data/app.sqlite3 by default, along with tasks and price history. The results page and export feature query this database. The logs page shows each task's run, which helps when a login has expired, when requests are being restricted or when an AI call fails.

Results and export read from SQLite
Logs are grouped by task
Persistent folders: data/, state/, prompts/, logs/ and images/

Know the limits before you rely on it

The README warns that frequent requests can cause account restrictions, and asks users to respect Xianyu's user agreement and robots.txt. It also says the project is for learning and technical research, is provided as-is under the MIT licence, and comes with no warranty. The AI analysis calls an external model API, so the tool is not fully offline.

Keep request frequency reasonable to reduce account limits
The AI analysis needs network access to your model provider
The main README is in Chinese; an English README (README_EN.md) is linked from it

What people use it for

Watching Xianyu for a specific used camera or console at or below a set price
Running a scheduled task that checks for new listings in a chosen price range
Using a plain-language requirement so the AI judges listing photos and descriptions, not just keywords
Sending matches to a phone through ntfy.sh, Bark or Telegram

Frequently asked questions

Is ai-goofish-monitor free to use?

The project is released under the MIT licence, which the README describes as provided as-is with no warranty. You still need your own OpenAI-compatible API key for the AI analysis, and the README does not list any prices.

What do I need to install ai-goofish-monitor?

The README's install method is Docker. You clone the repository, copy .env.example to .env, fill in your AI settings and run docker compose up -d. You also need an OpenAI-compatible API key for a model that accepts image input.

Does ai-goofish-monitor work offline?

No. The AI analysis calls an external model API, so you need network access and a valid API key. The Xianyu browsing also requires a connection to the site.

Can I run it without Docker?

The README has a developer section with manual steps: install Python 3.10+, Node.js with npm, Playwright and Chromium, then run start.sh or start the backend with uvicorn. The Docker route is the one the README recommends.

Why does the app say my Xianyu login is not working?

The logs page shows run details for each task, including login-state problems. Export a fresh login state with the Chrome extension, paste it into the account page and check that the file is saved under state/.

Is there an alternative to ai-goofish-monitor?

The README does not compare it with other tools. It credits superboyyy/xianyu_spider as a project it referenced during development, which you can look at if you want a different approach.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose ai-goofish-monitor if you are comfortable running a Docker container, editing a .env file and supplying an OpenAI-compatible API key that accepts images. It suits people tracking specific Xianyu items over time who want AI judgment of listings. Skip it if you do not want to manage a server, need a fully offline tool, or want an English-first experience, since the main README is in Chinese.

Install options & downloads