Heller Haus

Unraid API vs SSH vs Home Assistant: Three Ways to Manage Your Server

Written by

Geoffrey

in

The Three Ways to Talk to Your Unraid Server

If you’re running Unraid, you’ve probably wondered about the best way to automate tasks, monitor your system, or integrate it with other tools. After diving deep into the Unraid API for our homelab, I’ve broken down the three main approaches: the official GraphQL API, SSH access, and Home Assistant integration. Each has its strengths, and honestly, we use all three depending on what we’re trying to pull off.

1. The Unraid GraphQL API (Built-in Since 7.2)

Starting with Unraid 7.2, the API comes built into the operating system—no plugin installation required. It’s a modern GraphQL interface that provides programmatic access to pretty much everything you’d want to do with your server.

What You Can Do

  • System Information: Query CPU, memory, OS details, uptime, baseboard info, and real-time system metrics
  • Array Management: Start/stop the array, add/remove disks, monitor disk health and temperatures, track capacity (free/used/total), and manage parity checks (start, pause, resume, cancel)
  • Docker Containers: List all containers, monitor their status, start/stop/restart them, view container stats (CPU/memory usage), manage Docker networks, and detect port conflicts
  • Virtual Machines: Query VM status (running, paused, shut off), start/stop VMs, and monitor VM state changes
  • User Shares: List all shares, view share configuration (cache settings, disk allocation), and monitor share capacity
  • Notifications: Read system notifications and subscribe to real-time notification updates
  • User Management: Create/delete users, manage API keys, and control permissions (admin, connect, guest roles)
  • Remote Access: Configure Unraid Connect settings and manage allowed origins
  • Real-time Subscriptions: Subscribe to live updates for array state, Docker container changes, VM status, CPU utilization, and notifications

The Good Stuff

  • Structured Data: GraphQL gives you exactly the fields you ask for—no parsing text output or dealing with inconsistent formats
  • Real-time Updates: WebSocket subscriptions let you monitor changes as they happen (perfect for dashboards and alerts)
  • Authentication: API keys with role-based access control (RBAC) keep things secure
  • Developer-Friendly: Built-in GraphQL sandbox at http://YOUR_SERVER_IP/graphql for testing queries
  • Comprehensive Coverage: From disk temps to Docker stats to VM states—it’s all there

The Limitations

  • Read-Heavy, Not Full Control: You can query and monitor almost anything, but some operations (like installing new Docker containers from templates or modifying VM configurations) still require the web UI or SSH
  • Rate Limiting: The API implements rate limiting (100 requests per 10 seconds), so you can’t hammer it with polling loops
  • No File System Access: Can’t read/write arbitrary files on the array (that’s what SSH/NFS/SMB are for)
  • Learning Curve: GraphQL is powerful but has a learning curve if you’re used to REST APIs or command-line tools

Example Query

query {
  array {
    state
    capacity {
      disks { free, used, total }
      kilobytes { free, used, total }
    }
    disks {
      name
      size
      status
      temp
      numErrors
    }
  }
  dockerContainers {
    id
    names
    state
    status
    autoStart
  }
  info {
    cpu { manufacturer, brand, cores, threads }
    memory { total, free, used }
    os { platform, distro, release, uptime }
  }
}

Best For

  • Building custom dashboards and monitoring tools
  • Integrating Unraid with automation platforms (Home Assistant, Node-RED, custom scripts)
  • Mobile apps and remote monitoring
  • Structured data collection and reporting
  • Real-time event tracking and alerts

2. SSH Access (The Old-School Way)

SSH gives you direct shell access to your Unraid server. It’s the Swiss Army knife approach—you can do literally anything the underlying Linux system supports.

What You Can Do

  • Everything the API Does: Plus a whole lot more—SSH has no restrictions on what you can query or modify
  • File System Operations: Read, write, move, delete files anywhere on the array or cache drives
  • Docker Management: Run docker commands directly—pull images, build containers, inspect logs, exec into running containers
  • System Administration: Install packages (via NerdTools or manual compilation), modify system configs, manage services, check kernel logs
  • Scripting and Automation: Run bash scripts, cron jobs, and custom utilities
  • Network Troubleshooting: Use tools like ping, netstat, tcpdump, iperf to diagnose network issues
  • Plugin Management: Install, remove, and configure Unraid plugins from the command line
  • Backup and Restore: Script your own backup routines for config files, appdata, or the entire flash drive

The Good Stuff

  • Unlimited Power: If you can do it from the Unraid terminal, you can do it over SSH
  • Scripting: Chain commands together, use loops, conditionals, and text processing tools
  • Direct Access: No abstraction layer—you’re talking directly to the OS
  • Familiar Tools: Use standard Linux utilities (grep, awk, sed, find, etc.)
  • Debugging: When something breaks, SSH is where you go to figure out why

The Limitations

  • Security Risk: SSH access means root-level access to your entire server. A compromised SSH key or weak password is a game-over scenario
  • No Structured Output: You’re parsing text output from commands, which can break if Unraid changes its output format
  • Manual Parsing: Want to extract disk temps? You’ll need to parse the output of smartctl or hdparm with regex or text processing
  • Not Great for Polling: Running SSH commands every few seconds to monitor metrics is inefficient and can bog down your system
  • No Built-in Auth: You’re either in or out—no fine-grained permissions like the API’s role-based access

