Unraid® Management Agent - Home Assistant Integration

Complete Home Assistant custom integration for monitoring and controlling Unraid servers via the Unraid Management Agent.

Features

🔍 Comprehensive Monitoring

• System Metrics: CPU usage, RAM usage, CPU temperature, uptime
• Array Status: Array state, disk usage, parity check progress
• ZFS Storage: Pool capacity, health, fragmentation, ARC cache statistics
• GPU Metrics: GPU utilization, temperature, power consumption (Intel/NVIDIA/AMD)
• Network: Interface status, bandwidth monitoring (RX/TX)
• UPS: Battery level, load, runtime estimation
• Containers: Docker container status and metrics
• Virtual Machines: VM status and resource allocation

🎮 Full Control

• Docker Containers: Start, stop, restart containers via switches
• Virtual Machines: Start, stop, restart VMs via switches
• Array Management: Start/stop array with buttons
• Parity Checks: Start/stop parity checks with buttons

⚡ Real-Time Updates

• WebSocket Support: Instant state updates (<1s latency)
• Automatic Fallback: Falls back to REST API polling if WebSocket fails
• Exponential Backoff: Smart reconnection strategy
• No Data Loss: Seamless transition between WebSocket and polling

🧠 Smart Entity Management

• Collector-Based Filtering: Only creates entities for enabled collectors on your Unraid server
• Physical Disk Detection: Automatically filters out virtual disks (docker_vdisk, log) and empty disk slots
• Dynamic Discovery: Automatically discovers containers, VMs, disks, network interfaces, and more
• Minimal Clutter: Disabled collectors result in no orphan entities

🏠 Home Assistant Native

• UI Configuration: No YAML required for setup
• Device Grouping: All entities grouped under single device
• Proper Device Classes: Temperature, power, battery, duration, etc.
• State Classes: Support for statistics and long-term data
• MDI Icons: Beautiful Material Design Icons for all entities
• Extra Attributes: Contextual information for each entity

Prerequisites

Before installing this Home Assistant integration, you must have the Unraid Management Agent plugin installed and running on your Unraid server.

1. Install Unraid Management Agent Plugin

The Unraid Management Agent is a plugin that runs on your Unraid server and provides the API that this Home Assistant integration connects to.

Option A: Install via Community Applications (Recommended)

1. Open your Unraid web interface
2. Go to Apps tab
3. Search for "Unraid Management Agent"
4. Click Install
5. Configure the plugin settings (default port: 8043)
6. Start the plugin

Option B: Manual Installation via Plugin URL

1. Open your Unraid web interface
2. Go to Plugins tab
3. Click Install Plugin
4. Paste this URL:

   https://raw.githubusercontent.com/ruaan-deysel/unraid-management-agent/main/unraid-management-agent.plg
   

5. Click Install
6. Configure the plugin settings (default port: 8043)
7. Start the plugin

Verify Plugin Installation

After installation, verify the plugin is running by accessing:

http://<your-unraid-ip>:8043/api/v1/health

You should see a JSON response indicating the service is healthy.

2. System Requirements

• Unraid Server: Unraid 6.9.0 or newer
• Home Assistant: 2025.1 or newer
• Network: Home Assistant must be able to reach your Unraid server on port 8043 (or your configured port)

3. Network Configuration

Ensure your firewall allows:

• Port 8043 (or your configured port) for REST API communication
• WebSocket connections on the same port for real-time updates

---

Installation

Via HACS (Recommended)

Manual HACS Installation:

1. Open HACS in Home Assistant
2. Go to Integrations
3. Click the ⋮ menu → Custom repositories
4. Add this repository: https://github.com/ruaan-deysel/ha-unraid-management-agent
5. Category: Integration
6. Click Add
7. Search for Unraid Management Agent
8. Click Download
9. Restart Home Assistant

Manual Installation

1. Download the latest release from the Releases page
2. Extract the unraid_management_agent folder to your Home Assistant config/custom_components/ directory
3. Restart Home Assistant

Configuration

1. Go to Settings → Devices & Services
2. Click + Add Integration
3. Search for "Unraid Management Agent"
4. Enter your Unraid server details:
   • Host: 192.168.1.100 (your Unraid IP)
   • Port: 8043 (default)
   • Update Interval: 30 seconds
   • Enable WebSocket: true (recommended)

Entity Overview

Sensors (30+ base entities)

System Sensors (6+ entities)

• CPU Usage (%)
• RAM Usage (%)
• CPU Temperature (°C)
• Motherboard Temperature (°C) - conditional, only if available
• Fan {name} (RPM) - dynamic, one per detected fan
• Uptime (human-readable format)

