Hello Community!
In the latest version CUBE OS 2.10.3, you can now run CUBE as a Docker container! This opens up new possibilities for deploying CUBE on NAS devices, home servers, and other Linux machines.
Currently Supported Architectures
CUBE Docker currently supports the following architectures under Linux systems only:
- amd64 (x86_64) — regular PCs, servers, Synology NAS, QNAP NAS, etc.
- arm64 (aarch64) — Raspberry Pi 4/5, Orange Pi, Apple Silicon Mac (via Linux VM), etc.
Note: Docker images are built for Linux containers. If you’re on Windows or macOS, we highly recommend using the one-click installer. Please check One-click Installation | eWeLink CUBE.
Before You Start
Make sure port 80 and port 1883 are not in use on your host machine:
- Port 80 — CUBE Web UI (HTTP)
- Port 1883 — MQTT (device communication)
If these ports are occupied (e.g., by nginx or Apache), you’ll need to stop those services first.
Quick Start
1. Pull the image
docker pull ghcr.io/ewelinkcube/cube-os:2.10.3
2. Start the container
docker run -d \
--name cubeos \
--privileged \
--net=host \
-v /xxx/data:/data \
--device /dev/ttyUSB0:/dev/ttyUSB0 \
-v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro \
cubeos:2.10.3
Replace xxx with the actual directory path on your host where you want CUBE to store its data (e.g., /home/pi/cubeos-data).
Parameter Explained
| Parameter | Purpose |
|---|---|
--privileged |
Privileged mode — CUBE needs access to host hardware |
--net=host |
Host networking — required for device discovery and MQTT communication |
-v /xxx/data:/data |
Mount data directory — replace xxx with your actual path; data persists across recreations |
--device /dev/ttyUSB0 |
Pass through Zigbee dongle — only needed if you have Zigbee devices |
-v .../system_bus_socket:ro |
Mount host D-Bus — required for eWeLink Remote and Matter Hub |
3. Verify
docker ps
Then open your browser and visit http://your-device-ip
Important Notes
Due to Docker’s containerized architecture, some features are not available in the Docker version:
- Add-ons — cannot install/manage add-ons (like Node-RED, Z2M, etc.)
- Bluetooth Speaker — Bluetooth hardware passthrough is not supported
- System Update — cannot update CUBE from the web UI (you need to pull the new image and recreate the container)
- Reboot / Shutdown — these system-level controls are not available
How to Update CUBE OS
Since the Docker version doesn’t support OTA updates, you’ll need to update manually when a new version is released. Don’t worry — your data is safe as long as you’ve mounted the data volume.
# 1. Stop the old container
docker stop cubeos
# 2. Pull the new image (replace X.X.X with the new version)
docker pull ghcr.io/ewelinkcube/cube-os:X.X.X
# 3. Start a new container with the same parameters
docker run -d \
--name cubeos \
--privileged \
--net=host \
-v /xxx/data:/data \
--device /dev/ttyUSB0:/dev/ttyUSB0 \
-v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro \
cubeos:X.X.X
Note: Use the same startup parameters as before. Replace
xxxwith your actual data directory path andX.X.Xwith the new version number. Your config, devices, and scenes are stored in the mounted data directory, so they will persist across updates.
Raspberry Pi Users
If you’re using a Raspberry Pi, make sure your page size is set to 4K:
# Check current page size
getconf PAGE_SIZE
# If it's not 4096, add this line:
echo "kernel=kernel8.img" | sudo tee -a /boot/firmware/config.txt
sudo reboot
Want Support for More Architectures?
We currently support amd64 and arm64 Linux systems. If you’d like us to support other architectures (like arm32, etc.), please leave a comment below and let us know what hardware you’re using!