Community tier · free for private use · no account
Get Melanite.
One runtime, three ways to run it. They are the same product — pick the one that matches the hardware in front of you.
What will run Melanite?
Pick the hardware in front of you. We'll take it from there, one step at a time.
Windows or Mac?
Which kind of processor does it have?
Not sure? Run this on the machine — it prints amd64 or arm64:
dpkg --print-architectureStep 1 of 3
Install Docker Desktop
You should see
Docker Desktop is open and says Engine running.
Didn't work?
- Windows asks to install or update WSL: say yes, and restart when it asks.
- It does not start: restart the computer once after installing.
- On a Mac, pick the download that matches your Mac: Apple menu → About This Mac shows Apple M… or Intel.
Step 2 of 3
Start Melanite
docker run -d --name melanite --restart unless-stopped `
--stop-timeout 30 --cap-add SYS_NICE `
--ulimit rtprio=99 --ulimit memlock=-1 `
-p 5001:5001 -p 5002:5002 -p 1883:1883 `
-v melanite-data:/data/melanite `
-e TZ={TZ} `
-e MELANITE_FLAVOR_FILE=/usr/share/melanite/flavor.desktop.json `
melanite.io/melanite:latestdocker run -d --name melanite --restart unless-stopped \
--stop-timeout 30 --cap-add SYS_NICE \
--ulimit rtprio=99 --ulimit memlock=-1 \
-p 5001:5001 -p 5002:5002 -p 1883:1883 \
-v melanite-data:/data/melanite \
-e TZ={TZ} \
-e MELANITE_FLAVOR_FILE=/usr/share/melanite/flavor.desktop.json \
melanite.io/melanite:latestYou should see
The first time it downloads for a minute or two, then prints one long line of letters and numbers. That line means Melanite is running.
Didn't work?
- Cannot connect to the Docker daemon: Docker Desktop is not running yet — start it and try again.
- port is already allocated: another program uses port 5001. Change
-p 5001:5001to-p 5081:5001and use port 5081 in the next step. - The container name "/melanite" is already in use: you started it before. Run
docker start melaniteinstead.
Step 3 of 3
Open Melanite
You should see
Melanite's setup asks for a name and an admin PIN. Write the PIN down: it protects everything that can move a machine.
Didn't work?
- The page does not load: give it half a minute — the first start takes a moment — then reload.
Step 1 of 6
Check what you need
- A Raspberry Pi 5 and its power supply
- A microSD card of 32 GB or more, and a card reader
- A network cable to your router — and, easiest for the first start, a screen (micro-HDMI)
- A Windows, Mac or Linux computer
Step 2 of 6
Install Raspberry Pi Imager
You should see
Imager opens and asks for your device.
Step 3 of 6
Download Melanite
Download Melanite for Raspberry Pi
This file isn't published yet, so this step can't be done today. Leave your address at the bottom of the page and we'll tell you when it is.
You should see
A file whose name ends in .wic.xz in your downloads. Leave it compressed — Imager unpacks it while writing.
Step 4 of 6
Write the card
You should see
Imager writes the image, checks it and says the card can be removed.
Didn't work?
- Imager offers to customise the OS (hostname, Wi-Fi, user): skip it — Melanite sets itself up on its first start and would ignore those settings.
- The file does not show up in the file picker: switch the picker's file type to all files.
- The card is too small, or the write fails near the end: Melanite needs 32 GB or more.
- Verification failed: write it again, or use another card — cheap cards fail more often.
- Prefer balenaEtcher? Choose Flash from URL, paste
https://melanite.io/get/raspberry-pi, pick the card and flash.
Step 5 of 6
Start the Pi
You should see
With a screen: after a minute or two, Melanite's setup appears. Without one: the Pi shows up in your router's device list as melanite- followed by six characters.
Didn't work?
- Nothing on the screen after three minutes: check the card is fully inserted, then power-cycle.
Step 6 of 6
Set it up
http://melanite-xxxxxx.local:5001 on your computer, with the name from your router's list.You should see
Setup asks for a name and an admin PIN. Write the PIN down.
Didn't work?
melanite-….localdoes not open: use the IP address from your router's list instead, e.g.http://192.168.1.42:5001.
Step 1 of 6
Check what you need
- A Compute Module 5 with eMMC
- The CM5 IO Board, or a carrier whose USB boot port you can reach
- A USB-C cable that carries data, and the board's power supply
- A network cable — and, easiest for the first start, a screen
- A Windows, Mac or Linux computer
Step 2 of 6
Install Imager and rpiboot
Get the rpiboot installer (Windows)
git clone --depth=1 https://github.com/raspberrypi/usbboot && cd usbboot
make && sudo ./rpibootYou should see
Both installed.
Didn't work?
- Windows: the rpiboot installer (rpiboot_setup.exe, from Raspberry Pi's usbboot).
- Mac or Linux: build it from source with the two lines shown (Mac: install
libusbwith Homebrew first).
Step 3 of 6
Download Melanite
Download Melanite for Raspberry Pi
This file isn't published yet, so this step can't be done today. Leave your address at the bottom of the page and we'll tell you when it is.
You should see
A file whose name ends in .wic.xz in your downloads. Leave it compressed.
Step 4 of 6
Make the eMMC visible
You should see
After a few seconds the eMMC shows up on your computer as a new drive.
Didn't work?
- Nothing appears: check the jumper, and use a USB-C cable that carries data, not only power.
Step 5 of 6
Write the eMMC
You should see
Imager writes the image, checks it and reports success.
Didn't work?
- Imager offers to customise the OS: skip it — Melanite sets itself up on its first start.
- The write fails on Windows: Imager on Windows is known to be unreliable writing this image to a CM5. Writing it from a Linux computer works — the Reference view has the commands.
Step 6 of 6
Start it
http://melanite-xxxxxx.local:5001 with the name from your router's list.You should see
Setup asks for a name and an admin PIN. Write the PIN down.
Step 1 of 3
Install the package
curl -fLo melanite.deb https://melanite.io/get/linux-deb-{ARCH} && sudo apt install ./melanite.debThis file isn't published yet, so this step can't be done today. Leave your address at the bottom of the page and we'll tell you when it is.
You should see
apt installs Melanite and starts it as two services, melanite and melanite-rt.
Didn't work?
- Not Debian or Ubuntu: use the tarball — the Reference view has the commands.
- curl: command not found: install it first with
sudo apt install curl.
Step 2 of 3
Open Melanite
http://<this machine>:5001.You should see
Melanite's setup asks for a name and an admin PIN. Write the PIN down.
Step 3 of 3
Check its real-time readiness
melanite-checkYou should see
A list of checks with a verdict. Each failed check comes with its fix; exit status 0 means ready for hard real-time.
Melanite is running.
Next: build your first control loop — a PID holding a value at its setpoint, in about ten minutes.
- Docker Any PC, server or NAS — Windows, macOS or Linux. Up in minutes. amd64 · arm64
- Linux package Your own industrial PC, NUC or Raspberry Pi 5, as two systemd services. amd64 · arm64
- Raspberry Pi One image for the Pi 5 and the Compute Module 5: flash it, and the board boots into a PLC with a touch HMI. Pi 5 · CM5
01
Docker
The whole of Melanite in one container: the node engine and its real-time process, the HMI, the 2D and 3D views, MQTT, Modbus TCP and WLED. What a container cannot have, it tells you itself under Settings → This machine.
-
Save this as compose.yaml:
services: melanite: image: melanite.io/melanite:latest container_name: melanite restart: unless-stopped network_mode: host # found on the LAN as itself: mDNS, MQTT, pairing cap_add: [SYS_NICE] # the real-time process may run at SCHED_FIFO ulimits: { rtprio: 99, memlock: -1 } volumes: - melanite-data:/data/melanite - /etc/localtime:/etc/localtime:ro environment: MELANITE_RT_STOP_TIMEOUT: "5" MELANITE_APP_STOP_TIMEOUT: "20" stop_grace_period: 30s volumes: melanite-data:services: melanite: image: melanite.io/melanite:latest container_name: melanite restart: unless-stopped environment: MELANITE_FLAVOR_FILE: /usr/share/melanite/flavor.desktop.json TZ: Europe/Berlin # your time zone — the VM runs on UTC MELANITE_RT_STOP_TIMEOUT: "5" MELANITE_APP_STOP_TIMEOUT: "20" ports: - "5001:5001" # the app - "5002:5002" # https (a phone needs it for its microphone) - "1883:1883" # the built-in MQTT broker cap_add: [SYS_NICE] ulimits: { rtprio: 99, memlock: -1 } volumes: - melanite-data:/data/melanite # a named volume, never a Windows folder stop_grace_period: 30s volumes: melanite-data: -
Start it — the first start pulls the image from melanite.io:
docker compose up -d -
Open
http://<this host>:5001on Linux orhttp://localhost:5001on Docker Desktop; the setup wizard asks for a name and an admin PIN.
No internet on the target?
Download the image archive for its architecture, load it, and use the same compose file with the version tag instead of latest:
docker load -i melanite-<version>-docker-amd64.tar.gz
# compose.yaml: image: melanite.io/melanite:<version>| Docker Desktop | Docker on Linux | |
|---|---|---|
| Node graph, HMI, 2D and 3D, logging, alarms, assistant | Yes | Yes |
| MQTT broker, Modbus TCP, WLED, network cameras | Yes | Yes |
| Real-time process | Yes — 5 ms cycle | Yes — 5 ms cycle; better on a PREEMPT_RT host |
| Found by devices on the LAN | Through the published ports | Yes (host network) |
| EtherCAT | No | With an IgH master on the host |
| Sound outputs as synced speakers | No | With /dev/snd passed in |
Updates: pull the new image and recreate the container — your programs live in the melanite-data volume and carry over.
02
Linux package
The full product on a machine you already run — an industrial PC, a NUC, a server or a Raspberry Pi 5. Self-contained (no .NET needed), two systemd services, an unprivileged user. You bring the machine, the kernel and, for EtherCAT, the IgH master; Melanite tells you whether they are good enough.
-
Download the package for your architecture (Debian 12 or 13, Ubuntu 22.04 or 24.04):
File Arch Version Size SHA-256 Download -
Install it — or, on any other systemd distribution, unpack the tarball and run its installer:
sudo apt install ./melanite_<version>_amd64.deb # or, from the tarball: tar xzf melanite-<version>-linux-amd64.tar.gz sudo ./melanite-<version>-linux-amd64/install.sh Open
http://<this machine>:5001and the setup wizard asks for a name and an admin PIN.-
Is this machine ready for hard real-time? melanite-check says, check by check, with the fix:
melanite-check # exit 0 = ready for hard real-time sudo melanite-check --hwlat=60 # also measure firmware latency (stop Melanite first)
A PREEMPT_RT kernel and one isolated core are what turn a PC into a 1 ms controller — melanite-check prints the exact kernel line for this machine. Your programs live in /var/lib/melanite and are never removed by the package, not even on purge.
03
Raspberry Pi
One image for the Raspberry Pi 5 and the Compute Module 5. Flash it and the board boots straight into Melanite — the real-time kernel, EtherCAT and the touch HMI, nothing else to install. Only the way the image gets onto the board differs.
-
Download the image (and, for bmaptool, its block map):
-
Put the card in the reader and write the image to it — lsblk shows which /dev/sdX is the card:
lsblk sudo bmaptool copy melanite-<version>-raspberry-pi.wic.xz /dev/sdX # or without bmaptool: xzcat melanite-<version>-raspberry-pi.wic.xz | sudo dd of=/dev/sdX bs=4M conv=fsync status=progress Put the card in the Pi 5, connect Ethernet and, if you have one, a display.
Power on. The device opens a setup Wi-Fi — join it from a phone and setup opens by itself; on a touchscreen it shows a QR code for the same.
The image boots from the SD card: its partitions and updates are laid out for it, so NVMe boot is not supported. Rather keep Raspberry Pi OS? The Linux package installs on it instead, on the stock kernel.
-
Fit the board's nRPIBOOT jumper (disable eMMC boot), connect USB-C to the PC, power the board, and expose the eMMC as a USB drive with Raspberry Pi's rpiboot:
git clone --depth=1 https://github.com/raspberrypi/usbboot && cd usbboot make && sudo ./rpiboot -
Write the image — lsblk shows which /dev/sdX is the eMMC:
lsblk sudo bmaptool copy melanite-<version>-raspberry-pi.wic.xz /dev/sdX # or without bmaptool: xzcat melanite-<version>-raspberry-pi.wic.xz | sudo dd of=/dev/sdX bs=4M conv=fsync status=progress Remove the jumper and power-cycle. Power on. The device opens a setup Wi-Fi — join it from a phone and setup opens by itself; on a touchscreen it shows a QR code for the same.
Flashing replaces everything on the card or eMMC. Back up first (Settings → Backup & Restore). Flash from Linux: Raspberry Pi Imager on Windows is unreliable with this image.
Check what you downloaded
Every file's SHA-256 is listed next to it, measured by our server from the file itself. Compare before you install:
sha256sum <file> # Linux
shasum -a 256 <file> # macOS
Get-FileHash <file> # Windows PowerShellWhat changed in each version: the changelog. Free for private use, teaching and non-commercial research. Any use by a company needs a Commercial licence — see pricing.
Commercial licences aren't on sale yet.
Leave an address and you get one mail when they are.