Overview

UnraidClaw is a permission-enforcing REST API gateway that lets AI agents manage your Unraid server. It sits between AI tools and your server, providing a unified API with fine-grained access control, authentication, and activity logging.

Instead of giving AI agents direct access to Unraid internals, UnraidClaw acts as a controlled gateway. It combines Unraid's GraphQL API with direct system integration (CLI commands for parity checks, reboot/shutdown, and syslog; filesystem operations for share config editing and notification management; network introspection via ip) to expose capabilities that no single Unraid API covers.

It works with any AI agent that speaks HTTP, and ships with an OpenClaw plugin for plug-and-play integration.

What does it do?

The plugin installs a Node.js server and a web interface that together give you:

43 tools across 11 categories:

• Docker – List, inspect, logs, start, stop, restart, pause, unpause, remove containers

• Virtual Machines – List, inspect, start, stop, force stop, pause, resume, reboot VMs

• Array – Status, start/stop array, parity check start/pause/resume/cancel

• Disks – List disks, view individual disk details and SMART data

• Shares – List shares, view details, edit settings (comment, allocator, split level, floor)

• System – System info, CPU/memory metrics, list services, reboot, shutdown

• Notifications – List, create, archive, delete notifications

• Network – View interfaces, routes, and DNS configuration

• Users – View current user info

• Logs – Read syslog entries

Settings Page (Settings > UnraidClaw) with four tabs:

• Dashboard – Service status, server info, quick health check

• Settings – Service enable/disable, port configuration, API key generation

• Permissions – Full resource:action permission matrix with presets (Read Only, Docker Manager, VM Manager, Full Admin, None). 21 individual permission toggles across 8 categories

• Activity Log – Searchable log of all API requests with timestamps, endpoints, methods, and results

Security:

• HTTPS with auto-generated self-signed TLS certificate (EC prime256v1, 10-year validity)

• API keys hashed with SHA-256 before storage; the plaintext key is never persisted

• Every request authenticated via API key ( x-api-key header ) and checked against the permission matrix

• All activity logged in JSONL format

• Runs locally on your Unraid box, no cloud dependencies

OpenClaw Plugin (npm) – For AI agents that support the OpenClaw protocol:

npm pack unraidclaw && openclaw plugins install unraidclaw-*.tgz && rm unraidclaw-*.tgz

Registers all 43 tools automatically. Configure with your server URL and API key in ~/.openclaw/openclaw.json.

{
  "plugins": {
    "entries": {
      "unraidclaw": {
        "config": {
          "serverUrl": "https://YOUR_UNRAID_IP:9876",
          "apiKey": "YOUR_API_KEY",
          "tlsSkipVerify": true
        }
      }
    }
  }
}

Requirements

• Unraid 7.0.0 or later (Node.js 22+ is built-in)

Installation

Community Applications (coming soon, waiting for approval)
Search for UnraidClaw in the CA plugin store.

Manual Install
Go to Plugins > Install Plugin and paste:

https://raw.githubusercontent.com/emaspa/unraidclaw/main/packages/unraid-plugin/unraidclaw.plg

Quick Start

1. Go to Settings > Management Access in the Unraid WebGUI, scroll to the API section, and copy your Unraid API key

2. Go to Settings > UnraidClaw, paste the Unraid API key into the Unraid API Key field

