> For the complete documentation index, see [llms.txt](https://cube.ewelink.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cube.ewelink.cc/getting-started/quickstart/docker.md).

# Docker

Install CUBE OS as a Docker container on a Linux host. This method works well for home servers, NAS devices, and always-on Linux machines.

{% hint style="info" %}
Docker deployment is supported on **Linux only**.

If you do not have a Linux host, use [Raspberry Pi](/getting-started/quickstart/raspberry-pi.md) or [Virtual Machine](/getting-started/quickstart/virtual-machine/virtualbox.md).
{% endhint %}

### 1. Preparation

{% stepper %}
{% step %}
**Check the host architecture**

CUBE Docker supports these Linux architectures:

* **amd64** (`x86_64`) — PCs, servers, Synology NAS, and similar devices
* **arm64** (`aarch64`) — Raspberry Pi 4/5, Orange Pi, and other ARM hosts
  {% endstep %}

{% step %}
**Check the Linux kernel version**

Kernel `4.15` or later is required.

```bash
uname -r
```

{% hint style="warning" %}
Some NAS devices ship with older kernels, such as `4.4.x`. These hosts are not compatible with CUBE Docker. In that case, run CUBE OS in a Linux virtual machine instead.
{% endhint %}
{% endstep %}

{% step %}
**Install Docker Engine**

Install Docker Engine on the host before you continue.

Use the [official Docker installation guide](https://docs.docker.com/engine/install/).
{% endstep %}

{% step %}
**Check required ports**

Make sure ports `80` and `1883` are free on the host.

```bash
sudo lsof -i :80
sudo lsof -i :1883
```

* **80** — CUBE OS web UI
* **1883** — MQTT broker

If another service is using these ports, stop it first.
{% endstep %}

{% step %}
**Prepare a Zigbee dongle if needed**

If you plan to add Zigbee devices, connect a compatible Zigbee dongle to the host.

Tested Zigbee dongles include:

> SONOFF ZBDongle-MAX\
> SONOFF ZBDongle-PMG24\
> SONOFF ZBDongle-LMG21\
> SONOFF ZBDongle-E\
> SONOFF ZBDongle-P\
> [Others listed](https://darkxst.github.io/silabs-firmware-builder/) by developer @darkxst 

{% hint style="info" %}
For more information on Zigbee configurations and compatibility, please refer to this [guide](/compatibility-check/zigbee.md).
{% endhint %}

For more information on Zigbee support, refer to [this guide](/compatibility-check/zigbee.md).
{% endstep %}
{% endstepper %}

### 2. Pull the image

{% stepper %}
{% step %}
**Download the latest image**

```bash
docker pull ghcr.io/ewelinkcube/cube-os:latest
```

<div align="left"><figure><img src="/files/xKwfo0hAhKjpnvC69qH2" alt="" width="563"><figcaption></figcaption></figure></div>

{% hint style="info" %}
You can replace `latest` with a specific version tag, such as `2.10.3`. Available versions are listed on [GitHub Releases](https://github.com/eWeLinkCUBE/CUBE-OS/releases/).
{% endhint %}
{% endstep %}
{% endstepper %}

### 3. Start CUBE OS

{% stepper %}
{% step %}
**Create a data directory**

```bash
mkdir -p ~/cubeos-data
```

This directory stores your devices, scenes, and settings.
{% endstep %}

{% step %}
**Check the Zigbee device path if you use one(optional)**

Common device paths are:

```bash
ls /dev/ttyUSB* /dev/ttyACM*
```

Use the correct path in the next command.
{% endstep %}

{% step %}
**Start the container**

Use this command as a baseline:

```bash
docker run -d \
  --name cubeos \
  --privileged \
  --net=host \
  -v ~/cubeos-data:/data \
  --device /dev/ttyUSB0:/dev/ttyUSB0 \
  -v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro \
  ghcr.io/ewelinkcube/cube-os:latest
```

<div align="left"><figure><img src="/files/mV7ow7VSjwCc1HEZRo6F" alt="" width="563"><figcaption></figcaption></figure></div>

{% hint style="info" %}
If you do not use Zigbee, remove `--device /dev/ttyUSB0:/dev/ttyUSB0`.

If you do not use Matter Hub or eWeLink Remote, you can also remove the D-Bus mount.
{% endhint %}
{% endstep %}

{% step %}
**Understand the main parameters**

* `--privileged` — required for hardware access
* `--net=host` — required for LAN discovery and MQTT
* `-v ~/cubeos-data:/data` — keeps your data after container restarts
* `--device /dev/ttyUSB0:/dev/ttyUSB0` — passes through a Zigbee dongle
* `-v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro` — enables D-Bus access for supported features
  {% endstep %}
  {% endstepper %}

### 4. Access CUBE OS

{% stepper %}
{% step %}
**Confirm that the container is running**

```bash
docker ps
```

The container status should show `Up`.
{% endstep %}

{% step %}
**Open the web UI**

Open a browser on the same network and visit one of these addresses:

* `http://<HOST_IP>/`
* <http://cube.local>

Replace `<HOST_IP>` with the Linux host IP address.
{% endstep %}

{% step %}
**Use the short local address later**

After setup, you can find the short ID on the settings page.

You can then use `cube-{short-id}.local` to identify this CUBE OS instance on your LAN.
{% endstep %}
{% endstepper %}

### 5. Update CUBE OS

The Docker deployment does not support OTA updates from the web UI.

To update manually:

```bash
docker stop cubeos
docker rm cubeos
docker pull ghcr.io/ewelinkcube/cube-os:latest

docker run -d \
  --name cubeos \
  --privileged \
  --net=host \
  -v ~/cubeos-data:/data \
  --device /dev/ttyUSB0:/dev/ttyUSB0 \
  -v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro \
  ghcr.io/ewelinkcube/cube-os:latest
```

Your data stays in `~/cubeos-data`, so devices, scenes, and settings remain after the update.

### 6. Limitations

Due to container isolation, these features are not available in Docker deployments:

* **Add-ons** — cannot install or manage add-ons
* **Bluetooth Speaker** — Bluetooth passthrough is not supported
* **System Update** — OTA updates in the web UI are disabled
* **Reboot / Shutdown** — system-level power controls are unavailable

### 7. Raspberry Pi note

If you run Docker on a Raspberry Pi, make sure the page size is `4096`:

```bash
getconf PAGE_SIZE

# If the result is not 4096, add this line and reboot
echo "kernel=kernel8.img" | sudo tee -a /boot/firmware/config.txt
sudo reboot
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cube.ewelink.cc/getting-started/quickstart/docker.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.