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
这是什么？一个自托管的本地 HTTPS 和 MQTT 服务器，在你自己的局域网上模拟 Roborock 的云端后端，让 Roborock 扫地机器人在不连外网的情况下保留实时地图和本地控制，且无需 root 或改装硬件。
这是我要导入的库，还是要运行的服务器？它是一套通过 Docker Compose 或 Home Assistant 加载项部署的自托管服务器组件，不是库——它用本地的 HTTPS 和 MQTT 组件替代 Roborock 的云服务。
怎么让它跑起来？为你的域名设置本地 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 扫地机器人吗？不——由于证书校验方式的差异，Q7 等入门级 Q 系列机型目前不受支持，而且不同机型接受的证书链并不相同，所以在选择证书方案前请先查看 Tested Vacuums 列表。
扫地机器人接入本地之后，我怎么控制它？通过 Home Assistant（有加载项可用）、开源的 LocalRock 手机应用，或针对 Android 打过补丁、或通过 iOS MITM 描述文件转接的官方 Roborock 应用。
我的扫地机器人还会和 Roborock 云端通信吗？不会——配对完成后，DNS 会把扫地机器人重定向到你的本地服务器而不是 Roborock 云端，因此地图和控制都留在与互联网隔离的局域网内。
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
935
Updated
CommitOct 12Releasev1.2.1Oct 08
Age
6mo
Commits · 90 Days