Get started

From install to your first routed message

Install MessageFoundry with pip on Python 3.14 or newer. This guide uses SQLite and a sample route to receive your first message.

Browse the documents → All guides → HL7 over MLLP → Build an interface →

Use a sandboxed, non-production environment with synthetic data. MessageFoundry started in May 2026 and is beta-level software under fast development. Read the project status →

Before moving beyond a sandbox, read the Early-Adopter Installation & Rollout Guide ↗. It covers prerequisites, limits, capacity tests on your hardware, backup and restore, and staged rollout checks.

Quickstart steps

Install

Create a virtual environment and install MessageFoundry from PyPI. Read about release signing and verification →

terminal

# virtual environment
python -m venv .venv
# macOS / Linux:   . .venv/bin/activate
# Windows (PS):    .venv\Scripts\Activate.ps1

# install from PyPI
pip install messagefoundry

Clone the repository to use the sample configuration and messages below:

terminal

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.

terminal

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.

terminal

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 web console

The engine serves the web console by default. Open it to view dashboards, search messages, inspect the HL7 parse tree, and replay messages. You do not need to install software on each workstation.

terminal

pip install messagefoundry-webconsole
# restart the engine, then open http://127.0.0.1:8765/ui

Author your own route

The VS Code extension’s New Connection and New Route wizards can generate the configuration. To write it yourself, add a Python module to your config directory. Name inbound and outbound Connections, then link a Router and Handler by name:

config/IB_Lab_ORU.py

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:

terminal

python -m messagefoundry check --config samples/config

FAQ

Frequently asked questions

What do I need to run MessageFoundry?

Use Python 3.14 or newer on Windows, Linux, or macOS. Install with pip from PyPI. The built-in SQLite store needs no separate database setup. PostgreSQL and SQL Server are also supported for production deployments.

How do I install MessageFoundry?

Create a virtual environment and run pip install messagefoundry. Start the engine with a config directory and store database, then follow the quickstart to receive a test message.

Do I have to write code to build an interface?

No. Use the guided wizards in the VS Code extension, or write Python when you need custom logic. Both produce readable configuration you can keep in 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.