local_roborock_server: Open Source Internet of Things (IoT)

What is local_roborock_server?

Roborock Local Server is a self-hosted HTTPS and MQTT cloud emulator that lets Roborock robot vacuums keep live maps and local controls on an isolated LAN without internet access, rooting the firmware, or modifying the hardware, and it is aimed at self-hosters and Home Assistant users who want to take the vendor cloud out of the loop.

What it is

Roborock Local Server is an on-premises HTTPS and MQTT stack that emulates Roborock's cloud backend on your own network. By redirecting DNS and completing an initial onboarding handshake, the vacuum is made to connect to your local server instead of the official cloud. The project is written in Python, licensed under MIT, lives in the Python-roborock organization, and publishes a container image through GHCR alongside a documentation site.

The problem it solves is specific. Home Assistant already speaks to Roborock vacuums over a local protocol, but two constraints historically blocked fully offline operation. First, Roborock routes all map data strictly through its cloud servers even though the vacuum stores the map locally, so cloud-locked maps meant no live maps or room cleanups without connectivity. Second, the vacuum performs cloud health checks: when it cannot reach Roborock's servers, it repeatedly restarts its network interface and drops local communication. Upstream cloud authentication changes are also the most frequent point of failure for third-party integrations. Local Server replaces that cloud dependency with a service the operator controls.

Key capabilities

Local map streaming: live maps and room cleanups work without cloud access.
A local HTTPS and MQTT stack combined with DNS redirection and an onboarding handshake, so the vacuum connects to your server rather than the official cloud.
No hardware modifications: no disassembly, soldering, or bootloader unlocking is required.
Greenfield onboarding that supports new vacuums out of the box without prior cloud registration.
Reversible setup: resetting the vacuum's Wi-Fi returns it to factory pairing mode.
Frontend options spanning Home Assistant (add-on available), the open-source LocalRock mobile app, and the official app via an Android APK patch or an iOS MITM profile.
Support for most Roborock vacuums, including modern v2 protocol models, with documented custom MQTT and custom certificate management.

Who users are and how they run it

Home Assistant users who prefer the add-on install path and documented integration setup over a manual Docker Compose deployment.
Self-hosters running the stack on a LAN machine with a domain they control, rewriting DNS through Pi-hole, AdGuard Home, or router DNS.
Households keeping the vacuum on an isolated LAN with no internet access, so map data stays on premises.
Users of the open-source LocalRock mobile app, or those patching the Android APK or installing the iOS MITM profile to keep using the official app.
Operators of modern v2 protocol models, who must consult the tested vacuums list before choosing a certificate path, because models do not all accept the same certificate chains.

Getting started

Installation is documented as a Docker Compose deployment in docs/installation.md, or as a Home Assistant add-on following docs/home_assistant.md, with a container image published to GHCR. Onboarding then pairs a vacuum from a secondary machine with Wi-Fi once the server is running.

How it compares

Local Server is built to complement rather than replace Home Assistant, which already communicates with Roborock vacuums over a local protocol but leaves maps and health checks dependent on the cloud. Its practical alternatives for control are the LocalRock open-source mobile app and the official Roborock app reached through an APK patch or MITM profile, and it belongs to the same Python-roborock organization behind the underlying Python integration work.

When to use it — and when not to

Choose it if you are willing to operate a domain with local DNS rewriting, a valid SSL certificate (automated through Cloudflare DNS-01 or generated manually), a Docker Compose host or a Home Assistant installation with add-on support, and a secondary Wi-Fi computer for onboarding. Entry-level Q series vacuums such as the Q7 are currently unsupported because of differences in certificate validation, and certificate acceptance varies across models, so the tested vacuums list and the known limitations document are essential reading rather than optional. Anyone who does not want to manage DNS records and certificate chains should not pick it.

project readme (upstream, from github) — read inline

Roborock Local Server

Run Roborock's cloud backend on your own local network. Your vacuum keeps live maps and local controls on an isolated LAN without internet access, requiring no hardware modifications or firmware rooting.

Why this exists

While Home Assistant communicates with Roborock vacuums over a local protocol, two constraints previously prevented running them completely offline:

