PanWatch: a self-hosted AI stock watcher with a TradingAgents decision chain

What PanWatch actually does for a retail position holder

The problem PanWatch addresses is not market data. A-share, Hong Kong and US quotes are widely available. The gap it targets is the step after the quote: deciding what a price move, a volume spike or a news item means for the specific positions you hold. The README frames the project as a self-hosted AI monitoring assistant whose selling point is that position data never passes through a third party, because the whole thing runs on your own machine.

The audience is narrow and specific. You need positions in at least one of the three covered markets, a machine that can run Docker or Python 3.10 with Node 18 for local development, and an OpenAI-compatible API key. The README lists OpenAI, Zhipu, DeepSeek and Ollama as supported providers, and the shipped .env.example defaults to Zhipu's endpoint with glm-4. Ollama matters here: it is the only listed option that keeps inference local as well, which is consistent with the privacy argument the project makes for itself.

What you get is a web dashboard with a holdings page, an opportunity page that scores candidates, a paper-trading page with an equity curve, per-stock detail, technical indicator panels and a price alert engine. Four scheduled agents run around the clock: pre-market analysis before the open, intraday monitoring during the session, a post-close daily report, and a news collector. Alerts and agent conclusions go out through Telegram, WeCom, DingTalk, Feishu, Bark or a custom webhook.

The TradingAgents chain: nine agents, three to five minutes, one decision

The distinctive mechanism is the deep analysis path. According to the README, clicking the brain icon on a holdings row hands the position to TradingAgents, an external multi-agent framework that PanWatch pulls in as a git dependency rather than a PyPI package. The chain runs four analyst types (technical, sentiment, news, fundamental), then a bull-versus-bear debate, then a risk review, then a portfolio-manager decision. The documented runtime is three to five minutes for a complete reasoning chain, and the conclusion is pushed to your IM channel.

That runtime is the honest signal about the architecture. This is not a request-response endpoint; it is a graph of model calls executed sequentially, which is why the project ships its own observability layer. The README describes structured logs with a trace_id threaded through, an agent_runs table, and node-level progress and cost tracking for TradingAgents. The optional OpenTelemetry export maps an agent run to a root span, a single LLM call to a gen_ai span following the OpenTelemetry GenAI semantic conventions, and each TradingAgents node to a child span. The export is off by default and the README states it is a no-op without the optional requirements-otel.txt dependency and an endpoint.

Cost is documented rather than hidden: roughly $0.05 per run on deepseek-chat. Multiply by the number of positions you analyze and the frequency, and the monthly figure is yours to estimate. The dependency itself is heavy. requirements.txt pins TradingAgents to the v0.4.0 release tag and notes it pulls langchain, langgraph and yfinance, about 115 packages and two to five minutes on first install. The same comment states the adapter depends on route_to_vendor, load_ohlcv, get_graph_args and create_initial_state keeping stable signatures, and that the one behavioural change in 0.4.0 is a REVIEW result when upstream cannot parse a rating, which result_mapper surfaces as pending manual review. That is a real failure mode worth knowing before you read an agent output as a verdict.

Installing PanWatch with Docker and running a first analysis

The README's quick start is a single container run. The image is sunxiao0721/panwatch:latest on Docker Hub, the service listens on port 8000, and /app/data is the mount point you must persist.

docker run -d \
  --name panwatch \
  -p 8000:8000 \
  -v panwatch_data:/app/data \
  sunxiao0721/panwatch:latest

Open http://localhost:8000 and the first screen asks you to set a username and password. The README notes that the image already carries the system libraries Playwright needs, but Chromium itself is downloaded on first container start into the mounted volume, by default /app/data/playwright. Expect several minutes and a working network path on that first boot. If you do not need screenshot capability, set PLAYWRIGHT_SKIP_BROWSER_INSTALL=1 when starting the container to skip the download entirely.

The Compose variant differs only in restart policy and volume declaration:

version: '3.8'
services:
  panwatch:
    image: sunxiao0721/panwatch:latest
    container_name: panwatch
    ports:
      - "8000:8000"
    volumes:
      - panwatch_data:/app/data
    restart: unless-stopped

volumes:
  panwatch_data:

After login the README's first-configuration list is four steps: set the AI provider under Settings, add a notification channel, then add a stock under Holdings and enable the agent for it. The AI provider screen expects an OpenAI-compatible API, and the repository's .env.example shows the shape of the credentials if you prefer environment variables over the UI:

AI_BASE_URL=https://open.bigmodel.cn/api/paas/v4
AI_API_KEY=your_key_here
AI_MODEL=glm-4

The same file shows the Telegram notification pair, NOTIFY_TELEGRAM_BOT_TOKEN and NOTIFY_TELEGRAM_CHAT_ID, plus an optional HTTP_PROXY for reaching Telegram from networks that need it. With a provider and a channel configured, adding a position and triggering the deep analysis is the first real use: the run appears in the UI with node-level progress, and the conclusion arrives in your IM channel a few minutes later.

Where PanWatch gets in your way