Example Command

# Get all Docker container statuses
ssh root@unraid "docker ps -a --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'"

# Check disk temperatures
ssh root@unraid "for dev in /dev/sd?; do echo -n \"$dev: \"; smartctl -A $dev | grep -i temperature | awk '{print $10}'; done"

# Start a parity check
ssh root@unraid "mdcmd check NOCORRECT"

Best For

  • One-off administrative tasks and troubleshooting
  • Complex scripting and automation that goes beyond what the API covers
  • File system operations (moving files, editing configs, backups)
  • Installing and configuring plugins or packages
  • Debugging when the API or web UI isn’t giving you enough info

3. Home Assistant Integration (The ServerBert Approach)

This is how we currently integrate Unraid with our smart home. Home Assistant connects to Unraid via the built-in Unraid integration (or custom integrations like ServerBert), which exposes Unraid data as HA entities (sensors, binary sensors, switches).

What You Can Do

  • Monitor System Health: CPU temp, CPU usage, RAM usage, array status, disk temps, UPS status—all as HA sensors
  • Track Docker Containers: See which containers are running, get update notifications, and toggle containers on/off via HA switches
  • Array Monitoring: Check if the array is started, if parity is valid, if a parity check is running, and get disk health alerts
  • VM Status: See which VMs are powered on (via device trackers or custom sensors)
  • Notifications: Forward Unraid notifications to HA for alerts via Telegram, email, or push notifications
  • Automation Triggers: Use Unraid state changes as triggers for HA automations (e.g., “if disk temp > 50°C, turn on rack fans”)
  • Dashboards: Display Unraid stats in HA dashboards alongside your smart home data

The Good Stuff

  • Unified Dashboard: See your Unraid server alongside your lights, cameras, thermostats, and everything else in one place
  • Automation Power: Trigger actions based on Unraid state—turn on cooling if the server gets hot, send alerts if a disk fails, wake the gaming VM when you sit at your desk
  • No Custom Code: The integration handles all the polling and data parsing for you
  • Historical Data: HA automatically logs sensor history, so you get graphs and trends for free
  • Notifications: Easy to set up alerts for critical events (disk errors, array stopped, high temps)

The Limitations

  • Limited Control: Most integrations are read-only or offer minimal control (start/stop containers, maybe start/stop the array). You can’t do complex operations like adding disks or modifying VM configs
  • Polling-Based: HA polls the Unraid API or SSH at intervals (usually every 30-60 seconds), so you don’t get true real-time updates
  • Entity Bloat: The integration can create hundreds of entities (one per disk, per container, per metric), which can clutter your HA instance
  • Dependency on Integration Quality: If the integration is buggy or unmaintained, you’re stuck (this is why we switched to ServerBert—it’s more reliable than the built-in integration)
  • No Direct File Access: Can’t read/write files on the array through HA

Example Automation

# Turn on rack fans if Unraid CPU temp exceeds 60°C
automation:
  - alias: "Server Cooling Boost"
    trigger:
      - platform: numeric_state
        entity_id: sensor.serverbert_cpu_temperature
        above: 60
    action:
      - service: fan.set_percentage
        target:
          entity_id: fan.rack_fans
        data:
          percentage: 100

Best For

  • Monitoring and alerting (temps, disk health, array status)
  • Integrating Unraid into smart home automations
  • Unified dashboards that combine server and home data
  • Simple on/off control of Docker containers
  • Historical trending and graphing of server metrics

So Which One Should You Use?

The answer is: all three. They’re not mutually exclusive—they’re complementary.

  • Use the Unraid API when you need structured data, real-time updates, or want to build custom integrations. It’s the future-proof way to interact with your server programmatically.
  • Use SSH when you need to do something the API doesn’t cover (file operations, complex scripting, debugging) or when you’re troubleshooting and need direct access.
  • Use Home Assistant when you want to monitor your server as part of your smart home ecosystem, trigger automations based on server state, or display server stats in a unified dashboard.

Our Setup

Here’s how we use all three in our homelab:

  • Home Assistant (ServerBert integration): Monitors CPU/RAM/disk temps, array health, Docker container status, and UPS status. Triggers automations like “turn on rack fans if server gets hot” and sends Telegram alerts if a disk fails.
  • SSH: Used for maintenance tasks (updating plugins, editing configs, running scripts), troubleshooting (checking logs, inspecting Docker containers), and one-off operations (moving files, backing up configs).
  • Unraid API: We’re just getting started with this—planning to use it for more advanced monitoring, custom dashboards, and potentially replacing some of the SSH-based scripts with cleaner GraphQL queries.

The Bottom Line

The Unraid API is a game-changer for anyone who wants to automate and integrate their server. It’s structured, secure, and comprehensive. But SSH will always be there for when you need to get your hands dirty, and Home Assistant is perfect for tying your server into your smart home ecosystem.

If you’re not using the Unraid API yet, fire up the GraphQL sandbox at http://YOUR_SERVER_IP/graphql and start exploring. Once you see how easy it is to pull structured data from your server, you’ll wonder how you lived without it.

Until next time, keep those arrays healthy and your cables tidy.

— Jillian 🏄‍♀️

Comments

Leave a Reply

More posts