"Vibe-Trading: Your Personal Trading Agent"
Installation and providers
Installation details
For an installed PyPI copy, vibe-trading update upgrades the package. Editable and version-control installations receive instructions for updating their checkout. To start just the HTTP API, run vibe-trading serve --port 8899.
If an upgrade from a pre-0.1.10 install fails on a LangChain or LangGraph import, recreate the virtual environment or run pip install --force-reinstall vibe-trading-ai.
Prerequisites
- An LLM API key from any supported provider — or run locally with Ollama (no key needed)
- Python 3.11+ for Path B
- Docker for Path A
- OpenAI Codex can also be used with ChatGPT OAuth: set
LANGCHAIN_PROVIDER=openai-codex, then runvibe-trading provider login openai-codex. This does not useOPENAI_API_KEY. In Web Settings, the Codex model picker discovers available models and reasoning levels from the authenticated ChatGPT session. If discovery is unavailable, the default model and manual model entry remain available. - GitHub Copilot can be used with an active Copilot subscription instead of a separately billed LLM API key. See GitHub Copilot SDK provider.
- A local Claude Code login can drive the agent without an API key. See Claude Code CLI provider.
Supported LLM providers: OpenRouter, OpenAI, Anthropic (native Messages API), DeepSeek, OpenCode (Go / Zen), Gemini, Groq, DashScope/Qwen, Zhipu, Moonshot/Kimi, MiniMax, SiliconFlow (CN + Global), Xiaomi MIMO, Novita AI, iFlytek Spark, Z.ai, NVIDIA NIM, ModelScope, GitHub Copilot, Claude Code CLI, Ollama (local). When no
*_BASE_URLis set, each provider falls back to its canonical endpoint, so just a key is enough. See.env.examplefor config.
MiniMax onboarding defaults to MiniMax-M3.1-Flash, with MiniMax-M3 as the alternative in Settings. Both the global and China API endpoints are supported. Saved model IDs and custom endpoints remain editable; official MiniMax endpoints suggest the current pair, while gateways retain every discovered route, including paid variants. MiniMax uses the API's default thinking depth, and Flash's reasoning is preserved across tool turns.
Market data: Public sources cover many common requests, including A-shares via Tencent, US and HK equities via Yahoo, and crypto via OKX. For futures, AKShare supplies supported Chinese contracts. Supply local bars for global contracts. Check the data-source table for credentials and coverage.
Custom model endpoints
Settings → Custom OpenAI-compatible providers tests a chat-completions endpoint,
saves its API key in the OS credential vault (pip install "vibe-trading-ai[keyring]"),
and activates it for new runs. Testing sends a short model request and may incur
the provider's normal API charge. Active profiles are immutable; save a changed
endpoint under a new ID and activate it after testing. Switch back through the
normal model provider selector. Keys are never stored in the profile JSON.
The same flow is available from vibe-trading provider custom list,
vibe-trading provider custom add --id example --label Example --base-url https://api.example.com/v1 --model example-model
(the key is prompted privately), and vibe-trading provider custom activate example.
The configured provider is used by CLI, API, Web, and agent runs alike.
GitHub Copilot SDK provider
The official GitHub Copilot SDK ships as an optional extra, so install it alongside Vibe-Trading with pip install "vibe-trading-ai[copilot]"; installing the Copilot CLI is optional. Authenticate with any one of these supported methods:
gh auth login # use GitHub CLI credentials
# or run `copilot` and sign in # stores credentials in the OS keychain
# or export COPILOT_GITHUB_TOKEN=gho_xxx
Then configure agent/.env:
LANGCHAIN_PROVIDER=copilot
LANGCHAIN_MODEL_NAME=claude-sonnet-5
# COPILOT_GITHUB_TOKEN=gho_xxx # optional; recommended for Docker/CI
Start Vibe-Trading normally. Its preflight reports whether the SDK can authenticate:
vibe-trading
Authentication priority is COPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN, stored Copilot CLI credentials, then gh credentials. Vibe-Trading does not copy or persist SDK credentials. Host keychain credentials are not automatically available inside Docker, so containers should receive COPILOT_GITHUB_TOKEN.
Claude Code CLI provider
The claude-cli provider uses the Claude Code CLI you already have installed and logged in. Each agent step runs one headless claude -p process that only chooses the next step — call these tools, or give the final answer. Vibe-Trading runs the tools itself, so the evidence ledger, grounding checks and swarm deliverable checks behave exactly as with an API provider. It does not read ANTHROPIC_API_KEY. Native CLI tools stay disabled. If the model tries one, Vibe-Trading feeds the refusal back and asks for a host tool call instead of accepting a claim that the tools are unavailable.
Log in once with Claude Code, then check that Vibe-Trading can see the login:
claude auth login
vibe-trading provider login claude-cli # reports the login; it does not start a new one
Then configure agent/.env:
LANGCHAIN_PROVIDER=claude-cli
LANGCHAIN_MODEL_NAME=claude-opus-5-5
# LANGCHAIN_REASONING_EFFORT=high # low|medium|high|xhigh|max; passed as --effort
# CLAUDE_CLI_PATH=/opt/homebrew/bin/claude # when `claude` is not on PATH or in ~/.local/bin
# VIBE_TRADING_DENY_TOOL_PREFIXES=trading_,etoro_ # any provider; empty offers every tool
# VIBE_TRADING_BASH_POLICY=python-only # any provider, or `off`
# CLAUDE_CLI_DENY_TOOL_PREFIXES=trading_,etoro_ # legacy alias when the generic name is unset
# CLAUDE_CLI_BASH_POLICY=python-only # legacy alias when the generic name is unset
VIBE_TRADING_DENY_TOOL_PREFIXEShides tools whose names start with these prefixes from every provider. An explicitly configuredCLAUDE_CLI_DENY_TOOL_PREFIXESremains the fallback alias across providers. With neither configured, other providers retain their existing tool surface; Claude CLI retains its previoustrading_,etoro_default (including broker reads).VIBE_TRADING_BASH_POLICY=python-onlyapplies the same rule to every provider:bashmay run onlypython <relative script>.py,python -c ..., and read-onlyls/cat/head/tail/wc/pwdon non-hidden relative paths (so not.env); refused calls are returned to the model so it can choose again.CLAUDE_CLI_BASH_POLICYremains the fallback alias.vibe-trading provider doctorreports the active policy and which variable supplied it.
Warning: Both settings are convenience filters, not a security boundary.
python -ccan still run arbitrary code, and external MCP tools (mcp_<server>_<tool>) are not covered by the default prefixes. Live orders stay bound by the mandate gate and kill switch whatever these settings allow.
Note: When Settings shows this provider, it loads the models your Claude Code login can run (cached for 5 minutes; Load models refreshes), and the reasoning effort menu offers only the levels the selected model accepts. The chosen level is passed to each
claude -pcall as--effort; it does not read or change~/.claude/settings.json, and "Provider default" means the model's own default. Base URL, temperature andMAX_RETRIEShave no effect with this provider, andTIMEOUT_SECONDSis raised to at least 600 seconds per decision. Image input is not supported. The CLI returns each decision in one piece; while it runs, provider waiting events keep the Web UI active. Transport keepalives alone do not suppressVIBE_TRADING_SSE_TIMEOUT(default 90 seconds), and cancellation and the per-decision deadline remain enforced.
Path A: Docker (zero setup)
git clone https://github.com/HKUDS/Vibe-Trading.git
cd Vibe-Trading
cp agent/.env.example agent/.env
# Edit agent/.env — uncomment your LLM provider and set API key
docker compose up --build
Open http://localhost:8899. Backend + frontend in one container.
[!NOTE] OpenAI Codex OAuth with Docker: the browser login needs a terminal so you can paste the callback URL. Run it through Compose, which allocates an interactive terminal automatically:
docker compose exec vibe-trading vibe-trading provider login openai-codexIf you use
docker execdirectly, pass-itbefore the container name.
Docker publishes the backend on 127.0.0.1:8899 by default and runs the app as a non-root container user. If you intentionally expose the API beyond your own machine, set a strong API_AUTH_KEY and send Authorization: Bearer <key> from clients.
[!NOTE] Using Ollama with Docker: the container reaches a host-side Ollama via
host.docker.internal, notlocalhost(inside the containerlocalhostis the container itself).docker-compose.ymldefaultsOLLAMA_BASE_URLtohttp://host.docker.internal:11434; exportOLLAMA_BASE_URL(or set it in a top-level.env) to point elsewhere. This relies on thehost-gatewaymapping inextra_hosts, which requires Docker Engine ≥ 20.10 / Compose v2 (provided automatically on Docker Desktop).
Your data survives updates: persistent memory, the cross-session search index, user-created skills, shadow accounts, broker connector config, web sessions, backtest runs, swarm history, and uploads all live in named Docker volumes, so git pull && docker compose up --build keeps them. In-progress Web replies are checkpointed too, so a restart restores the partial response and marks the attempt interrupted instead of silently dropping it. Data is deleted only by docker compose down -v.
Path B: Local install
git clone https://github.com/HKUDS/Vibe-Trading.git
cd Vibe-Trading
python -m venv .venv
# Activate
source .venv/bin/activate # Linux / macOS
# .venv\Scripts\activate.bat # Windows CMD
# .venv\Scripts\Activate.ps1 # Windows PowerShell
pip install -e .
cp agent/.env.example agent/.env # Edit — set your LLM provider API key
vibe-trading # Launch interactive TUI
[!NOTE] On Windows:
cpis a PowerShell alias forCopy-Item, so the snippets above work as-is in PowerShell. CMD has nocp— usecopy agent\.env.example agent\.envinstead (this applies to the Docker snippet above too). If PowerShell refuses to runActivate.ps1, runSet-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSignedfirst; it applies to that shell session only.
Start web UI (optional)
# Terminal 1: API server
vibe-trading serve --port 8899
# Terminal 2: Frontend dev server
cd frontend && npm install && npm run dev # requires Node >= 22.22
Open http://localhost:5899. The frontend proxies API calls to localhost:8899.
Production mode (single server):
cd frontend && npm run build && cd ..
vibe-trading serve --port 8899 # FastAPI serves dist/ as static files
[!NOTE]
vibe-trading servebinds0.0.0.0and is loopback-only by default: opening the UI on the same machine (http://localhost:8899) works with zero config. If you browse from another machine, a VM host, or a phone on your LAN, sensitive endpoints return403and the chat shows "Remote API access requires an API key" — set a strongAPI_AUTH_KEYinagent/.env, restart, and enter the same key once in Settings. (Docker Desktop's host gateway: setVIBE_TRADING_TRUST_DOCKER_LOOPBACK=1with the default127.0.0.1port bind.)
Path C: MCP plugin
See MCP Plugin section below.
Path D: ClawHub (one command)
npx clawhub@latest install vibe-trading --force
The skill + MCP config is downloaded into your agent's skills directory. See ClawHub install for details.
🧠 Environment Variables
Copy agent/.env.example to agent/.env and uncomment the provider block you want. Each provider needs 3-4 variables:
| Variable | Required | Description |
|---|---|---|
LANGCHAIN_PROVIDER |
Yes | Provider name (openrouter, deepseek, groq, ollama, etc.) |
<PROVIDER>_API_KEY |
Yes* | API key (OPENROUTER_API_KEY, DEEPSEEK_API_KEY, etc.) |
<PROVIDER>_BASE_URL |
Yes* | API endpoint URL |
LANGCHAIN_MODEL_NAME |
Yes | Model name (e.g. deepseek-v4-pro) |
LANGCHAIN_REASONING_EFFORT |
No | Reasoning effort (none, low, medium, high, or max; claude-cli takes low through max plus xhigh, and no none) |
LANGCHAIN_USE_RESPONSES_API |
No | Responses transport override: literal true uses /v1/responses when the endpoint supports it; native adapters retain their own transport; all other values use Chat Completions |
TUSHARE_TOKEN |
No | Tushare Pro token for A-share data (falls back to AKShare) |
TIMEOUT_SECONDS |
No | LLM call timeout, default 120s |
CLAUDE_CLI_PATH |
No | claude executable for the claude-cli provider when it is not on PATH or in ~/.local/bin |
VIBE_TRADING_DENY_TOOL_PREFIXES |
No | Explicit tool-name filter across every provider; empty offers every tool; unconfigured retains prior provider defaults |
VIBE_TRADING_BASH_POLICY |
No | Explicit python-only or off across providers; unconfigured retains prior defaults (python-only for Claude CLI, off otherwise) |
CLAUDE_CLI_DENY_TOOL_PREFIXES |
No | Legacy alias for VIBE_TRADING_DENY_TOOL_PREFIXES, used when the generic name is unset |
CLAUDE_CLI_BASH_POLICY |
No | Legacy alias for VIBE_TRADING_BASH_POLICY, used when the generic name is unset |
API_AUTH_KEY |
Recommended for network deployments | Bearer token required when the API is reachable from non-local clients |
VIBE_TRADING_ENABLE_SHELL_TOOLS |
No | Explicit opt-in for shell-capable tools in remote API/MCP-SSE style deployments |
VIBE_TRADING_ALLOWED_FILE_ROOTS |
No | Extra comma-separated roots for document and broker-journal imports |
VIBE_TRADING_ALLOWED_RUN_ROOTS |
No | Extra comma-separated roots for generated-code run directories |
VIBE_TRADING_ALLOWED_WRITE_ROOTS |
No | Extra comma-separated roots the agent may write or edit (e.g. ~/Documents for report exports) |
VIBE_TW_STOCK_DB |
No | Path to a Taiwan-market SQLite snapshot; the read-only taiwan_stock_data tool registers only when it is schema-valid |
VIBE_TRADING_EXTRA_CORS_ORIGINS |
No | Comma-separated origins added to the loopback CORS defaults (CORS_ORIGINS replaces them instead) |
CONTENT_FILTER_WARNING_THRESHOLD |
No | Content-filter warning ratio threshold (default 0.05 = 5%). When the ratio of LLM responses blocked by content moderation exceeds this, the run card warns you to switch providers. |
* Ollama does not require an API key. OpenAI Codex uses ChatGPT OAuth and stores tokens via oauth-cli-kit, not in agent/.env. GitHub Copilot authentication is handled by the official SDK. Claude Code CLI uses the local claude login and needs no API key or base URL.
Free data (no key needed): A-shares via AKShare, HK/US/Canada/UK equities via Yahoo/yfinance, crypto via OKX, 100+ crypto exchanges via CCXT. The system automatically selects the best available source for each market.
PDF reports: Ask the agent to save a report as PDF. write_file renders a
.pdf target from Markdown/text with an embedded font; it does not need system
Pango/Cairo or a font download. The Web chat provides an authenticated download
link, and IM channels that support files receive the PDF as an attachment.
External folders must be listed in VIBE_TRADING_ALLOWED_WRITE_ROOTS. Successful
writes return the resolved path and byte count; a rejected path does not forbid
other allowed folders. Generated downloads are staged under
~/.vibe-trading/generated_reports/ (or VIBE_TRADING_HOME/generated_reports/).
🎯 Recommended Models
Vibe-Trading is a tool-heavy agent — skills, backtests, memory, and swarms all flow through tool calls. Model choice directly decides whether the agent uses its tools or fabricates answers from training data.
| Tier | Examples | When to use |
|---|---|---|
| Best | anthropic/claude-opus-4.7, anthropic/claude-sonnet-4.6, openai/gpt-5.5-pro, google/gemini-3.5-flash |
Complex swarms (3+ agents), long research sessions, paper-grade analysis |
| Sweet spot (default) | deepseek-v4-pro, deepseek/deepseek-v4-pro, x-ai/grok-4.20, z-ai/glm-5.1, moonshotai/kimi-k2.6, qwen/qwen3-max-thinking |
Daily driver — reliable tool-calling at ~1/10 the cost |
| Avoid for agent use | *-nano, *-flash-lite, *-coder-next, small / distilled variants |
Tool-calling is unreliable — the agent will appear to "answer from memory" instead of loading skills or running backtests |
The default agent/.env.example uses OpenRouter + deepseek/deepseek-v4-pro; for the DeepSeek official API, select LANGCHAIN_PROVIDER=deepseek and deepseek-v4-pro.