Open-FDD

Open-FDD is a free, open-source building-to-cloud pipeline for HVAC analytics and fault detection. The same stack runs on-premises or in the cloud: high-performance Apache Arrow storage and Apache DataFusion SQL, a Rust central service, React operator UI, Mosquitto MQTTS ingest, and fieldbus edge agents for BACnet, Modbus, and Haystack — plus REST APIs and CSV/zip import when you are not on live OT.

Deploy locally or as a cloud hub and pull building data over MQTTS, APIs, or files. Today’s product is SQL-based FDD and RCx on that Arrow/DataFusion engine; the roadmap is ML and clustering on the same foundation.

---

Install / run

Install / run

FDD Rule Cookbook — 62 public rules / 66 SQL registry ids: datafusion-sql-cookbook · pandas-cookbook · PyPI open-fdd

GHCR images

Image	Role
ghcr.io/bbartling/openfdd-central	MQTTS ingest, Feather historian, DataFusion FDD, REST /api
ghcr.io/bbartling/openfdd-web	React operator SPA (browser → central /api only)
ghcr.io/bbartling/openfdd-fieldbus	BACnet / Modbus / Haystack / JSON edge
ghcr.io/bbartling/openfdd-mqtt	Mosquitto MQTTS broker
ghcr.io/bbartling/openfdd-mcp	Optional slim MCP stdio sidecar → central API

Run

git clone https://github.com/bbartling/open-fdd.git && cd open-fdd
export OPENFDD_IMAGE_TAG=nightly
export OPENFDD_JWT_SECRET='change-me'
export OPENFDD_ADMIN_PASSWORD='change-me'

./scripts/openfdd_stack_up.sh react       # local CSV lab (ready today)
./scripts/openfdd_stack_up.sh csv         # central + web only
# Cloud hub path: openfdd-fieldbus → MQTTS (see docs/operations/RAILWAY_DEPLOYMENT.md)

Update a running stack (pull, backup, rollback if health fails):

./scripts/openfdd_maint_update_resume.sh react nightly

UI http://127.0.0.1:3000 · API http://127.0.0.1:8080 · build recipes

MCP

Open-FDD does not ship an embedded AI chatbot. External agents connect via MCP or REST — see external agents.

docker run -i --rm --network host \
  -e OPENFDD_API_BASE=http://127.0.0.1:8080 \
  -e OPENFDD_MCP_TOKEN="$TOKEN" \
  ghcr.io/bbartling/openfdd-mcp:nightly

Tool list: mcp/README.md.

PyPI package

PyPI package

pip install open-fdd

Library for notebooks and ECM helpers — not the operator stack. See PyPI and docs.

Develop

Develop

git clone https://github.com/bbartling/open-fdd.git && cd open-fdd
./scripts/openfdd_stack_up.sh react --build
cd frontend/web && npm ci && npm run dev

Rust: cargo test --workspace

Releases

Releases

GHCR images build on every master merge. Set OPENFDD_IMAGE_TAG=nightly (or sha-<7> to pin). Beta/stable are not published yet — release policy.

Intended for LAN / VPN / OT networks, not public internet hosting. The Railway field lab is experimental (see status blurb above).

Security

Security

Do not report vulnerabilities through public GitHub issues or discussions. Use GitHub Private Vulnerability Reporting. See SECURITY.md for what to include and how to redact sensitive OT/deployment evidence.

💛 Support This Work

If Open-FDD saves you time or budget, or helps with BAS/FDD work, you can support continued open-source development through PayPal. Your contribution directly helps fund the monthly time and labor required to keep the project moving forward. Your support is greatly appreciated.

License

MIT — see LICENSE.

Version 3.3.37 on tip · PyPI 4.4.2