Installation guide

Get HomeHQ running

Choose your platform below. Most installs are complete within 10 minutes.

⬇ Download homehq-arm64.img.gz (~970 MB)
1

Download the image

Download homehq-arm64.img.gz above. This is a compressed disk image — about 970 MB. Don't decompress it manually; Etcher handles that.

2

Flash to your SD card or USB

Install Balena Etcher, select the .img.gz file, select your SD card (16 GB minimum, Class 10 or faster), and click Flash. Takes 3–5 minutes.

💡 Alternatively, use the Raspberry Pi Imager — select "Use custom image" and pick the .img.gz file.
3

Optional: pre-configure WiFi

For a headless setup, create a wpa_supplicant.conf in the boot partition before inserting the card:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=GB
network={
    ssid="YourNetwork"
    psk="YourPassword"
}

If you're using ethernet, skip this step entirely.

4

Insert card and power on

Insert the SD card into your Pi. Connect HDMI to your TV. Connect ethernet or ensure WiFi is configured. Power on.

First boot expands the filesystem to fill the card automatically. This takes about 60 seconds. Then HomeHQ starts.

5

Scan the QR code

Within 90 seconds, the TV display shows a QR code and URL (e.g. http://homehq.local). Scan it with your phone to open the setup wizard.

💡 If your TV shows a black screen for more than 2 minutes, check that HDMI is connected before power-on, or add hdmi_force_hotplug=1 to /boot/firmware/config.txt.
6

Complete the setup wizard

The wizard walks you through four steps:

1. Household name — e.g. "The Smiths"
2. Your profile — name, a 4-digit PIN, colour
3. Family members — add everyone, or skip and add later
4. AI features — optional Anthropic API key for meal planning and smart suggestions

The TV dashboard activates automatically when you finish. Done.

⬇ Download homehq-x86_64.img.gz (~1.3 GB)
1

Download and flash to USB

Download homehq-x86_64.img.gz above. Flash it to a USB stick (8 GB minimum) with Balena Etcher. Select the file, select the USB drive, click Flash.

⚠️ This image requires UEFI/EFI boot. Legacy BIOS boot is not supported. All PCs made after ~2012 support UEFI.
2

Boot from USB

Insert the USB into your PC or NUC. Enter the boot menu (usually F12, F8, or DEL at startup) and select your USB drive. The machine boots directly into HomeHQ — no installer, no prompts.

First boot takes 60–90 seconds to start the server. The TV then shows the setup QR code.

3

Scan and set up

Scan the QR code with your phone and complete the 4-step wizard. Same process as Raspberry Pi above.

💡 The x86 image automatically expands its root partition to fill the USB drive on first boot, so a larger drive gives you more room for backups and data.
1

Requirements

Any Debian 12 or Ubuntu 22.04+ machine with Node.js 20+, Nginx, and Git. Works on x86-64, arm64, or armhf.

2

Run the install script

curl -fsSL https://homehq.cloud/install.sh | sudo bash

Or clone manually and run:

git clone https://github.com/ArchiveHunter/HomeHQ.git /opt/homehq
sudo bash /opt/homehq/setup/install.sh

The script installs Node, Nginx, PM2, clones the repo, configures systemd services, and sets up autologin for the kiosk.

3

Access on your network

Once running, HomeHQ is available at http://<your-ip> or http://homehq.local if mDNS is working. Navigate there on any phone to start setup.