Install Homebridge on Virtual Machine
This guide provides step-by-step instructions for installing Homebridge as a Virtual Machine. We provide Virtual Machine Appliances and Virtual Disks for both x86 and ARM architecture hosts. The Virtual Machine is a preconfigured implementation of Homebridge running on a Debian-based system.
Recommended for: Non-Linux systems where Docker or native installation cannot be used, such as Windows or macOS hosts.
The virtual disk is created using a similar process to the Homebridge Raspbian image. It leverages Debian as the operating system, with Node.js, Homebridge, and the Homebridge UI pre-installed and configured.
- Homebridge Virtual Machine Installation Guide
Appliance images are ready-to-import virtual machines with all settings preconfigured.
| Format | Description | Best For |
|---|---|---|
| OVA | Open Virtual Appliance | VirtualBox |
| UTM | UTM Appliance | UTM on macOS |
| HYPERV | Microsoft Hyper-V Virtual Machine | Windows 10/11 Enterprise, Pro, or Education (Hyper-V) |
Windows Users: Hyper-V is only available on Windows 10/11 Enterprise, Pro, or Education editions. Windows Home Edition does not support Hyper-V. Home Edition users should use VirtualBox instead.
Virtual disk images require manual VM creation but offer more flexibility.
| Format | Description | Best For |
|---|---|---|
| QCOW2 | QEMU Copy-On-Write disk image | QEMU/KVM environments |
| VDI | Virtual Disk Image | VirtualBox (alternative format) |
| VHDX | Virtual Hard Disk | Microsoft Hyper-V |
| VMDK | Virtual Machine Disk | VMware products, ESXi |
Choose the architecture that matches your host machine's processor:
| Architecture | Description | Example Hardware |
|---|---|---|
| amd64 | 64-bit Intel/AMD processors | Most Windows PCs, Intel Macs |
| arm64 | 64-bit ARM processors | Apple Silicon Macs (M1/M2/M3), ARM servers |
Important: You must select the image matching your host CPU architecture. An amd64 image will not work on ARM hardware and vice versa.
All Homebridge VM images include the following:
- Operating System: Debian 12 ("Bookworm") Lite
- CPU Architectures: x86-64 (Intel/AMD) and ARM64 (including Apple Silicon)
-
Virtual Disk Size:
- VHDX and VMDK: 5GB allocated
- QCOW2 and VDI: 50GB allocated (dynamically expanded)
-
Pre-installed Packages: Node.js, Homebridge, Homebridge UI, and FFmpeg
- Exact versions are listed in the manifest file included with each release
- Guest Additions: UTM and Hyper-V kernel modules pre-installed
Note: The legacy build documentation is available here.
Homebridge VM images are available in three release streams to suit different needs:
| Stream | Node.js* | Homebridge | UI | FFmpeg | Recommended For |
|---|---|---|---|---|---|
| Stable/Latest | LTS | Latest | Latest | Latest | Production use - most stable |
| Beta | Current | Beta V2 | Beta | Latest | Testing new features |
| Alpha | Current | Alpha | Alpha | Latest | Experimental - developers only |
All virtual disk and appliance images are packaged in a GitHub releases:
- Stable/Latest: Latest Release
- Beta/Alpha: Select the appropriate tag from All Releases
The Hyper-V appliance provides the fastest setup for Windows users.
Requirements: Windows 10/11 Enterprise, Pro, or Education (64-bit). Windows Home Edition does not support Hyper-V - use VirtualBox instead.
-
Download the latest Hyper-V appliance image (HYPERV) for your CPU architecture
-
Extract the downloaded archive
- Open Hyper-V Manager
- Select Action → Import Virtual Machine
- Browse to the extracted appliance folder
- Complete the import wizard
Pre-configured Settings:
- Generation 2 VM
- 4096MB memory (Dynamic Memory disabled)
- Network: Default Switch
- Security: Secure Boot disabled
- Start your VM from Hyper-V Manager
- Follow the First Boot Setup instructions below
- Connect to the Homebridge UI at the address shown in the console (e.g.,
http://192.168.1.100:8581)
The OVA appliance provides the simplest setup for VirtualBox users.
Download the OVA appliance for your CPU architecture:
- Open VirtualBox
- Select File → Import Appliance
- Browse to the downloaded OVA file
- Review the settings and click Import
- Wait for the import process to complete
- Select your imported VM
- Click Settings → Network
- Change "Attached to" from NAT to Bridged Adapter
- Select your active network interface
- Click OK
- Start your VM
- Follow the First Boot Setup instructions below
- Connect to the Homebridge UI at the address shown in the console (e.g.,
http://192.168.1.100:8581)
The UTM appliance is optimized for macOS users, especially those with Apple Silicon.
Download the UTM appliance for your CPU architecture:
- Extract the downloaded UTM archive
- Store the extracted .utm file in a permanent location
- Open UTM
- Click the + button to create a new VM
- Select Open Existing
- Browse to the extracted .utm file
- Start your VM from UTM
- Follow the First Boot Setup instructions below
- Connect to the Homebridge UI at the address shown in the console (e.g.,
http://192.168.1.100:8581)
Virtual disk images provide maximum flexibility and work with most virtualization platforms.
- Navigate to the appropriate release (Stable, Beta, or Alpha)
- Download the virtual disk image matching:
- Your host CPU architecture (amd64 or arm64)
- Your virtualization platform (QCOW2, VDI, VHDX, or VMDK)
- Extract the downloaded file if compressed (.gz)
- Open your virtualization software (Hyper-V, VirtualBox, Parallels Desktop, ESXi, etc.)
- Create a new virtual machine with these settings:
Basic Settings:
- Operating System: Linux → Debian → Debian 12 (64-bit) or Debian 12 (ARM 64-bit)
- Hyper-V Users: Select "Generation 1 VM"
Hardware Requirements:
- RAM: 4GB minimum (recommended: 8GB)
- CPU: 1 core minimum (recommended: 2+ cores)
-
Network Adapter:
- VirtualBox/Parallels: Bridged Adapter
- Hyper-V: External Switch
- UTM: Network Mode: Bridged
- Others: The virtual machine needs to use a bridged network interface.
Disk Configuration:
- Select "Use an existing virtual hard disk"
- Browse to the extracted virtual disk image file
- Important: Store the disk image in a permanent location - it must remain accessible to the VM
- Complete the VM creation wizard
- Start your VM
- Follow the First Boot Setup instructions below
- Connect to the Homebridge UI at the address shown in the console (e.g.,
http://192.168.1.100:8581)
When you first start your Homebridge VM, you'll need to create a local user account.
- The VM will display a setup wizard in the console window
- Enter a username (lowercase letters, no spaces)
- Create a strong password
- Confirm your password
-
Save these credentials securely - you'll need them to:
- Log into the VM console
- SSH into the VM for maintenance
- Perform system updates
- The VM will complete its initial configuration
- Network settings will be applied
- The Homebridge UI will start automatically
- The console will display the web interface URL
- On UTM and VirtualBox, the virtual hard disk will automatically expand to 50GB
Troubleshooting: If the first boot setup screen doesn't appear or you accidentally cancel it, simply restart the VM to display it again.
Virtual Machine Image Configuration Tools
For detailed configuration options, system management, and troubleshooting, please refer to the Debian/Ubuntu Configuration Reference.
This includes information on:
- Updating Homebridge and Node.js
- Managing the Homebridge service
- Configuring automatic backups
- Troubleshooting common issues
- Security best practices
If you encounter issues or have questions:
- Check the Homebridge Wiki
- Search existing GitHub Issues
- Join the Homebridge Discord #hb-vm-image community
- Create a new issue with detailed information about your problem