Array Sensors (2 entities)

• Array Usage (%)
• Parity Check Progress (%)

Disk Sensors (dynamic)

• Disk {name} Usage (%) - dynamic, one per disk (excludes parity disks)
• Disk {name} Health - dynamic, one per physical disk with SMART data
• Docker vDisk Usage (%) - conditional, only if Docker vDisk exists
• Log Filesystem Usage (%) - conditional, only if log filesystem exists

GPU Sensors (3 entities, conditional)

• GPU Utilization (%)
• GPU CPU Temperature (°C)
• GPU Power (W)

UPS Sensors (4 entities, conditional)

• UPS Battery (%)
• UPS Load (%)
• UPS Runtime (seconds)
• UPS Power (W) - compatible with Home Assistant Energy Dashboard

Network Sensors (dynamic)

• Network {interface} Inbound (bits/s) - one per physical interface
• Network {interface} Outbound (bits/s) - one per physical interface

Binary Sensors (7+ entities)

Array Binary Sensors (3)

• Array Started (on/off)
• Parity Check Running (on/off)
• Parity Valid (problem indicator)

UPS Binary Sensor (1, conditional)

• UPS Connected (on/off)

Container Binary Sensors (dynamic)

• Container {name} (running/stopped)

VM Binary Sensors (dynamic)

• VM {name} (running/stopped)

Network Binary Sensors (dynamic)

• Network {interface} (up/down)

Switches (dynamic)

• Container {name} - Start/stop Docker containers
• VM {name} - Start/stop virtual machines

Buttons (4)

• Start Array
• Stop Array
• Start Parity Check
• Stop Parity Check

Services

The integration provides 18 services for advanced automation and control beyond what switches and buttons offer.

Container Services (5)

• unraid_management_agent.container_start - Start a Docker container
• unraid_management_agent.container_stop - Stop a Docker container
• unraid_management_agent.container_restart - Restart a Docker container
• unraid_management_agent.container_pause - Pause a running Docker container
• unraid_management_agent.container_resume - Resume a paused Docker container (unpause)

Example:

service: unraid_management_agent.container_start
data:
  container_id: "plex"

Virtual Machine Services (7)

• unraid_management_agent.vm_start - Start a virtual machine
• unraid_management_agent.vm_stop - Stop a virtual machine (graceful shutdown)
• unraid_management_agent.vm_restart - Restart a virtual machine
• unraid_management_agent.vm_pause - Pause a running virtual machine (suspend to RAM)
• unraid_management_agent.vm_resume - Resume a paused virtual machine
• unraid_management_agent.vm_hibernate - Hibernate a virtual machine (suspend to disk)
• unraid_management_agent.vm_force_stop - Force stop a virtual machine (equivalent to power off)

Example:

service: unraid_management_agent.vm_hibernate
data:
  vm_id: "Windows 10"

Array Control Services (2)

• unraid_management_agent.array_start - Start the Unraid array
• unraid_management_agent.array_stop - Stop the Unraid array

Example:

service: unraid_management_agent.array_start

Parity Check Services (4)

• unraid_management_agent.parity_check_start - Start a parity check
• unraid_management_agent.parity_check_stop - Stop the running parity check
• unraid_management_agent.parity_check_pause - Pause the running parity check
• unraid_management_agent.parity_check_resume - Resume a paused parity check

Example:

service: unraid_management_agent.parity_check_pause

Example Automations

Note: Replace tower in the entity IDs below with your actual Unraid server hostname (e.g., if your Unraid server is named "nas", use sensor.unraid_nas_cpu_usage).

High CPU Alert

automation:
  - alias: "Unraid High CPU Alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.unraid_tower_cpu_usage
        above: 80
        for:
          minutes: 5
    action:
      - service: notify.mobile_app
        data:
          title: "⚠️ Unraid Alert"
          message: "CPU usage is {{ states('sensor.unraid_tower_cpu_usage') }}%"

UPS Graceful Shutdown

automation:
  - alias: "Unraid UPS Critical Shutdown"
    trigger:
      - platform: numeric_state
        entity_id: sensor.unraid_tower_ups_battery
        below: 10
    action:
      - service: switch.turn_off
        target:
          entity_id: all
        data:
          domain: switch
      - delay:
          seconds: 30
      - service: button.press
        target:
          entity_id: button.unraid_tower_stop_array

Disk Health Alert

