claude-home/.claude/plans/home-assistant-deployment-guide.md

# Home Assistant Deployment Guide

**Last Updated:** January 9, 2026
**Deployment Method:** Home Assistant OS (HAOS) VM on Proxmox
**Status:** ✅ Deployed and Operational

## Current Deployment

| Setting | Value |
|---------|-------|
| **VM ID** | 109 |
| **VM Name** | homeassistant |
| **Primary IP** | 10.0.0.28 (home network - for Matter/IoT) |
| **Secondary IP** | 10.10.0.215 (server network - management) |
| **Web UI** | http://10.0.0.28:8123 |
| **USB Device** | Nabu Casa ZBT-2 (Thread/Zigbee coordinator) |

## Deployment Overview

### Why HAOS VM (Not Container)?

| Factor | HAOS VM | Container (HA Core) |
|--------|---------|---------------------|
| **Add-on Marketplace** | ✅ Full access | ❌ Not available |
| **Supervisor** | ✅ Included | ❌ Not included |
| **USB Passthrough** | ✅ Reliable | ⚠️ Problematic |
| **Official Support** | ✅ Yes | ⚠️ Limited |
| **Backup/Restore** | ✅ Built-in | Manual |
| **Updates** | ✅ One-click | Manual |

The Add-on marketplace provides one-click installation of:
- **Mosquitto** (MQTT broker)
- **Node-RED** (visual automation)
- **Zigbee2MQTT** / **ZHA** (Zigbee coordination)
- **ESPHome** (DIY sensors)
- **Piper** / **Whisper** (local voice)
- **File Editor**, **Terminal**, **Samba**, and 1000+ more

---

## Pre-Deployment: Decommission Old HA VM

An old, unmaintained Home Assistant VM exists and should be removed before deploying the new instance.

### Decommissioning Steps

1. **Identify the old VM** in Proxmox web UI
   ```bash
   # List all VMs to find the old HA instance
   qm list | grep -i home
   ```

2. **Check if it has any valuable config** (likely not if never fully implemented)
   ```bash
   # If VM is running, you could backup config first
   # But if it was never completed, skip this
   ```

3. **Stop and remove the old VM**
   ```bash
   # Stop the VM (replace VMID with actual ID)
   qm stop <VMID>

   # Remove the VM and its disks
   qm destroy <VMID> --purge
   ```

4. **Free up resources** - Note the resources being reclaimed for the new VM

---

## VM Specifications

### Recommended Configuration

| Resource | Value | Rationale |
|----------|-------|-----------|
| **CPU** | 4 cores | Headroom for add-ons and integrations |
| **RAM** | 8 GB | Comfortable for MQTT, Node-RED, history |
| **Disk** | 64 GB | Add-ons, recorder database, backups |
| **Network** | Bridge (vmbr0) | Same network as IoT devices |
| **Machine Type** | q35 | Modern, better device support |
| **BIOS** | OVMF (UEFI) | Required for HAOS |

### Network Considerations

- Place on same VLAN/subnet as IoT devices for discovery
- Static IP recommended (or DHCP reservation)
- Suggested IP: Document in your network scheme
- Ports: 8123 (web UI), 1883 (MQTT if using add-on)

---

## Installation

### Method: Community Helper Script (Recommended)

The community-maintained scripts (originally by tteck) automate the entire process:

```bash
# Run from Proxmox shell
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/vm/haos-vm.sh)"
```

### Script Prompts

When prompted, select **Advanced** to customize specs:

| Prompt | Recommended Value |
|--------|-------------------|
| Use default settings? | No (select Advanced) |
| HAOS Version | Latest (default) |
| VM ID | Next available or choose |
| Machine Type | q35 |
| Disk Size | 64G |
| CPU Cores | 4 |
| RAM | 8192 |
| Bridge | vmbr0 (or your IoT bridge) |
| MAC Address | Auto or specify |
| VLAN | Your IoT VLAN if applicable |
| Start after creation | Yes |

### Post-Installation

1. **Wait for HAOS to boot** (2-3 minutes first boot)
2. **Access web UI** at `http://<VM-IP>:8123`
3. **Create admin account**
4. **Complete onboarding wizard**

---

## Initial Configuration

### Step 1: Onboarding

