Install Gladys Assistant on Proxmox VE
If you already run a Proxmox VE server at home, you can host Gladys Assistant on it next to your other services.
We recommend running Gladys in a virtual machine (VM) with Debian, then installing it with Docker exactly like on any Linux server. A VM behaves like a real computer: the official installation command works as is, your Zigbee dongle is passed through over USB, and Gladys is reachable at gladysassistant.local on your network.
This guide uses the menu names of the Proxmox web interface in English, on Proxmox VE 8 and 9.
Step 1: Download the Debian ISO
In the Proxmox web interface, select your storage (usually local), open ISO Images, then click on Download from URL.
Paste the link of the latest Debian "netinst" image for your architecture (amd64 for most mini-PCs and servers), available on the Debian website, click on Query URL, then on Download.
Ubuntu Server works just as well if you prefer it: only the installation in step 3 is different.
Step 2: Create the virtual machine
Click on Create VM at the top right and go through the wizard:
- General: name the VM
gladys. Tick Advanced, then Start at boot, so Gladys starts again after a reboot of the server. - OS: select the ISO you just downloaded.
- System: tick Qemu Agent.
- Disks: 32 GB is enough to start. Gladys keeps the history of your sensors, so give it more if you have a lot of devices.
- CPU: 2 cores. Choose the host type for the best performance (in a cluster with different CPU models, see the FAQ below).
- Memory: 4096 MB (4 GB). Gladys runs with 2 GB, but Zigbee2MQTT and the other integrations will thank you for the margin.
- Network: keep the default bridge (
vmbr0) and the VirtIO model, so the VM gets an address on your home network like any other device.
Confirm, then start the VM.
Step 3: Install Debian or Ubuntu Server
Open the Console of the VM and follow the installer. On Debian, at the Software selection step:
- untick the desktop environments (Gladys does not need one),
- tick SSH server and standard system utilities.
sudo first on DebianIf you set a root password during the installation, Debian does not install sudo, and the commands of this guide need it. Log in as root with su -, then run:
apt update && apt install -y curl sudo
usermod -aG sudo your-user
Replace your-user with your username, then log out and back in.
The Ubuntu installer has no software selection step: just tick Install OpenSSH server when it asks. Ubuntu already comes with sudo and curl.
Once the system is installed and the VM has rebooted, log in and install the Qemu guest agent, which lets Proxmox show the IP address of the VM and shut it down cleanly:
sudo apt update && sudo apt install -y qemu-guest-agent
sudo reboot
We also recommend giving the VM a fixed IP address with a DHCP reservation in your router: the IP address of the VM is shown in its Summary tab once the guest agent runs.
Step 4: Pass through your Zigbee dongle (and Bluetooth)
If you use a USB Zigbee coordinator, plug it into the Proxmox server, then give it to the VM:
- Select the VM, open Hardware, then click on Add > USB Device.
- Choose Use USB Vendor/Device ID and select your dongle in the list (for example a SONOFF Zigbee dongle).
- Click on Add, then restart the VM so it sees the device.
Choosing the dongle by its vendor/device ID, rather than by USB port, means the VM finds it again even if you plug it into another port. You can do the same from the shell of the Proxmox host: find the ID with lsusb, then run qm set <VM ID> -usb0 host=<vendor>:<device>.
In the VM, check that the dongle shows up:
ls /dev/serial/by-id/
Do the same for a USB Bluetooth adapter if you want to use Bluetooth sensors or pair Matter devices over Bluetooth, then install BlueZ in the VM:
sudo apt install -y bluez
With an Ethernet Zigbee coordinator (such as the SMLIGHT SLZB-06), there is nothing to pass through: Gladys reaches it over the network, and you can move the VM to another Proxmox node freely. See Use a network coordinator.
Step 5: Install Gladys with Docker
The VM is now a regular Debian server. Follow the Docker installation guide: install Docker with the official script, then start Gladys with the installation command, unchanged.
Then open http://gladysassistant.local from a computer on the same network. If that name does not open, use the IP address of the VM instead, as shown in its Summary tab: http://VM-IP.
Step 6: Back up the VM
If you use Gladys Plus, it already backs up your Gladys every day, encrypted. On Proxmox you can add a backup of the whole VM: in Datacenter > Backup, schedule a regular backup of the gladys VM. Before a big change, you can also take a snapshot from the Snapshots tab of the VM.
Frequently asked questions
Should I use a VM or an LXC container?
We recommend a VM. Gladys runs in Docker, and Docker inside an LXC container needs a privileged container with nesting enabled. USB devices are also harder to pass to a container, and Matter needs IPv6 to work inside the container as well. Some community members do run Gladys in a privileged "Docker" LXC, and it works, but a VM gives you exactly the same setup as the official installation, for a few hundred MB of RAM more.
How much RAM and disk does the Gladys VM need?
2 CPU cores, 4 GB of RAM and a 32 GB disk are comfortable for a typical home. Gladys itself runs with 2 GB of RAM. Give the VM more disk if you keep a long history for many sensors.
Does Matter work in a Proxmox VM?
Yes. Matter relies on IPv6, so IPv6 must be enabled on your router and in the VM. Debian enables it by default: check that the network interface of the VM (usually ens18, not the lo loopback) has an IPv6 address with ip -6 addr show dev ens18. See the Matter integration for the rest of the setup.
Can I move the Gladys VM to another Proxmox node?
Yes, but a USB device passed through to the VM stays attached to the server it is plugged into: move the dongle with the VM, or use a network Zigbee coordinator, which works from any node. In a cluster whose nodes have different CPU models, also keep the default CPU type of the VM instead of host, otherwise live migration can fail.
Can Gladys monitor my Proxmox server?
Yes. The community Proxmox integration shows the state of your VMs and containers and the result of your backups in Gladys, so you can get notified when a backup fails.