Cloud-locked maps: Roborock routes all map data strictly through their cloud servers (despite the vacuum storing the map locally).
Cloud health checks: If a vacuum cannot reach Roborock's servers, it repeatedly restarts its network interface, dropping local communication.

Upstream cloud authentication changes are also the most frequent point of failure for third-party integrations.

Roborock Local Server provides an on-premises HTTPS and MQTT stack. By redirecting DNS and completing an initial onboarding handshake, the vacuum connects to your local server instead of the official cloud.

Features

Local map streaming: Live maps and room cleanups work without cloud access.
No hardware modifications: No disassembly, soldering, or bootloader unlocking required.
Greenfield onboarding: Supports new vacuums out of the box without prior cloud registration.
Reversible: Resetting the vacuum's Wi-Fi returns it to factory pairing mode.
Frontend options: Works with Home Assistant (Add-on available), LocalRock (open-source mobile app), or the official app (via Android APK patch or iOS MITM profile).

Compatibility

Supported: Most Roborock vacuums, including modern v2 protocol models (based on firmware research by Dennis Giese).
Currently unsupported: The entry-level Q series (such as the Q7; not to be confused with QRevo) due to differences in certificate validation.
See the Tested Vacuums List for specific model reports.

Requirements

A domain you control with local DNS rewriting (Pi-hole, AdGuard Home, or router DNS).
A place to run the stack on your LAN (Docker Compose or Home Assistant installation that supports add-ons).
A valid SSL certificate for your domain (automated via Cloudflare DNS-01 or generated manually).
A secondary computer with Wi-Fi for initial onboarding.

Getting Started

Start here if this is your first time setting up the stack:

Installation for the shared requirements, network setup, and Docker Compose install path.
Home Assistant if you want to install the stack as a Home Assistant add-on instead of Docker Compose.
Cloudflare setup if you want Cloudflare DNS-01 auto-renew for certificates.
Onboarding to pair a vacuum from a second machine after the server is running.
Updating if you already have an install and are moving to a newer stable release.

Before choosing a certificate path, check Tested vacuums. Different models do not all accept the same certificate chains. For most users, start with ZeroSSL. Use Actalis mainly for older vacuums or models that are already known to trust that chain more reliably.

Additional docs:

Docs index
Technical Writeup: How Reverse Engineering Works
Known limitations
Tested vacuums
Home Assistant for the add-on install path and integration setup
Mobile App Options
Custom MQTT
Custom certificate management

Container Image

Published image:

docker pull ghcr.io/python-roborock/local_roborock_server:latest

Contributing

If you would like to contribute, help in these areas is especially welcome:

Code is always welcome that you have fully tested.
Video walkthroughs and setup tutorials.
Documentation improvements and network configuration guides.

Acknowledgements

Dennis Giese (@dgiese) whose research and papers inspired much of the work on reverse-engineering Roborock vacuums.
Sören Beye (@Hypfer) creator of Valetudo, whose work on cloud-free vacuum control has been foundational for this whole space.
@rovo89 who has been VERY helpful through this process, giving lots of tips and advice.
python-miio - Their repo was the basis for a lot of python-roborock's logic.
@humbertogontijo who first created the python-roborock repo.
@allenporter who has taken up a significant role in the maintenance of the python-roborock library as well as the Roborock integration. The improvements Allen has made to the repository cannot be overstated.
@rccoleman who was the first beta tester and helped work out some kinks!

Support the Project

If this repository worked for you, consider giving it a star on GitHub to help others find it!

If you are purchasing a Roborock device and want to support continued development, consider using an affiliate link:

Direct donations:

Disclaimer

This software is provided "as is", without warranty of any kind. Running this stack involves modifying how your Roborock vacuum communicates with the network. You are solely responsible for any damage to your hardware, data loss, network exposure, or other consequences. Use at your own risk. This project is not affiliated with, endorsed by, or sponsored by Roborock.

License

This project is licensed under the MIT License — see LICENSE for details.

Frequently asked questions

Is local_roborock_server free to use?

local_roborock_server is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does local_roborock_server do?

Local HTTPS and MQTT cloud emulator for Roborock vacuums without rooting or hardware modifications

What is local_roborock_server written in?

local_roborock_server is primarily written in Python. Its source is publicly available at https://github.com/Python-roborock/local_roborock_server, and it has 759 GitHub stars.