1. Set location (for sun-based automations, weather)
2. Create admin user account
3. Skip or configure any auto-discovered devices
4. Install HA mobile app for presence detection

### Step 2: Essential Add-ons

Navigate to **Settings → Add-ons → Add-on Store**

| Add-on | Purpose | Priority |
|--------|---------|----------|
| **File Editor** | Edit YAML configs in browser | Install first |
| **Terminal & SSH** | Shell access | Install first |
| **Samba Share** | Access config from desktop | Recommended |
| **Mosquitto** | MQTT broker for devices | When needed |
| **HACS** | Community integrations | Recommended |

### Step 3: Philips Hue Integration

1. Go to **Settings → Devices & Services**
2. Hue Bridge should auto-discover
3. Click **Configure** → Press button on Hue Bridge
4. All Hue devices appear immediately
5. Full local control established

### Step 4: Matter/Thread Setup

For Eve and other Matter devices:

1. Go to **Settings → Devices & Services → Add Integration**
2. Search for **Matter**
3. Follow pairing instructions for each device
4. Use existing Thread network (Apple TV/HomePod as border routers)

---

## USB Passthrough: Nabu Casa ZBT-2

The ZBT-2 is a Thread/Zigbee coordinator that provides:
- **Thread Border Router** functionality (for Matter over Thread devices)
- **Zigbee coordinator** capability (for ZHA integration)

### Current Configuration

```bash
# USB device info
Bus 002 Device 003: ID 303a:831a Nabu Casa ZBT-2

# VM config line
usb0: host=303a:831a
```

### Setup Steps

1. **Plug ZBT-2 into Proxmox host** (USB 2.0 port preferred to avoid USB 3.0 interference)

2. **Identify device:**
   ```bash
   ssh proxmox "lsusb | grep -i nabu"
   # Expected: 303a:831a Nabu Casa ZBT-2
   ```

3. **Stop VM and add USB passthrough:**
   ```bash
   qm stop 109
   qm set 109 -usb0 host=303a:831a
   qm start 109
   ```

4. **Verify in HA:** Settings → System → Hardware
   - Should show `/dev/ttyACM0` or similar
   - Full path: `/dev/serial/by-id/usb-Nabu_Casa_ZBT-2_<SERIAL>-if00`

### Flash Thread Firmware

If the ZBT-2 needs Thread firmware:
1. Settings → System → Hardware → Find ZBT-2
2. Click three dots → Configure → Flash Thread firmware
3. Wait for flash to complete
4. Restart OpenThread Border Router addon

---

## CRITICAL: Network Configuration for Matter

**Matter devices REQUIRE Home Assistant to be on the same subnet as the IoT devices.** This is the most common cause of Matter commissioning failures.

### The Problem

If HA is on a server VLAN (10.10.0.x) but IoT devices are on the home network (10.0.0.x):
- mDNS discovery fails across subnets
- Matter commissioning times out with "Discovery timed out" errors
- PASE session establishment fails

### The Solution: Dual-NIC Configuration

VM 109 has two network interfaces:

| Interface | Bridge | Network | Purpose |
|-----------|--------|---------|---------|
| net0 (enp6s18) | vmbr1 | 10.0.0.x (Home) | **Primary** - Matter/IoT communication |
| net1 (enp6s19) | vmbr0 | 10.10.0.x (Server) | Secondary - Management access |

### Proxmox VM Network Config

```bash
# Current configuration (qm config 109 | grep net)
net0: virtio=0E:E0:41:39:CC:95,bridge=vmbr1
net1: virtio=6E:16:AB:69:63:89,bridge=vmbr0
```

### Why This Matters

- **net0 on vmbr1 (home network)**: Matter Server auto-selects the first interface. By putting the home network on net0, Matter commissioning works.
- **net1 on vmbr0 (server network)**: Provides management access from the server VLAN.

### HAOS Network Settings

| Interface | IP | Gateway | Purpose |
|-----------|-----|---------|---------|
| enp6s18 | 10.0.0.28 (DHCP) | 10.0.0.1 | Matter/mDNS/IoT |
| enp6s19 | 10.10.0.215 (DHCP) | 10.10.0.1 | Server management |

**Important:** Set a DHCP reservation for 10.0.0.28 in your router to prevent IP changes.

### Unifi mDNS Configuration

