local_roborock_server: a local cloud for Roborock vacuums

The manufacturer's cloud, run on your LAN

The one-line description in the repository listing is precise: a local HTTPS and MQTT cloud emulator for Roborock vacuums without rooting or hardware modifications.

And the readme's summary says the same thing from the user's side. Run the manufacturer's cloud backend on your own local network, and the vacuum keeps live maps and local controls on an isolated LAN without internet access, requiring no hardware modifications or firmware rooting.

The phrase isolated LAN is doing real work. The point is not that the vacuum stops talking to the internet, it is that the thing it talks to is now yours. The vacuum believes it is talking to the vendor, with the same protocols, the same certificates and the same expectations, and it does not know the difference.

That approach is a deliberate choice against the alternative. The other way to free a vacuum from its cloud is to modify the firmware, which means disassembly, soldering and a bootloader unlock, and which permanently changes a device you might want to sell or return. This project changes nothing about the device, which means the change is entirely in the network, and can be undone.

The result is a stack that provides an on-premises HTTPS and MQTT pair. By redirecting DNS and completing an initial onboarding handshake, the vacuum connects to your local server instead of the official cloud.

The two constraints that kept vacuums online

The section explaining why this exists names two specific constraints, and they are more interesting than a general statement about vendor cloud dependence.

The first is cloud-locked maps. The manufacturer routes all map data strictly through their own cloud servers, even though the vacuum stores the map locally. So the map you see in the application is fetched, not computed on the device, and without the cloud there is no map.

The second is cloud health checks. If a vacuum cannot reach the manufacturer's servers, it repeatedly restarts its network interface, which drops local communication as a side effect. That is the behaviour that makes these devices unusable on an isolated network: the vacuum does not merely lose a feature, it tears down the local connection it has with your Home Assistant instance in the process.

There is a third observation, which is about everyone else rather than about the device. Upstream cloud authentication changes are the most frequent point of failure for third-party integrations. A manufacturer can change their authentication flow on a Tuesday afternoon and break every home automation setup in the country, with no notice and no changelog aimed at people who did not buy the product from them.

So the local server is addressing three separate problems: a feature that cannot work without the cloud, a device that breaks its own local networking when the cloud is unreachable, and a dependency on somebody else's login system.

What you need before you start

The requirements list is short and each item is a real obstacle.

You need a domain you control with local DNS rewriting, and three ways of doing that are named, a network-wide DNS server such as Pi-hole or AdGuard Home, or the DNS settings of your router. You need a place to run the stack on your LAN, with Docker Compose or a Home Assistant installation that supports add-ons. You need a valid SSL certificate for your domain, automated through a DNS-01 challenge with Cloudflare or generated by hand. And you need a secondary computer with Wi-Fi for the initial onboarding.

That last one is worth explaining, because it is the step that looks like a joke and is not. A vacuum has to be told about a new server by being paired with it, and that pairing is done by scanning a code, and the vacuum has to be on the network that the server is on. If you run the server on the same network as the vacuum, you cannot be on that network with your phone at the same time, so you need a second machine.

The DNS requirement is the heart of the design. The vacuum resolves the manufacturer's domain, and your DNS server answers with the address of your local server, and from the vacuum's point of view nothing unusual has happened.

The certificate requirement follows from that. The vacuum is doing normal TLS to what it believes is the manufacturer's domain, so you need a certificate that the vacuum's own trust store will accept for that domain, and a real certificate authority is much more likely to be accepted than a self-signed one.

Which models work, and which certificate to use

The compatibility section is honest in a way that is useful, and it has one specific exclusion.

Most Roborock vacuums are supported, including the modern second generation protocol models, and the readme credits the firmware research that made that possible to a named researcher. There is a tested vacuums list with specific model reports, and the getting started section tells you to check it before you choose a certificate path, because different models do not all accept the same certificate chains.

The exclusion is the entry-level series, and the readme is careful to say which one, because the naming is confusing. The Q series, such as the Q7, is not to be confused with the differently named QRevo, and it is unsupported because of differences in certificate validation.

That reason is instructive. It tells you the failure mode for these devices is the trust store, not the protocol. A vacuum that speaks the protocol perfectly but rejects your certificate chain behaves identically to one that speaks no protocol at all, and no amount of protocol work will fix it.

So the guidance for certificates is practical. For most users, start with one particular authority. Use the other mainly for older vacuums, or for models that are already known to trust that chain more reliably.

