Vibe-Trading Setup: Self-Host an AI Trading Agent Free

Vibe-Trading is a free, open-source AI agent that turns a plain-English request like "backtest a BTC-USDT 20/50 moving-average strategy for 2024" into a real quantitative research run, entirely on your own machine. Today it is one of the hottest repositories on GitHub trending, adding roughly 770 stars in a single day on top of nearly 21,000 total, and this tutorial takes you from an empty terminal to a working agent in about ten minutes. It is the rare fintech tool that ships as a normal Python package, keeps your API keys and data local, and refuses to touch a live brokerage account until you explicitly opt in.

• One command installs it: pip install vibe-trading-ai, then vibe-trading init to set up your model. Python 3.11+ and any LLM key (or a local Ollama) is all you need.
• It bundles a backtest engine, 461 pre-built alpha factors, 54 MCP tools, and a multi-agent swarm, and reads market data from 18 free sources with no paid API key.
• Trading is paper and read-only by default; live order placement is experimental, opt-in, and gated behind a committed mandate, a kill switch, and an audit ledger.
• It is MIT licensed and runs as a CLI, a FastAPI web UI, or an MCP server you can plug straight into Claude Desktop or Cursor.

What is Vibe-Trading and why is it trending?

Vibe-Trading is a "personal trading agent" from HKUDS, the Hong Kong University lab behind popular open-source projects like LightRAG. Instead of a dashboard you click through, it is an agent you talk to: you describe a strategy or a research question in ordinary language, and the agent plans the work, pulls market data, writes and runs a backtest, and reports results with charts and metrics. Under the hood it is a Python 3.11+ package with a FastAPI backend and a React 19 web UI, and it exposes 54 tools over the Model Context Protocol so the same capabilities work from the CLI, the browser, or any MCP client. The trending spike is easy to read: retail quant tooling has always been fragmented across data vendors, backtest libraries, and broker SDKs, and Vibe-Trading collapses that stack into one install where the language model does the wiring. It sits near 21,000 stars under an MIT license, and the maintainers ship near-daily.

RelatedSuperpowers Setup: Give Your AI Coding Agent a Real Workflow

How do you install Vibe-Trading?

The fastest path is the PyPI package. You need Python 3.11 or newer and an API key from any supported LLM provider (OpenRouter, OpenAI, DeepSeek, Gemini, Groq, and others), or a local Ollama install if you want zero cloud keys. Install the package, run the interactive setup, and fire a first research task:

# any OS with Python 3.11+
pip install vibe-trading-ai
vibe-trading init
vibe-trading run -p "Backtest a BTC-USDT 20/50 moving-average strategy for 2024 and summarize return and drawdown"

That gives you three commands: vibe-trading launches the interactive terminal UI, vibe-trading serve --port 8899 starts the FastAPI web app, and vibe-trading-mcp runs the MCP server. Market data for Hong Kong, US, and crypto works with no data key at all, because the loader falls back across free sources like yfinance, OKX, and mootdx automatically.

How do you run it in Docker instead?

If you would rather not touch your local Python environment, the repository ships a Docker path that bundles backend and frontend in one container. Clone, copy the env template, add your LLM key, and bring it up:

# Docker: zero local Python setup
git clone https://github.com/HKUDS/Vibe-Trading.git
cd Vibe-Trading
cp agent/.env.example agent/.env
# edit agent/.env: uncomment your provider, set the API key
docker compose up --build

Then open http://localhost:8899 for the web UI. The compose file binds to 127.0.0.1 by default and runs as a non-root user, and your memory, sessions, and backtest history persist in named Docker volumes across rebuilds. If you expose the API beyond your own machine, the docs are explicit that you must set a strong API_AUTH_KEY and send it as a bearer token.

How do you plug it into Claude Desktop or Cursor?

Because Vibe-Trading exposes its tools over MCP, you can attach it to an existing agent rather than running its own UI. It runs as a stdio subprocess, so there is no server to host. For Claude Desktop, add this to claude_desktop_config.json:

{
  // vibe-trading-mcp is installed by the pip package
  "mcpServers": {
    "vibe-trading": {
      "command": "vibe-trading-mcp"
    }
  }
}

Core research tools work with zero API keys for Hong Kong, US, and crypto data; the swarm tool needs an LLM key, and the broker tools only act through whichever connector profile you deliberately select. For Cursor, Windsurf, or other clients, point them at vibe-trading-mcp for stdio or vibe-trading-mcp --transport sse for a web client.

RelatedDesktop Commander Setup: Give Claude Terminal Control

How does it compare with existing quant tools?

The code-first libraries still win when you want total control over a custom engine, and QuantConnect wins on institutional data depth. Vibe-Trading wins on speed to a first result: describing a strategy in a sentence and getting a backtested answer with an attribution breakdown is a genuinely different workflow from writing a strategy class by hand.

What are the gotchas before you rely on it?

Four things worth knowing before you point it at anything real. First and most important: this is research and paper-trading software, not investment advice, and live order placement is flagged experimental across the whole project. Most broker connectors are paper or read-only, and the ones that can place orders sit behind a committed mandate (symbol universe, order size, exposure caps), a filesystem kill switch, and an audit ledger. Do not skip that safety model. Second, model choice matters more than usual: the maintainers warn that small or distilled models produce unreliable tool calls, so the agent appears to answer from memory instead of actually running a backtest. Use a capable model for anything you trust. Third, a real security note from the README: scammers launched a fake token and impersonation accounts, and the team has never issued any token or memecoin, so never connect a wallet or sign anything on the strength of a Vibe-Trading name. Fourth, a backtest is not a forecast: the project added look-ahead-bias fixes and a random-control gate precisely because it is easy to fool yourself with an overfit factor.

Our take

Vibe-Trading is the clearest example yet of an agent collapsing a fragmented tool stack into a conversation, and it does the unglamorous packaging work well: 18 free data loaders, a backtest engine, hundreds of pre-built factors, and a broker layer all reachable from one prompt or one MCP endpoint. The engineering discipline around safety is what earns the trust, not the star count. Read-only defaults, a mandate gate, and an audit ledger are exactly the guardrails a tool that can touch money should ship with, and the fact that the loud news items are security hardening rather than feature hype is a good sign. Treat it as a fast, private research and backtesting environment first. The moment you consider wiring it to a live account, slow down, read the connector docs twice, and remember that a convincing backtest is the easiest lie in finance.

Original analysis by GenZTech. Tool documentation: HKUDS/Vibe-Trading on GitHub.