Python-roborock/local_roborock_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.

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

1. Cloud-locked maps: Roborock routes all map data strictly through their cloud servers (despite the vacuum storing the map locally).
2. 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.

• 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).

• 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.

• 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.

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

1. Installation for the shared requirements, network setup, and Docker Compose install path.
2. Home Assistant if you want to install the stack as a Home Assistant add-on instead of Docker Compose.
3. Cloudflare setup if you want Cloudflare DNS-01 auto-renew for certificates.
4. Onboarding to pair a vacuum from a second machine after the server is running.
5. 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

Published image:

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

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

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

• 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!

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:

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.

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