local_roborock_server README

The project's README from github.com/Python-roborock/local_roborock_server. As one markdown file: README.md.

Roborock Local Server

GHCR Docs GitHub stars

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:

  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.

Features

Compatibility

Requirements

Getting Started

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:

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:

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

Acknowledgements

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:

Amazon Affiliate Roborock Affiliate

Direct donations:

Buy Me a Coffee PayPal

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.

local_roborock_server (Python-roborock/local_roborock_server)

Searching Database…

935 ·GitHub
Local_roborock_server
What is this?A self-hosted local HTTPS and MQTT server that emulates Roborock's cloud backend on your own LAN, letting your Roborock vacuum keep live maps and local control without reaching the internet, and without rooting or modifying hardware.
Is this a library I import, or a server I run?It's a self-hosted server stack you deploy via Docker Compose or as a Home Assistant add-on, not a library — it replaces Roborock's cloud with an on-premises HTTPS and MQTT stack.
How do I get it running?Set up local DNS rewriting for your domain (Pi-hole, AdGuard Home, or router DNS), get an SSL certificate (via Cloudflare DNS-01 or manually), deploy the stack with Docker Compose or the Home Assistant add-on, then onboard the vacuum from a second Wi-Fi-connected machine.
What do I need before starting?A controlled domain with local DNS rewriting, a valid SSL certificate for it, somewhere to run Docker Compose or a Home Assistant install with add-on support, and a second Wi-Fi-capable computer for onboarding.
Does it work with every Roborock vacuum?No — entry-level Q series models like the Q7 are currently unsupported due to differences in certificate validation, and different models don't all accept the same certificate chain, so check the Tested Vacuums list before picking a cert path.
How do I control the vacuum once it's connected locally?Through Home Assistant (an add-on is available), the open-source LocalRock mobile app, or the official Roborock app patched for Android or routed through an iOS MITM profile.
Does my vacuum still talk to Roborock's cloud?No — once onboarded, DNS redirects the vacuum to your local server instead of Roborock's cloud, so maps and controls stay on an isolated LAN without internet access.
What is LocalRock?LocalRock is an open-source mobile app listed as one of the frontend options for controlling your vacuum once it's running on the local server, alongside Home Assistant and the patched official app.
Why can't Roborock vacuums just work fully locally already?Roborock routes all map data through its cloud even though the vacuum stores the map locally, and if a vacuum can't reach those servers it keeps restarting its network interface, which breaks local communication too.
Can I undo this setup if something goes wrong?Yes — resetting the vacuum's Wi-Fi returns it to factory pairing mode, making the whole process reversible.
What are similar projects?EchoMuse, glasshouse, techo5, ha_xiaomi_home, core, zigbee2mqtt, Tasmota, frigate
Which topics is it in?certificate, mitm, smart-home, mqtt, ssl, home-assistant, home-automation, homelab, dns, iot, cloudflare, reverse-engineering
Creator
Python-roborock
Size
1.2 MB
Stars
935
Updated
CommitOct 12Releasev1.2.1Oct 08
Age
6mo
Commits · 90 Days