automation:
  - alias: "Unraid Disk Health Alert"
    trigger:
      - platform: state
        entity_id: sensor.unraid_tower_disk_disk1_health
        to: "Failed"
    action:
      - service: notify.mobile_app
        data:
          title: "🚨 Unraid Disk Alert"
          message: "Disk 1 health status is {{ states('sensor.unraid_tower_disk_disk1_health') }}"

Container Auto-Restart on Failure

automation:
  - alias: "Restart Plex on Stop"
    trigger:
      - platform: state
        entity_id: switch.unraid_tower_container_plex
        to: "off"
        for:
          minutes: 1
    action:
      - service: unraid_management_agent.container_start
        data:
          container_id: "plex"

Architecture

Components

• API Client (api_client.py) - REST API communication with aiohttp
• WebSocket Client (websocket_client.py) - Real-time event streaming
• Data Coordinator (__init__.py) - Data management and updates
• Config Flow (config_flow.py) - UI-based configuration
• Platforms:
  • sensor.py - System, array, GPU, UPS, network sensors
  • binary_sensor.py - Status indicators
  • switch.py - Container and VM control
  • button.py - Array and parity check control

Data Flow

Unraid Server (REST API + WebSocket)
           ↓
    API Client / WebSocket Client
           ↓
    Data Update Coordinator
           ↓
    Entity Platforms (Sensor, Binary Sensor, Switch, Button)
           ↓
    Home Assistant UI

Update Strategy

1. Initial Load: REST API fetches all data on startup
2. Real-Time Updates: WebSocket receives events and updates coordinator
3. Fallback Polling: REST API polls at configured interval if WebSocket fails
4. Control Actions: REST API sends commands, coordinator refreshes immediately

Troubleshooting

Common Issues

Cannot Connect

• Verify Unraid Management Agent is running: curl http://<ip>:8043/api/v1/health
• Check firewall rules allow port 8043
• Ensure Home Assistant can reach Unraid server

WebSocket Not Working

• Check logs for WebSocket errors
• Verify no proxy blocking WebSocket
• Integration will fall back to REST polling automatically

Entities Not Updating

• Check update interval in options
• Verify WebSocket connection in logs
• Test REST API manually

Missing Entities

• Verify resources exist on Unraid (containers, VMs, GPU, UPS)
• Reload integration
• Check logs for entity creation errors

Development

Project Structure

ha-unraid-management-agent/
├── custom_components/
│   └── unraid_management_agent/
│       ├── __init__.py           # Integration setup
│       ├── api_client.py         # REST API client
│       ├── binary_sensor.py      # Binary sensor platform
│       ├── button.py             # Button platform
│       ├── config_flow.py        # Configuration flow
│       ├── const.py              # Constants
│       ├── manifest.json         # Integration metadata
│       ├── sensor.py             # Sensor platform
│       ├── strings.json          # Translations
│       ├── switch.py             # Switch platform
│       └── websocket_client.py   # WebSocket client
└── README.md                     # This file

Testing

Run the test suite:

# Run all tests
pytest

# Run tests with coverage report
pytest --cov --cov-report=term-missing --cov-report=html

# Run specific test file
pytest tests/test_coordinator.py -v

# Run tests in parallel
pytest -n auto

CI/CD Pipeline:

• Automated tests run on every push and pull request
• Tests run on Python 3.12 and 3.13
• Coverage reports automatically uploaded to Codecov
• Test results tracked in GitHub Actions

Coverage Requirements:

• Minimum coverage: 60%
• Coverage reports available at Codecov

1. Install in development mode

2. Enable debug logging:

   logger:
     default: info
     logs:
       custom_components.unraid_management_agent: debug

3. Check logs for errors

4. Test all entity types

5. Test control operations

6. Test WebSocket reconnection

Releases

This integration follows semantic versioning with the format vYYYY.MM.x (e.g., v2025.11.1).

Latest Release

Check the Releases page for the latest version and changelog.

Release Process

Releases are automated via GitHub Actions:

1. Update manifest.json version
2. Update CHANGELOG.md with release notes
3. Create and push a version tag (e.g., v2025.11.1)
4. GitHub Actions automatically builds and publishes the release

For detailed release process documentation, see docs/RELEASE_PROCESS.md.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run linting and tests:

   scripts/lint
   pytest

5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Guidelines:

• Follow Home Assistant core integration best practices
• Maintain 60%+ code coverage
• Use type hints throughout
• Add tests for new features
• Update documentation as needed

CI Checks: All pull requests must pass:

• ✅ Ruff linting (format and check)
• ✅ Pytest test suite (Python 3.12 & 3.13)
• ✅ Coverage threshold (60% minimum)
• ✅ Manifest and configuration validation

5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Trademark Notice

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