The interface is Chinese. The README, the screenshots and the configuration flow are all written for a Chinese-speaking user, and nothing in the repository describes an English localisation. If your team does not read Chinese, the dashboard is a genuine barrier rather than a cosmetic one, because the agent output itself is prose you have to interpret.

The deployment has two heavyweight first-run costs. Chromium is fetched on first start unless you set PLAYWRIGHT_SKIP_BROWSER_INSTALL=1, and the TradingAgents dependency is a git URL that drags in around 115 packages, which the requirements comment puts at two to five minutes on first install. Neither is fatal, but both make the "five minute setup" claim in the README optimistic on a slow connection. The Dockerfile also installs git purely because requirements.txt contains that git+https line, which tells you the build cannot be fully offline.

There is a subtler limitation in the analysis path. The README's own note about TradingAgents v0.4.0 says that when upstream cannot parse a rating, the adapter returns REVIEW and result_mapper displays it as pending manual review. In other words, a completed run does not guarantee a directional conclusion. You will occasionally pay for a chain that ends in a human-review marker. The project is also explicit that the deep analysis agent is only invoked when you enable it, and that leaving it off costs nothing, which is the right default but also means the headline feature is opt-in per position.

Finally, the scheduling layer is timezone-sensitive. The TZ variable defaults to Asia/Shanghai and the README states it affects when agent schedules fire as well as how times are displayed. Set it wrong and your pre-market analysis runs at the wrong hour.

PanWatch versus wiring the pieces together yourself

The obvious alternative is to assemble the same thing from its parts. TradingAgents is a standalone open source framework, and the README points to it directly. A developer could install TradingAgents, write a scheduler, pull quotes through akshare or efinance, and push results to Telegram with apprise. Every one of those libraries already appears in PanWatch's own requirements.txt, which is a fair indication of how thin the wrapper is in places.

The difference is in what you would have to build. PanWatch supplies the persistence layer (SQLAlchemy models, an agent_runs table), the scheduler (APScheduler with configurable cron, for example DAILY_REPORT_CRON=30 15 * * 1-5), the alert engine with AND/OR condition combinations, cooldowns, daily trigger caps and per-rule channel selection, the authentication layer with JWT, and the React frontend. Rebuilding the alert engine alone is a weekend of work if you want cooldowns and duplicate-trigger modes.

A second alternative is a hosted portfolio tracker. Those give you an English interface and no server to run, and they lose the property PanWatch is built around: your holdings never leave your machine, and if you point AI_BASE_URL at a local Ollama instance, neither does the inference. That trade is the whole decision. If you are comfortable with a third party holding your position data, the self-hosted argument largely evaporates and PanWatch becomes a more effortful way to get a similar dashboard.

A third path, closer to PanWatch's own design, is to keep its monitoring and alerting but skip the deep analysis. The README states the TradingAgents dependency is only called when you enable the deep analysis agent, so you can run the container, configure a provider for the lighter scheduled agents, and never install the heavy graph. That is a legitimate configuration rather than a compromise.

Maintenance, upgrades and what the MIT licence leaves to you

The repository is not archived, and the last push was on 2026-08-27, matching the 0.11.0 release. The two prior releases, 0.10.2 and 0.10.1, landed on 2026-08-12 and 2026-08-02, so the cadence over that month was roughly one release per fortnight. That is recent enough to call the project current, and the release notes do not describe breaking migrations, but the README does not document a rollback procedure or a database migration path between versions. If you run this against real holdings, that silence matters more than the release cadence. Pin an image tag rather than tracking latest, and back up the /app/data volume before upgrading, because that volume holds both the application data and the Playwright browser install.

Upgrade cost has three components. The container image itself is small because Chromium lives in the volume, so pulling a new tag is cheap. The TradingAgents dependency is pinned to v0.4.0 by tag, and the requirements comment explains that the adapter relies on four upstream functions keeping stable signatures, which means a future upstream release can break the integration even if PanWatch itself is unchanged. The optional OTel layer is separate by design and installs from requirements-otel.txt only when you want it.

The licence is MIT. That permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained, and it disclaims warranty. It says nothing about the data sources: akshare and efinance fetch market data, and the terms attached to those sources are your responsibility, not the licence's. The same applies to the model provider you configure. None of this is legal advice; read the MIT text and the terms of the data and model providers you actually use.

Editorial conclusion

Adopt PanWatch if you already hold positions across A-share, Hong Kong or US markets, you are willing to run a container and keep a data volume, and you accept that the analysis is produced by a third-party model at roughly $0.05 per run. Do not adopt it if you need an English interface, if you cannot run Docker or a Python 3.10 environment, or if you expect the agent output to be a validated signal rather than a reasoning chain. Before trusting a deployment, confirm three things: that the data volume survives a container restart, that PLAYWRIGHT_SKIP_BROWSER_INSTALL is set if you do not need K-line screenshots, and that your configured model actually returns a decision instead of the REVIEW outcome the TradingAgents adapter maps to manual review.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes