Home Assistant Integration for Unraid®

> ⚠️ Migration Notice: Release 2025.06.11 is the last stable SSH-based version of this integration. Starting with 2025.12.0, this integration has been completely rebuilt to use Unraid's official GraphQL API. There is no direct migration or upgrade path from SSH to GraphQL - you will need to remove the old integration and set up fresh with a new API key. Users who prefer the SSH-based integration can continue using release 2025.06.11.

Installation

HACS (Recommended)

• Home Assistant: 2026.9.0 or later
• Unraid Server: With GraphQL API v4.31.1 or later (install the Unraid Connect plugin to stay up to date)
• Unraid API Key: Generated in Unraid settings

Manual Installation

1. Download this repository as ZIP
2. Extract the custom_components/unraid folder
3. Copy it to your Home Assistant config/custom_components/ directory
4. Restart Home Assistant

Configuration

Step 1: Generate Unraid API Key

1. Log in to your Unraid WebGUI
2. Navigate to Settings → Management Access → API
3. Click Add to create a new API key
4. Copy the generated API key

Step 2: Add the Integration

1. Go to Settings → Devices & Services
2. Click + Add Integration
3. Search for Unraid
4. Enter your configuration:

The integration will validate the connection and create entities for all discovered devices.

Step 3: Configure Options (Optional)

After setup, you can adjust UPS settings (only shown if UPS is detected):

1. Go to Settings → Devices & Services
2. Find the Unraid entry and click Configure
3. Adjust:

Note: Polling intervals are fixed per Home Assistant Core guidelines:

> - System data (CPU, RAM, Docker, VMs): 30 seconds

- Storage data (array, disks, SMART): 5 minutes

> For custom refresh rates, use the homeassistant.update_entity service (see Custom Polling below).

Entity Overview

Sensors

| Entity | Description | Device Class | | --------------- | ------------------- | ------------ | | CPU Usage | CPU utilization % | - | | CPU Temperature | Package temp °C | temperature | | CPU Power | Power consumption W | power | | Memory Usage | RAM used % | - | | Uptime | System uptime | - | | Array State | started/stopped | enum | | Array Usage | Capacity used % | - | | Parity Progress | Check progress % | - | | Disk Usage | Per-disk used % | - | | Share Usage | Per-share used % | - | | Flash Usage | Boot device used % | - | | UPS Battery | Charge level % | battery | | UPS Load | Current load % | - | | UPS Runtime | Estimated runtime | - | | UPS Power | Power consumption W | power | | Notifications | Unread count | - |

Binary Sensors

| Entity | Description | | -------------------- | ----------------------------------- | | Array Started | Array running state | | Parity Check Running | Parity check in progress | | Parity Valid | Parity status healthy | | Disk Health | Per-disk health (problem if not OK) | | UPS Connected | UPS connection status |

Switches

| Entity | Description | | ----------------- | --------------------- | | Docker Containers | Start/stop containers | | Virtual Machines | Start/stop VMs |

Buttons

| Entity | Description | | ----------------------- | ------------------------- | | Array Start/Stop | Control array state | | Parity Check Start/Stop | Control parity operations | | Disk Spin Up/Down | Control disk spin state |

UPS Power Sensor for Energy Dashboard

To track UPS power consumption in Home Assistant's Energy Dashboard:

1. Go to Settings → Devices & Services
2. Find Unraid and click Configure
3. Set UPS capacity (VA) to your UPS rating (e.g., 1000 for a 1000VA UPS)
4. The UPS Power sensor will show calculated wattage based on load percentage

Dynamic Entity Creation

The integration only creates entities for available services:

• No UPS connected → No UPS sensors created
• Docker service stopped → No container switches created
• No VMs defined → No VM switches created
• No shares → No share sensors created

Custom Dashboard Cards

The integration includes a suite of 8 modern custom Lovelace cards bundled directly with zero extra setup needed:

| Card | Tag | Description | | :--- | :--- | :--- | | Server Overview | custom:unraid-server-card | System uptime, OS version, registration badge, CPU/RAM utilization progress rings, motherboard temperatures (Unraid API 4.37.6+), primary network info, live traffic, and boot device. | | Storage & Disks | custom:unraid-storage-card | Storage matrix showing array status, parity sync status and history, capacity progress rings, and individual disk health (temperatures, spin states, and read/write I/O). | | User Shares | custom:unraid-shares-card | User shares with disk usage progress bars, used/free/total capacity, and share protection states (Protected vs. Unprotected). | | Network Interfaces | custom:unraid-network-card | Physical NICs, bonds, and bridges with real-time throughput metrics (rates and totals), link speed badges, active link state chips, MTU, MAC addresses, and clickable WebGUI links. | | Docker Containers | custom:unraid-docker-card | Container manager displaying active containers, status badges, CPU/memory footprints, autostart toggles, and start/stop/restart controls. | | Power & UPS | custom:unraid-ups-card | Power & UPS monitor with battery charge rings, electrical load, AC voltages, estimated runtime, and adaptive status coloring. | | Virtual Machines | custom:unraid-vm-card | Virtual machine manager with state pills, memory allocation, CPU assignments, and lifecycle controls. | | Control Center | custom:unraid-dashboard-card | All-in-one unified dashboard with instant tab switching across all Unraid subsystems. |

Hardware temperature entities require Unraid API 4.37.6 or later and supported sensors. Older or unknown API versions omit temperature queries to preserve disk standby. Temperature entities are discovered during setup; reload the integration after upgrading the server API.

Interactive More-Info Dialogs

Clicking on CPU, RAM, or Storage rings, as well as uptime, network, and battery metrics, automatically opens Home Assistant's native More-Info dialog with historical usage graphs, attributes, and settings.

Dashboard Layout & Native View Tabs (2026+ Best Practice)

For the best experience across mobile and desktop, configure your Unraid dashboard using Home Assistant's Sections view combined with the unified custom:unraid-dashboard-card or dedicated view tabs/subviews.

Entity ID Placeholders: Replace with your server name (e.g., cube, tower) and with your UPS model (e.g., pr1000elcdrt1u). You can check your exact entity IDs under Settings → Devices & Services → Unraid.

views:
  - title: Overview
    path: overview
    icon: mdi:server
    type: sections
    max_columns: 2
    badges:
      - type: entity
        entity: sensor.<your_server>_array_state
        show_name: true
        show_state: true
        color: green
      - type: entity
        entity: sensor.<your_server>_ups_<model>_battery
        show_name: true
        show_state: true
        color: accent
      - type: entity
        entity: sensor.<your_server>_unread_notifications_total
        show_name: true
        show_state: true
        color: red
        visibility:
          - condition: numeric_state
            entity: sensor.<your_server>_unread_notifications_total
            above: 0
    sections:
      - type: grid
        column_span: 2
        cards:
          - type: custom:unraid-dashboard-card
            grid_options:
              columns: full
              rows: auto
# Dedicated views accessible via top tabs or subviews:
  - title: Storage & Disks
    path: storage
    icon: mdi:harddisk
    type: sections
    sections:
      - type: grid
        column_span: 2
        cards:
          - type: custom:unraid-storage-card
          - type: custom:unraid-shares-card
- title: Docker
    path: docker
    icon: mdi:docker
    type: sections
    sections:
      - type: grid
        column_span: 2
        cards:
          - type: custom:unraid-docker-card
- title: VMs
    path: vms
    icon: mdi:monitor
    type: sections
    sections:
      - type: grid
        column_span: 2
        cards:
          - type: custom:unraid-vm-card
- title: Network
    path: network
    icon: mdi:lan-connect
    type: sections
    sections:
      - type: grid
        column_span: 2
        cards:
          - type: custom:unraid-network-card
- title: Power & UPS
    path: ups
    icon: mdi:flash
    type: sections
    sections:
      - type: grid
        column_span: 2
        cards:
          - type: custom:unraid-ups-card

Troubleshooting

Connection Issues

• Verify API Key: Ensure the key is valid and has appropriate permissions
• Network Access: Confirm Home Assistant can reach the Unraid server
• Firewall: Ensure HTTPS port (443) is accessible
• Unraid API Version: Requires GraphQL API v4.31.1+ (install the Unraid Connect plugin to update)

Missing Entities

• Check if the service is running (Docker, VMs, UPS)
• Verify devices exist on the Unraid server
• Check Home Assistant logs for errors

Entities Not Updating

• System sensors update every 30 seconds, storage sensors every 5 minutes
• Use homeassistant.update_entity service to force immediate refresh
• Check Unraid server responsiveness
• View integration diagnostics for coordinator status

Reauthentication

If your API key becomes invalid:

1. A repair notification will appear in Home Assistant
2. Click the notification and follow the steps to enter a new API key
3. Alternatively, go to Settings → Devices & Services, find Unraid, and use the "Reconfigure" option

Removal

To remove the integration:

1. Go to Settings → Devices & Services
2. Find the Unraid entry
3. Click the three-dot menu (⋮) and select Delete
4. Confirm removal

Known Limitations

• GraphQL API Required: This integration requires the Unraid GraphQL API v4.31.1 or later. The API can be updated independently of the Unraid OS version — install the Unraid Connect plugin to keep it updated
• No Network Discovery: Unraid servers must be manually configured (no SSDP/mDNS discovery)
• Disk SMART Data: SMART queries can be slow on large arrays; storage polling is less frequent to compensate
• Container/VM Actions: Start/stop operations may take up to 60 seconds to complete
• SSL Certificates: Self-signed certificates require enabling "Allow insecure connections" (or configuring custom CA)

Custom Polling Intervals

Polling intervals are fixed per Home Assistant Core integration guidelines. If you need more frequent updates for specific sensors (e.g., disk temperatures for fan control), use the homeassistant.update_entity service with a time-pattern automation:

automation:
  - alias: "Update disk temperatures every 60 seconds"
    trigger:
      - trigger: time_pattern
        seconds: "/60"
    action:
      - action: homeassistant.update_entity
        target:
          entity_id:
            - sensor.unraid_tower_disk1_temperature
            - sensor.unraid_tower_disk2_temperature
            # Add all disk temperature sensors you need

This allows custom refresh rates while keeping the integration compliant with HA Core standards.

Automation Examples

Alert on Parity Check Errors

automation:
  - alias: "Unraid Parity Check Error Alert"
    trigger:
      - platform: state
        entity_id: binary_sensor.unraid_tower_parity_valid
        to: "off"
    action:
      - service: notify.mobile_app
        data:
          title: "⚠️ Unraid Parity Error"
          message: "Parity check has detected errors on your Unraid server."

Notify When Array Stops

automation:
  - alias: "Unraid Array Stopped"
    trigger:
      - platform: state
        entity_id: binary_sensor.unraid_tower_array_started
        to: "off"
    action:
      - service: notify.mobile_app
        data:
          title: "Unraid Array"
          message: "The Unraid array has stopped."

Start Container on Schedule

automation:
  - alias: "Start Plex at 6PM"
    trigger:
      - platform: time
        at: "18:00:00"
    action:
      - service: switch.turn_on
        target:
          entity_id: switch.unraid_tower_plex

Development

Prerequisites

• Docker Desktop
• VS Code with Dev Containers extension

Setup

git clone https://github.com/tinkerologie/ha-unraid.git
cd ha-unraid
code .
Reopen in Dev Container when prompted

Commands

./script/setup    # Install dependencies
./script/lint     # Format and lint (run after every change!)
pytest             # Run tests
./script/develop  # Start Home Assistant for testing

Code Quality

This project enforces strict code quality:

• All changes must pass ./script/lint with zero warnings
• All tests must pass before committing
• Type hints required for all functions

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make changes and run ./script/lint
4. Run tests with pytest
5. Keep PRs small and focused - one issue/feature per PR
6. Submit a pull request

License

Licensed under the Apache License 2.0 - see LICENSE for details.

Disclaimer

Unraid® is a registered trademark of Lime Technology, Inc. This integration is not affiliated with, endorsed, or sponsored by Lime Technology, Inc.