If you have VLANs, enable mDNS reflection:
1. Unifi Controller → Settings → Services
2. **Gateway mDNS Proxy**: Custom
3. **VLAN Scope**: Select all VLANs that need mDNS (Home Network, Servers)
4. **Service Scope**: All

---

## Thread Network Configuration

### Network Topology

```
┌─────────────────────────────────────────────────────────────┐
│                     Home Assistant VM                        │
│                  (10.0.0.28 on home network)                │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐    ┌─────────────────────────────────┐ │
│  │  Matter Server  │    │  OpenThread Border Router       │ │
│  │  (addon)        │    │  (ZBT-2 @ /dev/ttyACM0)         │ │
│  └────────┬────────┘    └────────────┬────────────────────┘ │
└───────────┼──────────────────────────┼──────────────────────┘
            │                          │
            │ IPv6/mDNS                │ 802.15.4 Radio
            │                          │
            ▼                          ▼
    ┌───────────────┐          ┌───────────────┐
    │ Apple Thread  │◄────────►│   Thread      │
    │ Border Routers│  Thread  │   Devices     │
    │ (8x HomePods) │  Mesh    │  (Eve, etc.)  │
    └───────────────┘          └───────────────┘
```

### Thread Networks

Two Thread networks exist in this environment:

| Network | PAN ID | Channel | Border Routers |
|---------|--------|---------|----------------|
| MyHome (Apple) | 0xF672 | 25 | 8 (HomePods/Apple TVs) |
| ha-thread-b072 | 0xB072 | 25 | 1 (ZBT-2) |

**Current setup:** Apple network is set as "Preferred" in HA → Settings → Thread. This means:
- HA uses Apple's Thread credentials for commissioning
- Devices join Apple's strong mesh (8 border routers)
- HA can still control devices via Matter

### OTBR Addon Configuration

Settings → Add-ons → OpenThread Border Router:
- **Device**: `/dev/serial/by-id/usb-Nabu_Casa_ZBT-2_DCB4D90E794C-if00`
- **Baudrate**: 460800
- **Hardware flow control**: Enabled
- **NAT64**: Enabled
- **OTBR firewall**: Enabled

### OTBR REST API

Accessible at `http://10.0.0.28:8081/`:
- `/node/state` - Current state (leader, router, etc.)
- `/node/dataset/active` - Active Thread dataset
- `/diagnostics` - Network diagnostics

---

## Matter Commissioning

### Prerequisites

1. HA on same subnet as IoT devices (10.0.0.x)
2. Matter Server addon running
3. OpenThread Border Router addon running
4. Thread network configured (Apple or HA)
5. HA Companion app on phone with Bluetooth permission

### Commissioning Steps

1. **Factory reset the device** (hold button 10+ seconds)
2. Open **HA Companion app** on phone
3. Go to **Settings → Devices & Services → Add Integration → Matter**
4. Scan the Matter QR code on the device
5. Phone uses Bluetooth for initial PASE session
6. Device receives Thread credentials and joins network
7. Device appears in HA

### Adding HA as Secondary Controller

If device is already in Apple Home:
1. In Apple Home app, find device → Settings
2. Look for **"Turn On Pairing Mode"**
3. In HA Companion app → Add Matter Device
4. Enter the temporary pairing code
5. Device now controlled by both Apple Home and HA

---

## Backup Strategy

### Built-in Backups

HAOS includes automated backup to:
- Local storage
- Network shares (Samba/NFS)
- Google Drive (via add-on)

### Recommended Schedule

```yaml
# Example: Weekly full backup
# Settings → System → Backups → Create Backup
```

### Proxmox-Level Backup

Additionally, back up the entire VM via Proxmox:
```bash
# Manual backup
vzdump <VMID> --storage local --mode snapshot

# Or configure in Proxmox Backup Server
```

---

## Migration Strategy

### Phase 1: Foundation (Week 1)

1. ✅ Decommission old HA VM
2. ✅ Deploy new HAOS VM with recommended specs
3. Connect Philips Hue Bridge (native integration)
4. Test Hue control from HA
5. Install essential add-ons

### Phase 2: Parallel Operation (Weeks 2-3)

1. Re-pair 2-3 Matter devices (Eve switches) to HA
2. Keep Apple Home running for remaining devices
3. Build basic automations in HA
4. Test reliability and family usability
5. Install HA mobile app for all household members

