You enroll an Android device by scanning a QR code during its setup, which makes the MDMesh agent its Device Owner.
From the web console you then install apps on it, lock it into kiosk mode, see its location and send it remote
actions. On quick-start installs, the server updates from signed releases; agents update from the signed release's
APK.
Why MDMesh
- There is no paid edition. Kiosk mode, app installs, location and the installers are all open source under
Apache-2.0.
- Updates are signed, and on quick-start installs a failed update rolls back. The updater only offers releases
whose signature verifies. You apply an update with one click. The updater backs up the
database first and rolls back by itself if the new version fails its health check.
- Older agents keep working after a server update. The agent is a Device Owner app written in Kotlin. The server
only sends it commands it reports it supports, and the agent protocol (
/agent/v1) only ever adds fields. A test
in CI checks this.
- One command installs the server. It runs on Docker Compose with automatic HTTPS (Caddy) or a Cloudflare Tunnel,
or natively on Debian 12/13 and Ubuntu 24.04, on x86_64 or Arm64. The published Docker images are x86_64 only for
now; Arm64 images are planned.
■ Features
- Devices: the device list shows each device's status, with search, filters and sorting. The Overview lists the
devices that need attention, each with a button for the next step.
- Device page: tabs for remote actions, telemetry (hardware, battery, storage, network), apps, activity and
location. The Apps tab lists the device's apps that have a launcher icon, from its latest scan, with search and a
CSV export.
- Configurations: a configuration sets up to 25 device settings, from kiosk options to Wi-Fi, factory reset and
Safe Mode. Devices apply it at their next check-in, and the device page shows the result for each setting. Apps
added to a configuration install on its devices at their next check-in.
- Kiosk mode: locks a device to one app or to a grid of chosen apps, in the colours the configuration sets. Safe
Mode is blocked in kiosk unless the configuration allows it. If a one-app kiosk's app closes, the launcher opens it
again; if it closes more than 3 times within a minute, the device stays in kiosk and shows an "Open again" button.
An exit PIN can end kiosk on the device; too many wrong PINs lock the exit for a while and, when email is set up,
email the administrators.
- Apps: add apps from your own APK uploads, from the F-Droid catalog or by a link to the APK. Every install is
checked against the app's SHA-256: uploads and F-Droid apps have one already, and for a link you add it. The agent
installs apps without asking the device's user.
- Remote actions: send an alert or a lock-screen message, ring, lock, reboot, enter or exit kiosk mode, reset the
passcode or factory-reset a device. Passcode reset and factory reset ask you to confirm. An alert that can't show,
because notifications are off on the device, is reported as failed.
- Connectivity: by default the agent keeps its live connection only while the screen is on or the device is
charging. A configuration can set it to Always-on, so commands reach a locked device right away.
- Location: a configuration sets whether devices report their last known location, a fresh GPS fix or nothing.
The device page shows the location history on a map, for the last hour, 24 hours, 7 days or all of it.
- Staged agent rollouts: a new agent version goes to a set of canary devices first. You promote it to the other
devices once the canaries have updated.
- Sign-in and audit: failed sign-ins are limited per address and per account. The audit log records sign-ins,
changes and the commands sent to devices, with who did it and from where.
- Extending: forks add console pages, tabs and sections in
web/src/extensions/ and server plugins in
plugins/fork/, without editing core files (EXTENDING).
■ Quick start
On an x86_64 Linux host with Docker, Docker Compose v2, curl, openssl 3.0+ (or an older openssl and
minisign), and either a domain in Cloudflare (for a Cloudflare Tunnel) or a domain pointed at the host with ports 80
and 443 open:
bash <(curl -fsSL https://github.com/MDMesh-app/MDMesh/releases/latest/download/quickstart.sh)
To check quickstart.sh against the signed release before it runs, use the
checked install in DEPLOY.md instead.
The quick start pulls the released images and sets up updates from the console. To build the images from source instead
(./setup.sh --update needs git, curl, and openssl 3.0+, or an older openssl and minisign; python3 is
optional, to verify the release for the enrollment QR):
git clone https://github.com/MDMesh-app/MDMesh.git && cd MDMesh
./setup.sh --update # checks out the newest signed release, then sets it up
Without Docker, run sudo ./setup.sh --update --native from the clone on Debian 12/13 or Ubuntu 24.04 (x86_64 or
Arm64). It only needs git and brings the rest (native install). Each
installer prints the console URL and a temporary admin password. Then enroll a device:
- Sign in and set your own password.
- Open Enroll and choose a configuration. The page shows its QR code.
- Factory-reset an Android device (Android 7.0 or later) and tap the welcome screen six times to open the QR
scanner.
- Scan the code. The device enrolls as Device Owner and checks in.
On a test device you can also use adb shell dpm set-device-owner (docs/DEV.md).
DEPLOY.md covers the hosting modes and the native install, and
docs/UPGRADING.md covers updates.
■ How it works
- You edit a configuration in the console. Each changed setting is marked "Changed" until you select Save and
apply.
- The server wakes the devices that use the configuration over their WebSocket connection. Each agent checks in
and gets a
config.apply command. A device without an open connection gets it at its next regular check-in.
- The agent applies each setting and reports the result for each one. The device page shows which settings were
applied, which failed and which the device doesn't support.
■ Architecture
The server is a Java (Jersey) REST API with a PostgreSQL database. In the Docker install, Caddy serves the React
console and passes API requests to the server. Caddy gets the TLS certificate. With a Cloudflare Tunnel, Cloudflare
handles TLS instead. A native install serves the console from Tomcat, behind your own TLS proxy. Agents check in
over REST and keep a WebSocket open, so the server can wake them when there's a command. The updater, a separate
service, checks GitHub Releases and verifies each release's minisign signature. On quick-start installs it also
applies the update, with a database backup and an automatic rollback. STRUCTURE.md describes the
code layout.
■ Roadmap
- Done: the web console, the Device Owner agent, kiosk mode, app installs, location, signed updates, staged agent
rollouts and extensions for forks.
- Next: remote control of a device's screen (view and input) over WebRTC, with a self-hosted TURN server.
- Later: support for device makers' management APIs (Samsung Knox, Zebra) through the agent's capability layer.
■ Contributing
Code, docs, bug reports and ideas are all welcome. Start with CONTRIBUTING.md, then
report a bug or
suggest a feature. For a PR, follow
the PR template; small, focused PRs merge fastest. Report security issues
privately, as SECURITY.md describes.
■ License & credits
MDMesh is licensed under the Apache License 2.0. It is a fork of Headwind MDM
by Headwind Solutions LLC, also Apache-2.0 (why and how: ADR-0008).
Trademarks and brand names belong to their owners.