Home Assistant Integration for Unraid®

A Home Assistant custom integration for monitoring and controlling Unraid servers via the official GraphQL API.

Note: This integration requires the Unraid GraphQL API v4.31.1 or later. The API can be updated independently of the Unraid OS version by installing the Unraid Connect plugin from the Unraid Community Applications store.

Important: If you encounter issues, ensure you have the latest version of the Unraid GraphQL API installed via the Unraid Connect plugin. Many reported issues are resolved simply by updating to the latest API version.

⚠️ 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)

1. Click the button above or manually add the repository in HACS
2. Search for Unraid and click Download
3. Restart Home Assistant

Alternative

I encourage users to check out Unraid Management Agent integration, which provides an alternative solution for integrating Unraid with Home Assistant.

Features

System Monitoring

• CPU Usage: Real-time CPU utilization percentage
• CPU Temperature: Package temperature monitoring
• CPU Power: Power consumption (when available)
• Memory Usage: Used memory and percentage utilization
• System Uptime: Human-readable uptime display

Storage Management

• Array Status: State tracking (started/stopped/degraded)
• Array Capacity: Total, used, free space with usage percentage
• Parity Status: Parity check status, progress, and validation
• Disk Health: Per-disk health monitoring (binary sensors)
• Disk Usage: Individual disk capacity and usage for data and cache disks
• Share Usage: Per-share storage utilization
• Flash Device: Boot device usage monitoring

Docker Container Control

• Container Switches: Start/stop Docker containers
• State Sync: Real-time container state updates
• Attributes: Container image, status, and port information

Virtual Machine Control

• VM Switches: Start/stop virtual machines
• State Sync: Real-time VM state updates
• Attributes: VM name and state information

UPS Monitoring (when connected)

• Battery Level: Charge percentage
• Load: Current UPS load percentage
• Runtime: Estimated battery runtime
• Power Consumption: Calculated power usage for Energy Dashboard (requires configuration)
• Connection Status: UPS connected binary sensor

Notifications

• Active Notifications: Count of unread Unraid notifications

Requirements

• Home Assistant: 2025.12.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:
   • Host: Unraid server IP or hostname
   • API Key: The key from Step 1

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:
   • UPS capacity (VA): Your UPS VA rating for reference
   • UPS nominal power (W): Required for UPS Power sensor in Energy Dashboard

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

Binary Sensors

Switches

Buttons

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

Formula: Power (W) = Load% × Capacity (VA) × 0.6 (power factor)

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

Entities are automatically created when services become available.

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

If you installed via HACS, you can also uninstall from HACS after removing the integration.

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/ruaan-deysel/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

See CONTRIBUTING.md for detailed guidelines.

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.