Bumper is a self-hosted central server for Ecovacs robots, including DEEBOT vacuums and GOAT mowers. It replaces the Ecovacs cloud, giving you full local control through a privacy-first, high-performance stack: Python + uv, Docker Swarm, and NGINX.
- Self-Hosted: Operate without Ecovacs cloud servers.
- Privacy-First: All data stays within your network.
- High Performance: Python 3.13+ (3.15 by default) with asyncio, aiohttp, slixmpp, and amqtt; uv keeps the environment and lockfile reproducible.
- Docker Swarm & Compose: One-command startup with turnkey NGINX configuration.
- Modular: Easily extend protocols and add integrations.
⚠️ Warning: Branchesmain/devare under active development and may be unstable. Use at your own risk.
TLS certificates:
The checked-in Compose/Swarm files load certificates from $PWD/certs/* as
read-only Docker configs, so create and install them before deployment:
bash scripts/certs/create-cert.sh
# add --rsa if your robot requires RSA keysUse the generated certs/ca.crt on the app and clients;
Certificates
covers key types, SANs, and startup generation.
Environment variables:
Create a .env file with at least the following:
# 'overlay' for Docker Swarm, 'bridge' for plain Docker Compose
NETWORK_MODE=overlay
# required by the Compose file
BUMPER_ANNOUNCE_IP=192.168.0.100 # your server's local IPFull configuration options are available in the Environment Variables.
Step 1 - Clone the repository
git clone https://github.com/MVladislav/bumper.git
cd bumperStep 2 - Initiate Docker in Swarm mode
docker swarm initStep 3 - Start services
# Docker Swarm: pulls ghcr.io/mvladislav/bumper (tag from VERSION_BUMPER, default "latest")
docker-swarm-compose deebot
# or plain Docker Compose: builds the image from this checkout
docker compose up -dStep 4 - Open the UI
Visit https://ecovacs.net/ in your browser.
In-depth guides and architecture details are available in the docs/ folder or online:
- Online: Documentation
- Getting started: DNS Setup and Certificates
- Docker Usage: Docker
- Mobile App: Mobile App Integration
- Environment Variables: Configuration
- How It Works: Architecture
See Model Compatibility for reported working models, known limitations, and cases that still need verification.
The official Ecovacs app works with Bumper once it is patched, and the patch is not tied to an app version anymore - there is no version table to keep. See Mobile App Integration and Certificate Pinning Bypass (APP).
Join our Gitter channel to discuss features, report issues, and share setups:
Or use the GitHub Discussions section for longer conversations and proposals.
Contributions are welcome! To get started:
-
Fork the repo and create a feature branch.
-
Run the checks CI runs:
uv run --active prek run --all-files uv run --active pytest tests
-
Submit a pull request against
main.
See the Development Guide for the full setup and each linter.
Bumper relies on community testing for broader device coverage. If you test Bumper with your robot, please open a discussion with:
classidandmodel(from the app, or match the name inbumper/web/static_api/productIotMap.json)- Firmware version
- Protocol used (MQTT / XMPP / NGIoT)
- Whether the app works, or only a client such as
deebot-client - Success or failure details, with
DEBUG_BUMPER_LEVEL=DEBUGlogs
The confirmed models are tracked on the Model Compatibility page.
Released under the GPLv3 License.
- https://github.com/bmartin5692/bumper
- https://github.com/edenhaus/bumper
- https://github.com/Yakifo/amqtt
- https://github.com/DeebotUniverse/client.py
Special thanks to:
- @torbjornaxelsson for the original Bumper implementation.
- @wpietri and contributors of Sucks for the open-source Ecovacs client.
- All community members who test and contribute to making Bumper better.
Originally forked from edenhaus/bumper (via bmartin5692) · Maintained by @MVladislav

