From install to your first routed message
MessageFoundry installs from PyPI with a single pip install messagefoundry — a signed, versioned release you can verify, not a moving source checkout — and runs locally on Python 3.14+. Once it's running, you can build interfaces two ways: with guided wizards in the VS Code extension and admin console, or in plain Python for full control. It starts zero-config on SQLite; point it at PostgreSQL or SQL Server for production.
Planning a real pilot? This quickstart gets you running; for a production pilot, start with the Early-Adopter Installation & Rollout Guide ↗ — prerequisites, honest limitations, capacity testing on your own hardware, backup/restore, and a staged rollout with go/no-go gates. MessageFoundry is pre-1.0 Early Access; the guide is the playbook for adopting it safely.
Install
Create a virtual environment and install MessageFoundry from PyPI — a signed, versioned release. How releases are signed & attested →
# virtual environment python -m venv .venv # macOS / Linux: . .venv/bin/activate # Windows (PS): .venv\Scripts\Activate.ps1 # install from PyPI pip install messagefoundry
The sample-driven steps below use config and messages from the repository, so clone it alongside to follow along:
git clone https://github.com/MEFORORG/MessageFoundry.git
cd MessageFoundry
Run the engine
Load the sample config, open the store, and serve the localhost API on 127.0.0.1:8765.
python -m messagefoundry serve --config samples/config --db messagefoundry.db # API on http://127.0.0.1:8765 # GET /connections GET /messages GET /stats WS /ws/stats
Send a test message
The sample config's IB_Test_ADT listens for MLLP on port 2575. Send it an ADT and watch it route.
python samples/send_mllp.py samples/messages/adt_a01.hl7 # A01/A04/A08 → archived to ./out/adt/<MSH-10>.hl7 # other events → logged FILTERED; non-ADT → logged UNROUTED
Open the admin console
A separate desktop app that attaches to the API — dashboards, message search and browse, parse-tree viewer, and one-click replay.
pip install "messagefoundry[console]"
python -m messagefoundry.console --url http://127.0.0.1:8765
Author your own route
Prefer wizards? The VS Code extension's New Connection and New Route flows generate this for you. Or, if you prefer code, drop a Python module into your config directory — name an inbound and outbound Connection, then wire a Router and Handler by name:
from messagefoundry import MLLP, Send, inbound, outbound, router, handler inbound("IB_Lab_ORU", MLLP(port=2580), router="oru_router") outbound("OB_EHR_ORU", MLLP(host="10.0.0.21", port=6661)) @router("oru_router") def route(msg): if msg["MSH-9.1"] != "ORU": return [] # UNROUTED return ["to_ehr"] @handler("to_ehr") def to_ehr(msg): if msg["OBR-25"] == "X": # drop corrected-in-error return None # FILTERED return Send("OB_EHR_ORU", msg)
Validate it before it ships with the commit gate:
python -m messagefoundry check --config samples/config
Frequently asked questions
What do I need to run MessageFoundry?
Python 3.14 or newer on Windows, Linux, or macOS. MessageFoundry installs from PyPI with pip and starts zero-config on a built-in SQLite store, so you can run it on a laptop; for production it also supports PostgreSQL and SQL Server.
How do I install MessageFoundry?
Create a virtual environment and run pip install messagefoundry, then start the engine pointed at a config directory and a store database. The quickstart walks through receiving your first HL7 v2 message over MLLP.
Do I have to write code to build an interface?
No. You can set interfaces up with guided wizards in the VS Code extension and drop into plain Python whenever you need full control — either way the result is readable configuration you version-control.
Which databases does MessageFoundry support?
SQLite out of the box for zero-config local runs, and PostgreSQL or SQL Server for production scale-out and high availability.