### Phase 3: Full Migration (Weeks 4-5)

1. Re-pair remaining Matter devices to HA
2. Migrate all automations from Apple Home
3. Optional: Set up HomeKit Controller integration
   - Exposes HA devices back to Apple Home
   - Maintains Siri voice control for family
4. Decommission Apple Home as primary controller

### Phase 4: Enhancement (Ongoing)

1. Add HACS for community integrations
2. Build advanced automations
3. Consider voice integration (Whisper/Piper add-ons)
4. Evaluate Zigbee coordinator if expanding beyond Matter

---

## Device Integration Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     Home Assistant VM                        │
│                      (HAOS on Proxmox)                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ Hue Native  │  │   Matter    │  │  Future: Zigbee     │  │
│  │ Integration │  │ Integration │  │  (ZBT-2 + Z2M)      │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
│         │                │                     │             │
└─────────┼────────────────┼─────────────────────┼─────────────┘
          │                │                     │
          ▼                ▼                     ▼
   ┌──────────────┐  ┌───────────┐        ┌───────────┐
   │  Hue Bridge  │  │  Thread   │        │  USB      │
   │   (Zigbee)   │  │  Border   │        │  Coord.   │
   └──────┬───────┘  │  Router   │        └─────┬─────┘
          │          │(Apple TV) │              │
          ▼          └─────┬─────┘              ▼
   ┌──────────────┐        │             ┌───────────┐
   │  Hue Bulbs   │        ▼             │  Zigbee   │
   │  Hue Sensors │  ┌───────────┐       │  Devices  │
   └──────────────┘  │Eve, etc.  │       └───────────┘
                     │(Matter/   │
                     │ Thread)   │
                     └───────────┘
```

---

## Automation Examples

### Complex Scheduling

```yaml
# Advanced morning routine with conditions
automation:
  - alias: "Smart Morning Routine"
    trigger:
      - platform: time
        at: "06:30:00"
    condition:
      - condition: state
        entity_id: binary_sensor.workday
        state: 'on'
      - condition: state
        entity_id: person.cal
        state: 'home'
    action:
      - service: light.turn_on
        target:
          entity_id: light.bedroom
        data:
          brightness_pct: 30
          color_temp: 400
      - delay: "00:15:00"
      - service: light.turn_on
        target:
          entity_id: light.bedroom
        data:
          brightness_pct: 80
```

### Presence-Based Automation

```yaml
# Welcome home scene
automation:
  - alias: "Arrival Detection"
    trigger:
      - platform: state
        entity_id: person.cal
        to: 'home'
    condition:
      - condition: sun
        after: sunset
    action:
      - service: light.turn_on
        target:
          entity_id: light.living_room
        data:
          brightness_pct: 80
      - service: notify.mobile_app
        data:
          message: "Welcome home!"
```

---

## Troubleshooting

### VM Won't Start

```bash
# Check VM status
qm status 109

# Check for errors
journalctl -u pve-guests | grep 109

# Verify UEFI boot
qm config 109 | grep bios
```

### Can't Access Web UI

1. Check VM console in Proxmox for IP address
2. Verify network bridge configuration
3. Ensure firewall allows port 8123
4. Wait 5 minutes on first boot for full initialization
5. Try both IPs: http://10.0.0.28:8123 and http://10.10.0.215:8123

### Hue Bridge Not Discovered

1. Verify same subnet as HA VM
2. Check mDNS/Avahi is working
3. Manually add: Settings → Integrations → Add → Philips Hue
4. Enter bridge IP manually if needed

### Matter Commissioning Fails

**Symptom:** "Pairing Failed" or endless spinning in Companion app

**Check Matter Server logs** (Settings → Add-ons → Matter Server → Logs):

| Error | Cause | Solution |
|-------|-------|----------|
| `Discovery timed out` | HA can't find device on network | Verify same subnet |
| `PASESession timed out` | Can't establish secure session | Check Bluetooth permissions on phone |
| `Thread credentials don't match` | Wrong Thread network | Set correct preferred network in HA |
| `Msg Retransmission failure` | Network communication issue | Check mDNS reflection, firewall |

**Most common fix:** Ensure HA is on the same subnet as IoT devices (see Network Configuration section).

### Thread/OTBR Issues