The getting started documentation is a five step path, and it is ordered the way you would actually do it: the installation, then the Home Assistant add-on route if you want that instead of Docker Compose, then the Cloudflare setup if you want automated certificate renewal, then the onboarding, then the updating notes for people who already have an install.

Front ends, and how to undo it

The feature list has a line about front end options, and it is the one that tells you who this project is for.

It works with Home Assistant, with an add-on available, with an open source mobile application written by someone else, and with the manufacturer's own application, the last one via an Android package patch or an iOS man-in-the-middle profile.

That last option is worth pausing on, because it is the one that lets a person keep the interface they are used to. The price is interception of the app's traffic, which is a serious thing to do to a phone, and it is only listed as an option rather than recommended.

The other features are about reversibility and about not needing the cloud to get started. There are no hardware modifications, so no disassembly, no soldering and no bootloader unlocking. There is greenfield onboarding, which means a vacuum that has never been registered with the manufacturer can be paired with your server, and this is the feature that makes the project usable for someone buying a device today. And it is reversible, because resetting the vacuum's Wi-Fi returns it to factory pairing mode, so the whole arrangement can be undone without any of it being permanent.

Local map streaming is the first feature listed, and the reason to use the project at all: live maps and room cleanups work without cloud access.

The container, and what the compose file tells you

The image is published in a container registry and the compose file shows the shape of the deployment.

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

The compose file runs one service, and it publishes two ports, one for the HTTPS side and one for the MQTT over TLS side, both of which are configurable through environment variables with defaults. The volumes are the configuration file, mounted read only, a data directory, and a secrets directory also mounted read only, which is the conventional way to pass credentials into a container without baking them into the image.

The health check is a detail worth reading, because it shows the deployment has two modes. It uses a scheme that defaults to HTTPS and can be overridden to plain HTTP for the case where the listener is in external TLS mode and the server itself speaks plain HTTP behind a proxy. The check hits an administrative endpoint on the local address, with a thirty second interval and a start period that gives the container time to come up.

The image is built on a slim Python image, and the system packages installed are the interesting part: certificate authorities, curl, a relay server, a message broker and the OpenSSL tools. The relay and the broker are there because a vacuum does not only speak HTTPS to the cloud, it also uses an encrypted signalling channel, and the stack has to be able to terminate that as well as serve the map API. The image also installs a certificate management tool at build time.

The Python side is an ASGI application, with an async web framework and its server, an async HTTP client, a cryptography library, a second one for a task the first does not cover, a large integer library, and a pinned dependency on the community library that actually speaks to the vacuums.

Credits, licence and a blunt disclaimer

The acknowledgements are unusually long and unusually specific, and they tell you the history of the project.

The first name is the researcher whose work on reversing the vacuum firmware inspired much of this, and the second is the creator of an existing cloud-free vacuum control project whose work is described as foundational for the whole space. Then there is a contributor who was very helpful with tips and advice through the process, a general purpose device library whose repository was the basis for a lot of the logic here, the person who first created the community library this project grew out of, a maintainer who has taken on a significant role and whose improvements cannot be overstated, and the first beta tester who helped work out some kinks.

That list is the best short history of community reverse engineering available, and it explains why the project is credible in a way that a readme cannot.

The disclaimer is short and deserves to be quoted. The software is provided as is, without warranty of any kind. Running the stack involves modifying how the vacuum communicates with the network, and the user is solely responsible for any damage to the hardware, data loss, network exposure or other consequences. Use at your own risk. And the project is not affiliated with, endorsed by, or sponsored by the manufacturer.

The licence is MIT, and the project metadata requires Python 3.11 up to but not including 3.14, with a console entry point and a Hatchling build. The release history shows steady work through 2026, with 1.1.0 in September, 1.2.0 at the end of that month and 1.2.1 in October, and the last push on 2026-10-12.

Editorial conclusion

local_roborock_server suits somebody who owns a Roborock vacuum and wants the live map, the local controls and the room cleanups to keep working without a cloud account, and it is a good example of doing that with DNS redirection rather than with modified firmware. It is a poor fit if the model is one of the unsupported entry-level ones, or if you are not prepared to run a local server and re-point your DNS. Before you start, check the tested vacuums list and pick a certificate authority accordingly, and read the disclaimer, because the project puts the responsibility for network exposure squarely on the user.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. Python-roborock/local_roborock_server on GitHub
4. README
5. Releases