Vibe-Trading: an HKUDS agent framework for market research, backtests and paper accounts, with most recent fixes still unreleased

Agents on LangGraph, data from Tushare, AKShare, yfinance and ccxt

The PyPI package is vibe-trading-ai, version 0.1.18, described as a natural-language finance research AI agent with backtesting. It requires Python 3.11 or newer and lists 3.11, 3.12 and 3.13 as supported classifiers. The agent layer is built on langchain, langchain-openai and langgraph pinned below 1.3. Market data comes through tushare and akshare for Chinese markets, yfinance for global equities and ccxt for crypto exchanges, with pandas below 3.0, duckdb, scipy and scikit-learn underneath the analysis. Document output goes through python-docx, python-pptx and openpyxl, which is how the project turns research into trading reports.

The project has never issued a token, and impersonators say otherwise

The top of the project news carries a security warning that deserves to be read before anything else. The X account VibeTrading_HKU, Virtuals project 101845 and the token contract 0x640BDBF77b6447E8b7DB7894cED84BD1c40571f4 are not official Vibe-Trading assets. The maintainers state they have never launched or endorsed any token or memecoin, and tell users not to buy, connect a wallet or sign anything. For a reader, the consequence is simple: any offer to invest in Vibe-Trading through a coin is not from HKUDS, and the official channels are listed in SECURITY.md.

Paper accounts are the execution layer, and they are still being finished

Release v0.1.17 introduced paper accounts. Work merged afterwards added a phase-1 bar-agnostic paper-order lifecycle state machine with stable replay IDs, fail-closed cancellation, day settlement, optional partial fills and deterministic snapshots. There are gaps a user will hit. A-share 5m paper steps now match bar by bar, but saved accounts remain daily-only, so an intraday strategy cannot be persisted at that resolution. Paper strategies run over private worker pipes, and native Windows confirmation of that path is still pending, so Windows users are on less tested ground. Broker integration is also limited: the Robinhood portfolio source is read-only, with account selection, quote mapping and cursor pagination.

Fixes land on main daily while the PyPI release stays at 0.1.18

The last tagged releases are v0.1.16 on 2026-09-29 and v0.1.17 and v0.1.18 both on 2026-10-21. Since then the news log marks almost every entry as unreleased: STAR and Beijing board minimum sizes in backtests, restored Binance open orders and AKShare compatibility, fixed spot-crypto costs, Shadow Account cache invalidation, Futu US symbol mapping, and UTC session timestamps. The last push was on 2026-11-02. The practical cost is that installing the 0.1.18 package gives you none of these corrections, and anyone who needs them has to run from a checkout of main, accepting changes that have not gone through a release.

Docker binds to 127.0.0.1:8899 and loses agent state without the vibe-home volume

The docker-compose.yml publishes the service on 127.0.0.1:8899 only, so the web interface is not exposed to the network by default. Configuration comes from agent/.env, which is also bind mounted so edits made from the Web UI survive container recreation. State lives in named volumes: vibe-runs, vibe-sessions, vibe-swarm-runs, vibe-uploads and vibe-home. The vibe-home volume at /home/vibe/.vibe-trading holds persistent memory, the sessions.db search index, user-created skills, shadow accounts, the hypothesis registry, broker connector config and agent.json. The compose file comments that without it a rebuild wipes all of that (issue #197), so dropping that volume from a custom setup means losing your accounts.

Local models through Ollama on host.docker.internal

For local inference the compose file sets OLLAMA_BASE_URL to http://host.docker.internal:11434 by default, because inside the container localhost is the container itself. If Ollama runs on another machine or port, export OLLAMA_BASE_URL or set it in a top-level .env. The host mapping uses host-gateway, which needs Docker Engine 20.10 or newer with Compose v2; older engines will not resolve the host. Taiwan stock snapshots are mounted read-only from a path outside the checkout, with VIBE_TW_STOCK_DB pointing at /data/tw-stock/latest.db, and the project insists no market data should land in the working tree.

A hash-pinned build that keeps compilers out of the runtime image

The Dockerfile has a node:22-slim stage that builds the frontend with npm ci --ignore-scripts, then a python:3.11-slim builder that installs Python dependencies with pip install --no-cache-dir --require-hashes -r requirements-lock.txt into a venv at /opt/venv. build-essential exists only in that builder stage and never reaches the runtime image. Channel SDKs for Feishu and Telegram come from their own hash-pinned lock instead of package extras. The trade-off is that changing agent/requirements.txt means regenerating the lock file, or the image build will reject the mismatch.

Chat channels and the MCP server reach beyond the web UI

Besides the web interface, the agent talks over Telegram, Feishu, Matrix, Weixin and Discord; voice notes reach the agent as attachments in the first four. The project also exposes an API and MCP server, and IBKR and Futu gateway addresses can be saved per connection through the Web UI or CLI. The optional Parallel search integration is off by default, so web search beyond the built-in data sources has to be switched on deliberately. The README is translated into Chinese, Japanese, Korean, Arabic, Spanish and Indonesian.

Editorial conclusion

Vibe-Trading suits people who want an open, self-hosted agent for market research, backtests and paper accounts across A-shares, US equities and crypto, and who are comfortable running beta software from Python 3.11 or Docker. It does not suit anyone looking for a hands-off live trading bot: broker links such as Robinhood are read-only, paper accounts are the execution layer the project is building out, and the package still declares Beta status. Before relying on it, check whether the fix you need is in the tagged release or only on main, mount the vibe-home volume if you run it in Docker, and ignore any token or wallet offer that uses the project name.

Frequently asked questions

Official sources

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