Unraid Management Agent

Monitor and control your Unraid server over a REST API, WebSocket events, Prometheus metrics, MQTT and the Model Context Protocol (MCP), from a single lightweight Go plugin.

The agent reads system state directly from Unraid, /proc, /sys, the Docker Engine API and libvirt, caches it, and serves it to dashboards, Home Assistant, monitoring stacks and AI assistants. It can also act: start and stop containers, VMs, the array and parity checks, spin disks, and more.

[!NOTE] This is a community plugin, not an official Lime Technology product. Unraid 7.2 and later ship an official GraphQL API; this agent is an independent REST, WebSocket, MQTT and MCP alternative. The two run side by side without conflict.

Contents

• Features
• Requirements
• Installation
• Quick start
• Security and privacy
• Configuration
• Integrations
• Documentation
• Troubleshooting and support
• Development
• Contributing
• License

Features

Monitoring

• System: CPU, memory, temperatures, fans (with their labels), uptime and hardware (DMI) details
• Array and parity: array state, capacity, parity status, schedules and check history
• Disks: per-disk usage, temperatures, SMART health and spin state, without waking spun-down disks
• Docker containers and VMs: state, resource use and image update checks (Docker Engine SDK and libvirt)
• Shares, unassigned devices, network interfaces, notifications, mover, plugins and OS updates
• ZFS: pools, datasets, snapshots, ARC, scrub progress and the SMART health of pool member drives
• UPS (apcupsd or NUT): charge, load, runtime, power, input/output/battery voltage, line frequency, transfers and self-test result
• GPUs (Intel, AMD, NVIDIA), network cards with SFP/QSFP optic diagnostics, and SAS storage topology (controllers, enclosures, drive paths)

Hardware auto-detection: hardware-dependent collectors (network cards and optics, SAS storage topology, GPU, UPS, NUT and ZFS) run only when the hardware is present, and the settings page hides what your server does not have. See Hardware Auto-Detection.

Control

• Docker containers: start, stop, restart, pause, unpause and update
• VMs: start, stop, restart, pause, resume, hibernate, force stop, snapshots and clones
• Array and parity checks, disk spin up and down, User Scripts, notifications, fan control and CPU tuning
• Server reboot and shutdown

Operations

• Alert rules and scheduled health checks with notifications
• One-click self-test and a redacted diagnostics bundle for bug reports
• mDNS (zeroconf) advertising, so clients such as Home Assistant find the agent on your network
• An optional, opt-in embedded AI operator (Agent Core, beta)

Requirements

• Unraid OS 7.2 or later (amd64)
• TCP port 8043 free on the server (configurable)
• No other plugins. Optional features use what is already installed: apcupsd or the NUT plugin for UPS data, storcli or sg_ses for SAS topology, and the GPU drivers for GPU metrics.

See System Requirements for details.

Installation

Community Applications (recommended): in the Unraid web UI, open Apps, search for Unraid Management Agent and click Install.

Plugin URL: open Plugins → Install Plugin and paste:

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

The service starts on port 8043. Open Settings → Unraid Management Agent to configure it. See the Installation Guide for upgrades and removal.

Quick start

Replace tower.local with your server's address.

1. Check that the agent is up (this endpoint never needs a token):

   curl http://tower.local:8043/api/v1/health
   

2. Generate an API token on the settings page and click Apply. Read it into a variable with a silent prompt (paste it, then press Enter), so it stays out of your shell history:

   read -rs UMA_TOKEN && export UMA_TOKEN
   

3. Read data and run an action:

   curl -H "Authorization: Bearer $UMA_TOKEN" http://tower.local:8043/api/v1/system
   curl -H "Authorization: Bearer $UMA_TOKEN" http://tower.local:8043/api/v1/docker
   curl -X POST -H "Authorization: Bearer $UMA_TOKEN" http://tower.local:8043/api/v1/docker/nginx/restart
   

4. Explore every endpoint in the interactive API docs at http://tower.local:8043/swagger/.

More examples: Quick Start Guide.

Security and privacy

[!WARNING] The API listens on all interfaces on port 8043 over plain HTTP. Set an API token, and enable HTTPS before the token crosses a network you do not trust: over plain HTTP anyone on the path can read it. Never forward the port to the internet.

• Authentication. Without a token, anyone on your network can read monitoring data, and on a fresh install every control action (REST and MCP) is refused. With a token, every request must send Authorization: Bearer <token>, except /api/v1/health, the Swagger UI and the optional MCP connect URL (/mcp/<secret>), where the secret in the URL is the credential. Treat that URL like a password. Installs upgraded from a version without a token keep control actions working (ALLOW_UNAUTHENTICATED_WRITES) until you set one.
• What access allows. The REST API and MCP can reboot or shut down the server, control containers, VMs and the array, spin disks and run User Scripts as /bin/bash. MCP read-only mode and per-tool policies restrict MCP clients only, not the REST API.
• Encryption. Serve HTTPS by setting a certificate and key (TLS_CERT_FILE, TLS_KEY_FILE).
• WAN IP lookup. Only when you request network access URLs, the agent asks api.ipify.org, ifconfig.me and icanhazip.com for your public IP. Turn WAN IP Lookup off to make no external requests.

Details: Configuration → Security and SECURITY.md.

Configuration

Most settings live on the plugin settings page (Settings → Unraid Management Agent) and are saved to /boot/config/plugins/unraid-management-agent/config.cfg. Clicking Apply restarts the service.

Longer intervals use less power. Every option, the config.yml file and command-line flags are covered in the Configuration Guide.

Integrations

Documentation

Troubleshooting and support

• Logs: /var/log/unraid-management-agent.log. Turn on Debug Logging in the settings for more detail.
• Run Self-Test on the settings page checks every data source; Download Diagnostics creates a redacted bundle to attach to a bug report.
• See Diagnostic Commands for command-line checks.
• Ask on the Unraid forum support thread or open an issue.

Development

Requires Go (the version in go.mod) and make.

git clone https://github.com/tinkerologie/unraid-management-agent.git
cd unraid-management-agent
make deps            # install dependencies and tools
make local           # build for this machine
make test            # run the tests with the race detector
make pre-commit-run  # lint, format and security checks
make package         # build the Unraid plugin bundle

The Ansible playbook builds the plugin, deploys it to a server and verifies the endpoints:

cp ansible/inventory.yml.example ansible/inventory.yml   # set the server address and credentials
ansible-playbook -i ansible/inventory.yml ansible/deploy.yml --tags build,deploy,verify

Architecture, conventions and the AI-assistant workflow are described in AGENTS.md.

Contributing

Contributions are welcome, especially fixes for hardware the maintainer cannot test: disk controllers, GPUs, UPS models and network cards. Every change starts with an issue, and pull requests follow the template and pass the quality checks. Read CONTRIBUTING.md before you start.

When you report a hardware problem, include your Unraid version, the hardware involved and a diagnostics bundle from the settings page.

License

MIT