3. Generate an UnraidClaw API key (save it, it won't be shown again)

4. Configure permissions on the Permissions tab

5. Set Service to Enabled and click Apply
   

The server starts on port 9876 over HTTPS.

Troubleshooting

• Service won't start: Check that Node.js 22+ is available. Run node --version in the Unraid terminal.

• Connection refused: Verify the service is running: /etc/rc.d/rc.unraidclaw status

• TLS certificate errors: If your AI client doesn't accept self-signed certs, set tlsSkipVerify: true in the OpenClaw config.

• Permission denied on API call: Check the Activity Log tab to see which permission was denied, then enable it on the Permissions tab.

• API key not working: The key is shown only once during generation. If lost, generate a new one from the Settings tab.

Support & Feedback

Please report bugs and feature requests on the GitHub Issues page.

For general discussion, questions, support and feedback, feel free to post in this thread.

Source code: github.com/emaspa/unraidclaw

Edited March 31Mar 31 by bubbl3

v0.1.31

Fixes

Parity-check status now reflects reality (#14, thanks @rodaballo)

/api/array/parity/status previously read Unraid's GraphQL array.parityCheckStatus, which doesn't reflect parity checks started outside Connect (via mdcmd, cron, or the webGUI) — so it reported no activity during a running check.

It now reads live md-driver state from mdcmd status (the same source the webGUI uses, consistent with how start/pause/resume/cancel already shell out to mdcmd).

API

Backward compatible — the existing keys keep their names and now carry real data, with new fields added:

Field	Source
running	mdResyncPos>0 ‖ mdResync>0
progress	mdResyncPos / mdResyncSize (0–100)
speed / speedHuman	mdResyncDb / mdResyncDt (KiB/s) / MB/s string
errors	sbSyncErrs
paused (new)	in progress but not advancing
correcting (new)	mdResyncCorr
action (new)	mdResyncAction (e.g. "check P Q")
position / size (new)	KiB done / total
lastCheck (new)	start/finish/duration/exit of the previous check

No changes required for existing API consumers (OpenClaw included)

v0.1.30

Important

Critical fix. v0.1.27–v0.1.29 silently chowned host root paths (/, /usr, /usr/local, /usr/local/emhttp, ...) to UID 1001 on install, breaking SSH key authentication on systems with default StrictModes yes. All users on those versions should upgrade.

Fixes

• Stop chowning host paths (#13)

  • The build's tar invocation lacked --owner=root --group=root, so the GitHub Actions runner's UID 1001 was baked into every directory entry of the .txz. upgradepkg then preserved that ownership on the host's matching paths.

  • Build now uses tar --owner=root --group=root --numeric-owner. All archive metadata is root:root.

• Heal existing installs

  • Postinstall step issues a corrective chown root:root on the affected host paths. Upgrading to v0.1.30 fixes already-broken systems automatically. No-op on healthy systems.

  • After upgrade, you can safely revert any StrictModes no workaround in /etc/ssh/sshd_config.

Huge thanks to @justinmeader for the exceptional bug report, root cause and fix included.

v0.1.29
Fixes

• Fix POST /api/docker/containers rejecting valid registry-prefixed image references (#12)

  • Now accepts host[:port]/path/name:tag (e.g. 192.168.178.158:5000/homelab/myapp:latest)

  • Now accepts digest references (e.g. nginx@sha256:...)

  • The previous validator only allowed a single : and didn't permit @, which blocked everyone running a local/private Docker registry.

v0.1.28

• Fix min/max version to align with XML v7 minimum by @mstrhakr in #11

v0.1.27

• Add memory stats (total, used, free, percent) to /api/system/info and /api/system/metrics

• Add CPU load averages (1m, 5m, 15m) to /api/system/info and /api/system/metrics

• Add disk usage (used, free, percent) to /api/disks endpoints via df

• Make /api/system/metrics a lightweight endpoint for polling (memory + CPU load only)

v0.1.26

• Security Hardening Release

• Fix command injection in syslog and notification endpoints (execSync to execFileAsync)

• Fix path traversal in notification archive/delete and docker template filename

• Restrict CORS to local network origins only

• Stop exposing Unraid API key in settings page HTML

• Remove internal error details from API error responses

• Add rate limiting on API authentication (10 attempts/min per IP)

• Add input validation on docker:create parameters (image, ports, volumes, env, network)

• Validate share update fields (floor, splitLevel, comment)

• Set restrictive file permissions on config, permissions, and log files

• Enforce strict boolean types in permission saves

• Require WebGUI authentication on activity log PHP endpoints

• Move CSRF token from global JS variable to data attribute

v0.1.25

• Add Unraid WebUI Port setting for non-standard port configurations

• GraphQL URL is now constructed automatically from the port (no more manual URL editing)

v0.1.24

• Remove GraphQL URL from settings (hardcode to http://localhost/graphql)

• Prevents misconfiguration that caused 500 errors on all GraphQL-based endpoints

v0.1.23

• Fix /api/health reporting hardcoded version "0.1.0" instead of actual installed version

• Version is now read from the .plg file automatically, so it always matches the installed release

v0.1.22

• Fix Docker inspect, logs, and all actions (start/stop/restart/pause/unpause) failing with 400 Bad Request

• Switch all Docker and VM operations from GraphQL to CLI for compatibility with Unraid 7.2.3

• Add docker:create endpoint for deploying containers via AI agents (thanks @bitcryptic-gw)

• Fix OpenAI function calling compatibility

• Fix global TLS bypass in OpenClaw plugin (now scoped per-connection)

• Fix XML injection in docker:create template generation

• Add ADMIN API key requirement to documentation

• Correct API route paths in README

OpenClaw plugin also updated to v0.1.3 on npm:

rm -rf ~/.openclaw/extensions/unraidclaw && npm pack unraidclaw && openclaw plugins install unraidclaw-*.tgz && rm unraidclaw-*.tgz
openclaw gateway restart

On the OpenClaw side, multi server support has been added, config is backwards compatible, but you can have multiple servers configured this way:

{
  "plugins": {
    "allow": ["unraidclaw"],
    "entries": {
      "unraidclaw": {
        "config": {
          "servers": [
            {
              "name": "home",
              "serverUrl": "https://192.168.1.100:9876",
              "apiKey": "...",
              "tlsSkipVerify": true,
              "default": true
            },
            {
              "name": "work",
              "serverUrl": "https://10.0.0.50:9876",
              "apiKey": "..."
            }
          ]
        }
      }
    }
  }
}

With multi-server, every tool accepts an optional server parameter (e.g. unraid_docker_list(server: "work")). If omitted, the default server is used.

Edited June 9Jun 9 by bubbl3

Forgive me for asking but I'm currently using OpenClaw. What does this do for me that OpenClaw doesn't? Or why would pick to use this over openclaw? I'm relatively new to LLM API use and still learning daily.

12 hours ago, FlyingTexan said:

Forgive me for asking but I'm currently using OpenClaw. What does this do for me that OpenClaw doesn't? Or why would pick to use this over openclaw? I'm relatively new to LLM API use and still learning daily.

This adds an additional layer of control and security, since many of the commands are not available through the unraid API the alternative is to give OpenClaw SSH root access to your server, which i wouldn't recommend. The focus here is on risk aware security, give enough granular access for what you want OpenClaw to do without full unrestricted root access to your unraid machine.

Since the plugin is stable features and functionality wise, the next couple of releases starting from v0.1.26 are going to be security hardening focused: https://forums.unraid.net/topic/197498-plugin-support-unraidclaw-ai-agent-gateway-with-permission-control/#findComment-1610700

Looks super interesting, will give it a go! Very new to AI and currently use Claude desktop rather than openclaw. Can I use Claude desktop to connect to it?

Cheers

Stuart

5 hours ago, schford said:

Looks super interesting, will give it a go! Very new to AI and currently use Claude desktop rather than openclaw. Can I use Claude desktop to connect to it?

Cheers

Stuart

Yes you can, install the plugin in unraid and then point Claude to the github repository, it will figure it out :)

Just FYI this has been tested and working on unraid 7.3.0 beta

Hi my Agent says he cant see some things any thoughts?

10 hours ago, schford said:

Hi my Agent says he cant see some things any thoughts?

That is correct, is not a bug, this is the data available on that API endpoint:

Will see if it makes sense to add memory and cpu usage.

Disks are on another endpoint, but only status no details on usage space:

The array status shows the total used and free space:

Having per disk stats is a good idea and will take it as a feature request.

Edited March 24Mar 24 by bubbl3

@schford

There is also a new metrics endpoint for easy polling:

Update plugin in unRAID and in OpenClaw:

openclaw plugins update unraidclaw
openclaw gateway restart

Edited March 24Mar 24 by bubbl3

Multi server support in OpenClaw has been added, config is backwards compatible, but you can have multiple servers configured this way:

{
  "plugins": {
    "allow": ["unraidclaw"],
    "entries": {
      "unraidclaw": {
        "config": {
          "servers": [
            {
              "name": "home",
              "serverUrl": "https://192.168.1.100:9876",
              "apiKey": "...",
              "tlsSkipVerify": true,
              "default": true
            },
            {
              "name": "work",
              "serverUrl": "https://10.0.0.50:9876",
              "apiKey": "..."
            }
          ]
        }
      }
    }
  }
}

With multi-server, every tool accepts an optional server parameter (e.g. unraid_docker_list(server: "work")). If omitted, the default server is used.

Hey,

install of the plugin seems to be broken with the current version of OpenClaw. When using openclaw plugins install unraidclaw you'll get an error saying that unraidclaw is a skill and to use openclaw skills install unraidclaw.

When using that it installs fine, but once you configure it as a plugin in openclaw.json you'll break the installation as the gateway won't restart. Added the output of my shell.

shell.log

On 3/27/2026 at 1:05 PM, domori said:

Hey,

install of the plugin seems to be broken with the current version of OpenClaw. When using openclaw plugins install unraidclaw you'll get an error saying that unraidclaw is a skill and to use openclaw skills install unraidclaw.

When using that it installs fine, but once you configure it as a plugin in openclaw.json you'll break the installation as the gateway won't restart. Added the output of my shell.

shell.log

Thanks for surfacing this, nothing wrong with the plugin, Clawhub is being stupid and classified this as a skill instead of a plugin, submitted a correction but they are not the fastest, use this command to install:

npm pack unraidclaw && openclaw plugins install unraidclaw-*.tgz && rm unraidclaw-*.tgz

You will need the same to update:

rm -rf ~/.openclaw/extensions/unraidclaw && npm pack unraidclaw && openclaw plugins install unraidclaw-*.tgz && rm unraidclaw-*.tgz

If you installed from Clawhub you'll need to uninstall and install again

Edited March 31Mar 31 by bubbl3

Wow! Incredible stuff, thanks for that!

Will try that as soon as my Openclaw is set up.

Very interesting, thanks for sharing, please could you give me some real world examples of where I would see the most benefit in installing/enabling this?

On 4/8/2026 at 1:48 PM, NodeCentral said:

Very interesting, thanks for sharing, please could you give me some real world examples of where I would see the most benefit in installing/enabling this?

Aside of general automation and orchestration, here's just a few scenarios:

Monitoring and alerts -- Ask your AI agent "how are my disks doing?" and get back temperatures, SMART status, array health, and parity check progress in plain English. No need to open the WebGUI.                                                                                                                                                          

Docker management -- "Stop the Plex container, update it, and start it again" or "spin up a new Nginx container on  port 8080 with these volume mounts" -- all through natural language.

Troubleshooting -- "Show me the last 200 lines of syslog filtered for errors" or "which containers are using the most resources?" -- get answers without SSH-ing in.

Multi-server oversight -- If you run multiple Unraid boxes (home NAS + media server, or home + offsite backup), you can manage them all from one AI conversation: "compare disk usage across my home and backup servers."

Scheduled checks -- Have your AI agent run a morning briefing: array status, any failed disks, parity errors, Docker containers that crashed overnight, unread notifications.

Quick actions from anywhere -- Reboot the server, start/stop VMs, pause a parity check -- all from your phone       through whatever chat interface your AI agent uses (Telegram, Discord, etc.), without opening a browser.                                                                                                                 

The key value is turning Unraid management into a conversation instead of clicking through the WebGUI. The permission matrix means you control exactly what the agent can and can't do.

im super new to this and hermes was extremely easier for me to setup and use. How do i intergrate this into my hermes setup ? thanks

On 4/14/2026 at 9:15 AM, prene1 said:

im super new to this and hermes was extremely easier for me to setup and use. How do i intergrate this into my hermes setup ? thanks

Sorry for the late reply, I was on holiday.

Would suggest pointed Herms to the repo and ask to build a skill, it should be able to do it by itself: https://github.com/emaspa/unraidclaw

Hello

I know this should be a stright forward plugin, but running the latest stable unraid and latest unraidclaw, I cant get unraidclaw and openclaw to speak to each other.

I have attempted the following:

1. Uninstalled and reinstalled the plugin.

2. Checked the node --version and /etc/rc.d/rc.unraidclaw status to make sure those are good. And they are

3. Double checked my openclaw.json file to make sure "tlsSkipVerify: true" and it is.

4. I have Created multiple keys and double checked my openclaw.json file try different api keys. To no success

But no matter what I try, openclaw and unraidclaw just do not speak to each other. Any time I type something that the unraidclaw should understand I get a wall of text, that pops up in the logs, which is attached below, and I continue to get api resonses or calls. Any assistance would be great!

2026-05-12T171544.731-0500 [reload].txt

I really like your plugin interface. Would be very useful to expose it as a MCP server so it can integrate with broader clients (e.g OpenWebUI, LobeHub or RikkaHub on android). Is there any plan to support this?

On 5/12/2026 at 3:25 PM, Mrtj18 said:

Hello

I know this should be a stright forward plugin, but running the latest stable unraid and latest unraidclaw, I cant get unraidclaw and openclaw to speak to each other.

I have attempted the following:

1. Uninstalled and reinstalled the plugin.

2. Checked the node --version and /etc/rc.d/rc.unraidclaw status to make sure those are good. And they are

3. Double checked my openclaw.json file to make sure "tlsSkipVerify: true" and it is.

4. I have Created multiple keys and double checked my openclaw.json file try different api keys. To no success

But no matter what I try, openclaw and unraidclaw just do not speak to each other. Any time I type something that the unraidclaw should understand I get a wall of text, that pops up in the logs, which is attached below, and I continue to get api resonses or calls. Any assistance would be great!

2026-05-12T171544.731-0500 [reload].txt

The OpenClaw logs don't say much unfortunately, from your screenshot doesn't seem like there has been any request to UnraidClaw server, you should see both successful and failed ones there under activity. Can you share the related OpenClaw config (minus the API key of course).

On 5/16/2026 at 4:07 AM, socool said:

I really like your plugin interface. Would be very useful to expose it as a MCP server so it can integrate with broader clients (e.g OpenWebUI, LobeHub or RikkaHub on android). Is there any plan to support this?

Interesting suggestion, will keep it in mind, atm I can't spend much time on this aside essential fixes as I'm traveling for work, but will look into it sometime in June.

1 hour ago, bubbl3 said:

The OpenClaw logs don't say much unfortunately, from your screenshot doesn't seem like there has been any request to UnraidClaw server, you should see both successful and failed ones there under activity. Can you share the related OpenClaw config (minus the API key of course).

upon inspection I have found that my openclaw.json was missing the required lines mentioned in the install instructions. ( I dont know how, I had them inserted correctly before) and now when I attempt to insert them it is giving me syntax error or unrecognized key error when inserting the required config lines or api key. Do you have any tips to clean this up? Openai was still giving me bad config lines and commas to insert. I took out my identifying info and api's the best I could.

openclaw.json

Edited May 18May 18 by Mrtj18

2 hours ago, Mrtj18 said:

upon inspection I have found that my openclaw.json was missing the required lines mentioned in the install instructions. ( I dont know how, I had them inserted correctly before) and now when I attempt to insert them it is giving me syntax errors when inserting the required config lines. Do you have any tips to clean this up. I dont understand how to fix syntax errors. Openai was still giving me bad config lines and commas to insert. I took out my identifying info and api's the best I could.

openclaw.json

You have a trailing comma there:

"plugins": {
    "unraidclaw": {
      "serverUrl": "http://192.168.50.122:9876",
      "apiKey": "7f3fa56ce...",   ← trailing comma
    },

It should be:

"plugins": {
    "unraidclaw": {
      "serverUrl": "http://192.168.50.122:9876",
      "apiKey": "7f3fa56ce..."
    },

In general you seems a bit inexperienced here, would suggest reading docs and asking for help in the OpenClaw subreddit, having an LLM writing your config means you won't really know how it works. Also not sure what LLM you're using, it should have catched the trailing comma, it's basic JSON.