**Check OTBR status:**
```bash
curl -s http://10.0.0.28:8081/node/state
# Should return: "leader" or "router"
```

**Check Thread diagnostics:**
```bash
curl -s http://10.0.0.28:8081/diagnostics | jq '.[] | {ActiveRouters, ChildTable, IfInUcastPkts}'
```

**Common issues:**

| Symptom | Cause | Solution |
|---------|-------|----------|
| `NoAck` errors in OTBR logs | Radio can't communicate | Check USB passthrough, restart OTBR |
| `IfInUcastPkts: 0` | Not receiving any traffic | Verify channel matches other devices |
| Empty `ChildTable` | No devices joined | Device joining different network |
| Commissioner disabled | Matter not enabling it | Restart Matter Server |

### ZBT-2 Radio Issues

**Verify USB passthrough:**
```bash
ssh proxmox "lsusb | grep 303a"
# Should show: 303a:831a Nabu Casa ZBT-2
```

**Check if device visible in HA:**
- Settings → System → Hardware → Search "usb"
- Should show `/dev/ttyACM0`

**Flash firmware if needed:**
- Settings → System → Hardware → ZBT-2 → Configure → Flash

### Network Interface Issues

**Matter Server using wrong interface:**

Check logs for: `Using 'enp6s18' as primary network interface`

If using wrong interface:
1. The primary interface (net0) must be on the IoT network
2. Swap interfaces in Proxmox if needed:
   ```bash
   ssh proxmox "qm set 109 -net0 virtio=<MAC>,bridge=vmbr1"
   ssh proxmox "qm set 109 -net1 virtio=<MAC>,bridge=vmbr0"
   ssh proxmox "qm reboot 109"
   ```
3. Reconfigure IPs in HAOS after reboot

---

## Resources

- [Home Assistant Documentation](https://www.home-assistant.io/docs/)
- [Community Scripts - HAOS VM](https://community-scripts.github.io/ProxmoxVE/scripts?id=haos-vm)
- [Home Assistant Community Forums](https://community.home-assistant.io/)
- [HACS - Community Store](https://hacs.xyz/)

---

## Checklist

### Pre-Deployment
- [x] Identify and document old HA VM ID
- [x] Plan IP address for new VM
- [x] Verify Proxmox storage has 64GB+ free

### Deployment
- [x] Decommission old HA VM
- [x] Run community helper script
- [x] Configure with recommended specs (4 cores, 8GB, 64GB)
- [x] Complete onboarding wizard

### Post-Deployment
- [x] Install File Editor and Terminal add-ons
- [ ] Connect Philips Hue Bridge
- [ ] Test light control from HA
- [x] Install HA mobile app
- [ ] Set up first automation

### USB Passthrough (ZBT-2)
- [x] Plug ZBT-2 into Proxmox host
- [x] Add USB passthrough to VM (303a:831a)
- [x] Verify device visible in HA
- [x] Flash Thread firmware
- [x] Configure OpenThread Border Router addon

### Network Configuration
- [x] Add second NIC to VM (net1 on vmbr0)
- [x] Swap interfaces (net0 on home network vmbr1)
- [x] Configure IPs in HAOS
- [ ] Set DHCP reservation for 10.0.0.28
- [x] Enable mDNS reflection in Unifi

### Matter/Thread Setup
- [x] Install Matter Server addon
- [x] Install OpenThread Border Router addon
- [x] Set Apple network as preferred Thread network
- [x] Commission first Matter device (Eve outlet)
- [ ] Commission remaining Matter devices

---

## Lessons Learned

1. **Matter requires same-subnet connectivity** - The biggest blocker was HA being on a different subnet than IoT devices. mDNS doesn't cross subnets without explicit reflection.

2. **Matter Server selects the first network interface** - No configuration option exists to change this. The solution is to ensure net0 is on the correct network at the Proxmox level.

3. **Thread channel matters** - If HA's Thread network is on a different channel than existing devices, they can't communicate. Match channels or use the existing network's credentials.

4. **Apple Thread network is robust** - With 8 HomePods/Apple TVs as border routers, the Apple Thread mesh is strong. Using it as the preferred network is practical.

5. **ZBT-2 USB passthrough works reliably** - Using vendor:product ID (303a:831a) passthrough is reliable and survives USB port changes.

---
*Last updated: January 9, 2026*