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…

947 ·GitHub
Local_roborock_server
Что это?Self-hosted локальный HTTPS- и MQTT-сервер, эмулирующий облачный бэкенд Roborock в вашей собственной LAN, благодаря чему ваш пылесос Roborock сохраняет живые карты и локальное управление, не выходя в интернет, и без рутинга или модификации железа.
Это библиотека для импорта или сервер, который я запускаю?Это self-hosted серверный стек, разворачиваемый через Docker Compose или как аддон Home Assistant, а не библиотека — он заменяет облако Roborock локальным HTTPS- и MQTT-стеком.
Как его запустить?Настройте локальное DNS-переписывание для вашего домена (Pi-hole, AdGuard Home или DNS роутера), получите SSL-сертификат (через Cloudflare DNS-01 или вручную), разверните стек через Docker Compose или аддон Home Assistant, затем привяжите пылесос со второй машины, подключённой к Wi-Fi.
Что мне нужно перед началом?Подконтрольный домен с локальным DNS-переписыванием, действительный SSL-сертификат для него, место для запуска Docker Compose или установка Home Assistant с поддержкой аддонов, а также второй компьютер с Wi-Fi для привязки.
Он работает с любым пылесосом Roborock?Нет — бюджетные модели серии Q вроде Q7 сейчас не поддерживаются из-за различий в проверке сертификатов, и не все модели принимают одну и ту же цепочку сертификатов, так что сверьтесь со списком Tested Vacuums, прежде чем выбирать путь с сертификатом.
Как управлять пылесосом после локального подключения?Через Home Assistant (доступен аддон), мобильное приложение с открытым кодом LocalRock или официальное приложение Roborock, пропатченное для Android или пропущенное через MITM-профиль на iOS.
Мой пылесос всё ещё общается с облаком Roborock?Нет — после привязки DNS перенаправляет пылесос на ваш локальный сервер вместо облака Roborock, так что карты и управление остаются в изолированной LAN без доступа в интернет.
Что такое LocalRock?LocalRock — мобильное приложение с открытым кодом, значащееся одним из вариантов фронтенда для управления пылесосом, когда тот работает на локальном сервере, наряду с Home Assistant и пропатченным официальным приложением.
Почему пылесосы Roborock до сих пор просто не могут полностью работать локально?Roborock пропускает все данные карт через своё облако, хотя пылесос хранит карту локально, и если пылесос не может достучаться до этих серверов, он постоянно перезапускает свой сетевой интерфейс, что ломает и локальную связь.
Можно ли отменить эту настройку, если что-то пойдёт не так?Да — сброс Wi-Fi пылесоса возвращает его в заводской режим сопряжения, делая весь процесс обратимым.
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
947
Updated
CommitOct 12Releasev1.2.1Oct 08
Age
6mo
Commits · 90 Days