Local Mirth
Local Mirth is a feature of the MirthSync VS Code extension that scaffolds a self-contained Docker Compose stack into your workspace. One command spins up a throwaway Mirth / Open Integration Engine instance plus its backing Postgres database, with the extension auto-wiring a connection profile pointing at the running stack.
For the tutorial walkthrough, including the traditional installer path as an alternative, see the 2026 Mirth/OIE/BridgeLink Docker Quickstart blog post.
Prerequisites
Section titled “Prerequisites”| Requirement | Why |
|---|---|
| VS Code 1.85.0 or later | Hosts the extension |
| MirthSync VS Code extension | See the installation guide |
| Docker Desktop (Windows/Mac) or Docker Engine (Linux) | Runs the stack — nothing else needed on the host |
The tools container inside the stack ships its own MirthSync CLI and JRE, so you don’t need either installed on your host for Local Mirth operations.
Architecture
Section titled “Architecture”Initializing Local Mirth writes .mirthsync/local/ into your workspace with three services defined in compose.yml:
| Service | Image | Bound to | Purpose |
|---|---|---|---|
mirth | sagait/engine (Saga-packaged Open Integration Engine with Saga plugins preinstalled) | 127.0.0.1:8443 (with auto-fallback if busy) | The integration engine itself |
postgres | Standard Postgres | Named volume, internal network only | Mirth’s backing database — survives Stop, wiped only by Reset |
tools | Alpine + JRE + mirthsync + curl + git + jq | Internal network only | Runs CLI commands inside the stack so the host needs nothing |
The extension auto-creates a Local Mirth entry in the Connections tree view pointing at the running mirth service. MirthSync CLI calls from VS Code (Pull All, Push All, Deploy Channel, etc.) get routed into the tools container.
Commands
Section titled “Commands”All commands are run from the VS Code command palette (Ctrl+Shift+P / Cmd+Shift+P).
| Command | Effect |
|---|---|
MirthSync: Initialize Local Mirth | Scaffolds .mirthsync/local/ (compose stack + tools container) into the workspace. Run once per workspace; commit .mirthsync/local/ to your repo so the next developer gets the same stack. |
MirthSync: Start Local Mirth | Builds the tools image and starts the three containers. Auto-creates the “Local Mirth” connection profile. Auto-falls back to an alternate host port if 8443 is busy and persists the choice in .mirthsync/local/.env. |
MirthSync: Stop Local Mirth | Stops the containers without deleting state. Postgres data survives on the named volume. |
MirthSync: Reset Local Mirth (Delete State) | Stops the stack and wipes its Postgres + appdata volumes. Next Start gets a fresh database with default admin / admin credentials. |
MirthSync: Remove Local Mirth (Delete All) | Stops the stack, deletes its volumes and locally-built tools image, removes .mirthsync/local/, and deletes the auto-created Local Mirth connection. Pristine “as if it was never initialized” state. |
MirthSync: Show Local Mirth Status | Per-service running/health summary. |
MirthSync: Show Local Mirth Logs | Tail Mirth container logs into the MirthSync output channel. |
MirthSync: Show Local Mirth Info | URL, default credentials, files location, launcher links — with copy actions. |
Settings
Section titled “Settings”| Setting | Default | Description |
|---|---|---|
mirthsync.localMirth.mirthImageTag | 4.5.2-ubuntu-jre | Image tag for the Local Mirth server. Points at the sagait/engine repo — Saga-packaged Open Integration Engine. Edit compose.yml directly to point at openintegrationengine/engine for vanilla OIE. |
mirthsync.localMirth.mirthsyncVersion | 3.5.2 | MirthSync release version baked into the Local Mirth tools image. |
mirthsync.localMirth.additionalPorts | [] | Additional host ports to forward from the Mirth container (e.g., MLLP/HTTP listener ports). The extension writes these to an auto-managed docker-compose.override.yml on next Start. |
Opening the Administrator
Section titled “Opening the Administrator”Local Mirth runs the engine but doesn’t ship the Mirth Connect Administrator (a Java client). Install a launcher on your host and point it at the URL Show Local Mirth Info provides.
- Ballista — community launcher used with Open Integration Engine. Requires a host JRE 8+.
- NextGen MCAL — legacy NextGen Mirth Connect Administrator Launcher. Bundles its own JRE.
Default credentials are admin / admin; the Administrator will prompt you to change the password on first login.
Common Operations
Section titled “Common Operations”Adding extra listener ports
Section titled “Adding extra listener ports”Mirth’s container only exposes the Administrator API on 8443 by default. To expose an MLLP listener on 6661 or an HTTP listener on 8081, set:
"mirthsync.localMirth.additionalPorts": [6661, 8081]Then Stop and Start Local Mirth. The extension writes a docker-compose.override.yml next to compose.yml that forwards the additional ports.
Switching to vanilla OIE (not Saga-packaged)
Section titled “Switching to vanilla OIE (not Saga-packaged)”The default sagait/engine image is OIE with Saga’s plugins preinstalled. To use vanilla OIE instead, edit .mirthsync/local/compose.yml and change the mirth service image reference to openintegrationengine/engine:<tag>. Then Reset Local Mirth to start fresh against the new image.
Connecting your channel workspace to the stack
Section titled “Connecting your channel workspace to the stack”Local Mirth doesn’t require a special workspace structure — once it’s running, the auto-created Local Mirth connection works with the same Pull All / Push All commands as any other Mirth connection. Pull your channel repo’s .mirthsync workspace into Local Mirth with Push All to test your changes against the stack.
Troubleshooting
Section titled “Troubleshooting”Port 8443 already in use
Section titled “Port 8443 already in use”The extension detects the conflict at Start, suggests an alternate port, and persists the choice in .mirthsync/local/.env. If you’d rather Mirth always bind to a specific port, edit .env directly and set MIRTH_HTTPS_PORT=<your-port>.
Tools image build fails
Section titled “Tools image build fails”The tools image is built locally on first Start. If the build fails (network issue, Docker Hub rate-limited, etc.), run Start Local Mirth again — Docker resumes from cached layers. If the build keeps failing, run Remove Local Mirth and Initialize again from a clean state.
Mirth container is up but Administrator can’t connect
Section titled “Mirth container is up but Administrator can’t connect”Mirth ships with a self-signed certificate. The Administrator caches the previous server’s cert per-launcher; clear the cache or accept the new cert on first connect. Default credentials remain admin / admin until you change them.
Containers stop unexpectedly
Section titled “Containers stop unexpectedly”Show Local Mirth Logs tails the Mirth container’s logs into the MirthSync output channel. Most often the cause is the host running out of memory (Mirth + Postgres together need ~1.5 GB RAM minimum) — close other Docker workloads and retry Start.
”Disk pressure” warnings on cold-start volumes
Section titled “”Disk pressure” warnings on cold-start volumes”The Postgres volume grows with message history. If Stop + Start cycles aren’t reclaiming space, run Reset Local Mirth to wipe the database completely. For pristine state, run Remove Local Mirth and Initialize again.
Related
Section titled “Related”- Installation — set up the extension itself
- Commands & Settings — full extension command reference (beyond Local Mirth)
- 2026 Mirth/OIE/BridgeLink Docker Quickstart — tutorial walkthrough with the traditional installer path as an alternative
- MirthSync for VS Code blog post — the editorial introduction to the extension