Proxmox

This is a generic guide to installing CUBE OS on Proxmox, the host can be an old PC, or a Mini PC.

1. Preparation

1

Download the CUBE OS image

Visit this repo to download the latest CUBE OS image and extract it after downloading.

For Proxmox VE 9, download the disk image archive (commonly sdcard.vmdk.xz).

Extract it to get the .vmdk file.

2

Prepare a Proxmox VE host

  • A running Proxmox VE host with admin access (Web UI + Shell/SSH)

  • If you haven’t installed Proxmox VE yet, follow the official guide.

  • Recommended resources for the VM:

    • CPU: 2 cores

    • Memory: 4096 MB (4 GB) or more

3

Zigbee Adapter (Optional)

If you need to add Zigbee devices, prepare a Zigbee Dongle. Tested Zigbee Dongles include:

SONOFF ZBDongle-MAX SONOFF ZBDongle-PMG24 SONOFF ZBDongle-LMG21 SONOFF ZBDongle-E SONOFF ZBDongle-P Others listed by developer @darkxst

For more information on Zigbee configurations and compatibility, please refer to this guide.

You can pass the dongle through to the VM in Proxmox (see the optional section below).

2. Create a Virtual Machine (Proxmox)

1

In Proxmox Web UI, click Create VM.

2

General - Set a VM ID and a name, e.g. CUBE OS.

3

OS - Choose Do not use any media.

CUBE OS is provided as a prebuilt disk image. In Proxmox, you will import the disk image and then boot from it.

4

System - Recommended settings:

  • BIOS: OVMF (UEFI)

  • EFI Disk: add an EFI disk (default size is fine)

  • Pre-Enfoll keys: Uncheck

Just like the VirtualBox/VMware guides, UEFI is required. If you can’t boot, double-check the BIOS is set to OVMF (UEFI).

5

Disk / CPU / Memory / Network

  • Disk: do not create a new empty disk. You will import the CUBE OS disk image in the next section.

  • CPU: 2 cores (CPU type host recommended)

  • Memory: 4096 MB (4 GB) or more

  • Network:

    • Bridge: vmbr0 (or your LAN bridge)

    • Model: VirtIO (paravirtualized)

For LAN discovery and cube.local to work reliably, avoid NAT-style networking. Use a bridged network connected to your home/office LAN.

3. Import the CUBE OS disk image into Proxmox

You’ll import the extracted CUBE OS image (for example CUBE-OS.vmdk) and attach it as the VM’s boot disk.

1

Find the right storage (local, not local-lvm). In the Proxmox Web UI left sidebar, click local (not local-lvm).

2

Upload the .vmdk into local

  1. Click Import

  2. Select the extracted disk image on your computer, for example:

    • sdcard.vmdk

  3. Wait for the upload to complete (800+ MB can take a while)

After it finishes, you should see the file in the Content list.

3

Attach the imported disk and set it as boot disk. In the CUBE OS VM:

  1. Go to Hardware

  2. Select the imported Add → Import Hard Disk

  1. Then go to Options → Boot Order and set the imported disk as the first boot device.

4. Boot CUBE OS

1

Click to the VM and open the Console.

2

Wait a few moments for CUBE OS to initialize.

Once boot is complete, you should see the IP address displayed on the console.

3

Open the CUBE OS Web UI

Upon successful access, a short ID can be viewed on the settings page. Subsequently, access the CUBE OS Web management page using cube-{short id}.local, which is useful for differentiating multiple CUBE OS instances on the same local network.

5. (Optional) Zigbee USB Dongle passthrough (Proxmox)

1

Plug the Zigbee dongle into the Proxmox host.

2

In the VM, go to Hardware → Add → USB Device.

  • Prefer selecting by Vendor/Device ID (more stable than by port if you move USB ports).

  • If your dongle exposes a serial interface, it may also appear under Add → Serial Port depending on your setup.

3

Reboot the VM (if required) and then add Zigbee devices in CUBE OS.

PreviousHyper-VNextNAS Devices

Last updated