{"id":"f364090e-4bbd-40dc-bc5c-308815894e85","slug":"loopfund","kind":"mcp","name":"Loopfund","summary":"Local first multi-agent AI sandbox for investing research (dry mode / paper trading). Runs local or cloud LLMs, with a FastAPI and React dashboard.","owner":"jaknak13-source","repoUrl":"https://github.com/jaknak13-source/Loopfund","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-06-27T18:45:17.000Z","addedAt":"2026-10-28T21:18:25.848Z","logoUrl":"https://avatars.githubusercontent.com/u/253824480?u=e0e8805e6e93717fc1e2521eb625f00e8d68c891&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["data-analytics","memory-knowledge"],"tags":["agentic-ai","ai-agents","algorithmic-trading","anthropic","autonomous-agents","fastapi","fintech","investing"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-28T21:18:36.219Z","sample":false,"url":"https://conduits.dev/tools/loopfund","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# loopfund\n\n[![CI](https://github.com/jaknak13-source/loopfund/actions/workflows/ci.yml/badge.svg)](https://github.com/jaknak13-source/loopfund/actions/workflows/ci.yml)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)\n![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)\n\nloopfund is a local first, always on multi agent investment research and\nportfolio-management sandbox. It runs a continuous research loop in which\nspecialist agents study a watchlist using free market data, then a coordinator\nagent makes one allocation decision per interval against a simulated EUR ledger.\n\nIt runs in dry mode: a simulated ledger that uses real market prices, real\ntrading fees, and real FX rates, but places no real orders. Live execution is\nintentionally gated and unimplemented.\n\n![loopfund dashboard showing a dry-mode portfolio with positions, P&L, and allocation](docs/dashboard.png)\n\n## Disclaimer\n\nRead this before anything else.\n\n- loopfund is for research and education only. It is not financial advice, not\n  an investment recommendation, and not a solicitation to buy or sell anything.\n- It runs in dry mode only. It simulates a portfolio. It does not place real\n  trades and cannot move real money.\n- It makes no guarantee of returns. Simulated results are not real results and\n  do not predict real results.\n- Outputs come from language models and free data feeds that can be wrong,\n  stale, or incomplete.\n- You use it at your own risk. Nothing here is produced by, or constitutes, a\n  licensed financial professional.\n\n## Features\n\n- A continuous research loop that runs specialist agents on a configurable\n  schedule, with one model call at a time to stay light on memory.\n- Core agents for research, macro, fundamentals, sentiment, IPO/M&A, alternative\n  data, quant, and risk, plus a decision coordinator.\n- Agent findings are combined by evidence-weighted aggregation, not majority vote.\n- A risk agent that can veto or haircut a proposed action.\n- `NO_ACTION` is a valid outcome of any cycle.\n- Optional dynamic agents defined as plain markdown briefings, with no code.\n- A simulated EUR ledger with real prices, fees, and FX.\n- A learning store that scores matured predictions and tracks an S&P 500 (SPY)\n  benchmark.\n- House rules in `docs/STRATEGY.md` that are enforced in code.\n- One model adapter layer covering local and cloud OpenAI-compatible backends\n  plus native Anthropic and Gemini.\n- A tabbed web dashboard you can reconfigure live without a restart.\n- A command-line interface for one-off cycles, status, backtests, and backups.\n- An optional Model Context Protocol (MCP) server that exposes the fund as tools.\n- Free data sources by default. Optional keys unlock extra sources.\n\n## Quickstart\n\nYou need Python 3.11 or newer. Node 18+ is optional (see [Development](#development)).\n\nOne command does everything: it installs dependencies on first run, then starts\nthe dashboard.\n\n### macOS / Linux\n\n```bash\n./start.sh\n```\n\nIf you downloaded a ZIP instead of cloning, the file may not be executable, so\nuse `bash start.sh` instead.\n\n### Windows\n\nDouble-click `start.bat`, or from a command prompt:\n\n```bat\nstart.bat\n```\n\nOn first run this creates a virtual environment and installs dependencies, then\nboots the backend, waits until it is healthy, opens the dashboard in your default\nbrowser, and prints the URL in the terminal. The default URL is\n`http://127.0.0.1:8500`. Stop with `Ctrl+C`. Later runs skip the install and start\nimmediately.\n\n## Choosing a model\n\nBy default loopfund runs fully local with no API keys.\n\n1. Install [LM Studio](https://lmstudio.ai) or [Ollama](https://ollama.com).\n2. Load (LM Studio) or pull (Ollama) any instruct/chat model.\n3. Put that model's id in the dashboard Settings tab, or in `config/models.yaml`\n   (the `model:` field).\n\nTo use a cloud backend instead, set `backend:` in `config/models.yaml` and paste\nthat backend's API key in the dashboard, or put it in `.env`.\n\n### Supported backends\n\nBackends are selected by name with `backend:` in `config/models.yaml`. Each\nbackend's URL and key come from `.env` (see `.env.example`) or the Settings tab.\n\n| Type | Backend name | Default endpoint | Key needed |\n|---|---|---|---|\n| Local | `local` (LM Studio, default) | `http://localhost:1234/v1` | no |\n| Local | `ollama` | `http://localhost:11434/v1` | no |\n| Local | `vllm` / LocalAI | `http://localhost:8000/v1` | no |\n| Cloud | `openai` | provider default | yes |\n| Cloud | `anthropic` | provider default | yes |\n| Cloud | `gemini` | provider default | yes |\n| Cloud | `openrouter` | provider default | yes |\n| Cloud | `groq` | provider default | yes |\n| Cloud | `together` | provider default | yes |\n| Cloud | `deepseek` | provider default | yes |\n| Cloud | `mistral` | provider default | yes |\n| Cloud | `xai` | provider default | yes |\n| Cloud | `qwen` (Alibaba DashScope) | provider default | yes |\n\nAny other OpenAI-compatible host works too: point one preset's `*_BASE_URL` at it.\n\nEach backend reads its credentials from env vars following the pattern\n`<NAME>_API_KEY` and `<NAME>_BASE_URL`, for example `OPENAI_API_KEY`,\n`ANTHROPIC_API_KEY`, `GEMINI_API_KEY` (or `GOOGLE_API_KEY`),\n`OPENROUTER_API_KEY`, `GROQ_API_KEY`, `DEEPSEEK_API_KEY`, and `DASHSCOPE_API_KEY`\nfor `qwen`. Local backends need no key.\n\n## Configuration\n\nThere are three places to configure loopfund, and they overlap by design.\n\n- `.env` holds secrets and endpoints. Copy `.env.example` to `.env` and fill in\n  only what you need. Everything is optional, and with no keys at all loopfund\n  runs fully local. Never commit `.env` (it is git-ignored).\n- `config/models.yaml` sets which backend and model each profile and agent uses,\n  plus temperature and token limits.\n- The dashboard Settings tab edits any setting live, including raw JSON. You can\n  switch backend and model without a restart. API keys pasted here are stored\n  server-side in `.env`, stay git-ignored, and are never displayed back.\n\nOther config files:\n\n- `config/settings.yaml` sets mode, base currency, watchlist, loop intervals,\n  decision rules, portfolio sizing, and logging.\n- `config/risk_limits.yaml` sets the risk governor limits.\n\n### Data sources\n\nFree sources work with no keys:\n\n- yfinance for prices.\n- frankfurter.dev and er-api for FX.\n- GDELT and RSS for news.\n- SEC EDGAR for filings and XBRL.\n\nOptional keys (FRED, Reddit, NewsAPI) enable extra sources. Leaving a key blank\ndisables only that source.\n\n## Using the dashboard\n\nThe dashboard is a tabbed web UI:\n\n- Overview: portfolio value, positions, and recent decisions.\n- Agents: each specialist agent's stance, findings, and confidence.\n- Market: watchlist and market data.\n- Memory / Mind: long-term memory and the live thinking feed.\n- Settings: every setting, editable live, including raw JSON and backend, model,\n  and key changes without a restart.\n- Health: service health.\n\nThe Market tab shows live prices in both native currency and your base currency:\n\n![loopfund market tab with live prices and FX](docs/dashboard-market.png)\n\n## How it works\n\nA continuous research loop runs specialist agents on a schedule.\n\nCore agents are Research, Macro, Fundamentals, Sentiment, IPO/M&A, AltData,\nQuant, Risk (a skeptic with veto power), and a Decision coordinator. Optional\ndynamic agents are defined as markdown briefings in `agents/briefings/*.md`, so\nyou add or change one by editing a markdown file.\n\n![loopfund agents tab showing the specialist agent roster](docs/dashboard-agents.png)\n\nFindings are combined by evidence-weighted aggregation, not a majority vote. The\nRisk agent can veto or haircut a proposed action. The Decision agent makes one\nallocation decision per configured interval, and `NO_ACTION` is a valid decision.\n\nA learning store scores predictions once they mature and tracks an S&P 500 (SPY)\nbenchmark. House rules live in `docs/STRATEGY.md` and are enforced in code. Inference\nis serialized to one model call at a time to keep memory use low.\n\n## CLI reference\n\nPass any command to the launcher (`./start.sh <cmd>`, or `start.bat <cmd>` on\nWindows):\n\n| Command | What it does |\n|---|---|\n| `serve` | Launch the dashboard (backend and loop control). |\n| `cycle` | Run one full research/decision cycle now. |\n| `status` | Print the current portfolio snapshot. |\n| `backtest TICKER` | Quick backtest of one ticker. |\n| `backup` | Snapshot runtime state now. |\n| `backups` | List backups. |\n| `restore <name>` | Restore a backup (snapshots current state first). |\n| `reset` | Wipe runtime state (after a safety backup). |\n\n## Project layout\n\n```\nagents/          specialist agents and markdown briefings\ncore/            config, store, loop runner, app wiring, backups, sandbox\nmodels_adapter/  model backends and the backend router\nquant/           factors, valuation/DCF, backtest, regime detection\ntools/           data sources and plugins\nmemory/          vector RAG and the learning store\nexecution/       dry-mode ledger and risk governor\nschemas/         pydantic models\ndashboard/       FastAPI API backend and React/Vite web frontend\nmcp_server/      Model Context Protocol server\nconfig/          settings.yaml, models.yaml, risk_limits.yaml\nskills/          markdown playbooks\nscripts/         CLI entrypoint (run.py), requirements.txt, helper scripts\ntests/           unit tests\ndeploy/          Docker assets (Dockerfile, compose, nginx)\ndocs/            STRATEGY, ROADMAP, EXTENDING, screenshots\n```\n\n## Development\n\nA prebuilt dashboard ships in the repo, so it works without Node. `start.sh`\nrebuilds it on first run if Node 18+ is present, or rebuild it yourself:\n\n```bash\ncd dashboard/web && npm install && npm run build\n```\n\nFor live frontend development on macOS/Linux:\n\n```bash\n./start.sh --dev\n```\n\nThis runs the backend plus the Vite dev server on `http://localhost:5173`, which\nproxies `/api` to port `8500`. In production the backend serves the built\ndashboard and the API on a single port.\n\nRun the tests:\n\n```bash\n.venv/bin/python -m pytest\n```\n\nThere are 218 unit tests.\n\nLint with ruff (line length 100):\n\n```bash\n.venv/bin/ruff check .\n```\n\n## MCP server\n\n`mcp_server/` exposes the fund as Model Context Protocol tools under the server\nname `loopfund_mcp`, over stdio or streamable-HTTP. Any MCP client can read the\nportfolio, agent analyses, and decisions, search memory, and trigger a cycle.\nSee `mcp_server/README.md` for details.\n\n## Safety and limitations\n\n- Dry mode only. Live trading is gated in `core/app.py`: it requires both\n  `mode=live` and the environment variable `LOOPFUND_ALLOW_LIVE=1`, and the\n  execution adapter is intentionally unimplemented, so it cannot move real money.\n- Model-authored code execution fails closed without an OS sandbox.\n- Prompt-injection defenses fence untrusted web, news, and memory content.\n- Free data feeds can be wrong, delayed, or unavailable.\n- Language model outputs can be wrong. Treat every result as a hypothesis, not a\n  recommendation.\n\n### Running it safely\n\n- It binds to `127.0.0.1` (localhost) by default, so only your machine can reach\n  it. That is the intended way to run it.\n- The dashboard API has no authentication and can write files, change settings,\n  and (if you enable it) run model-authored code. Do not expose it to other\n  machines or the internet without putting authentication in front of it. If you\n  set `LOOPFUND_HOST=0.0.0.0` or deploy with Docker, read\n  [deploy/DEPLOY.md](deploy/DEPLOY.md) first and add a password (the bundled\n  `deploy/nginx.conf` shows how).\n- Code execution by the research agent is off by default\n  (`agents.allow_code_execution: false`). Turn it on only on a machine whose\n  files you would be comfortable handing to the model.\n- Your API keys live in `.env`, which is git-ignored. Never commit it.\n- Report a vulnerability per [SECURITY.md](.github/SECURITY.md).\n\n## Contributing\n\nSee [CONTRIBUTING.md](.github/CONTRIBUTING.md).\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE).\n"}