UnraidClaw

AI Agent Gateway for Unraid. Permission-enforcing REST API that lets AI agents manage your server.

UnraidClaw sits between AI agents and your Unraid servers, providing a unified REST API with fine-grained access control. 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. Every call is authenticated, authorized against a configurable permission matrix, and logged.

Features

• 44 tools across 11 categories: Docker, VMs, Array, Disks, Shares, System, Notifications, Network, Users, Logs
• 22 permission keys in a resource:action matrix, configurable from the WebGUI
• HTTPS with auto-generated self-signed TLS certificate
• SHA-256 API key authentication
• Activity logging with JSONL format, filter, and search
• OpenClaw plugin available on npm (openclaw plugins install unraidclaw)
• Single-file server, no node_modules needed on Unraid

Requirements

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

Installation

From Community Applications

Search for UnraidClaw in the Unraid CA store and click Install.

Manual install

# Download and install the plugin
plugin install https://raw.githubusercontent.com/emaspa/unraidclaw/main/packages/unraid-plugin/unraidclaw.plg

Setup

1. Go to Settings > Management Access in the Unraid WebGUI, scroll to the API section, and copy your Unraid API key (must have ADMIN role)
2. Go to Settings > UnraidClaw, paste the Unraid API key into the Unraid API Key field
3. Generate an UnraidClaw API key (it's hashed with SHA-256; 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 by default. A self-signed TLS certificate is auto-generated on first start.

API

All endpoints return a consistent envelope:

{
  "ok": true,
  "data": { ... }
}

Authentication via x-api-key: <api-key> header.

Endpoints

Docker create

POST /api/docker/containers accepts:

{
  "image": "vikunja/vikunja:latest",
  "name": "vikunja",
  "ports": ["3456:3456"],
  "volumes": ["/mnt/cache/appdata/vikunja:/app/vikunja/files"],
  "env": ["VIKUNJA_SERVICE_TIMEZONE=Europe/London"],
  "restart": "unless-stopped",
  "network": "bridge",
  "icon": "https://example.com/icon.png",
  "webui": "http://[IP]:[PORT:3456]/"
}

Only image is required. The container is started immediately and an Unraid dockerMan XML template is created so it appears in the Docker tab.

Docker actions

POST /api/docker/containers/:id/:action where action is one of: start, stop, restart, pause, unpause

VM actions

POST /api/vms/:id/:action where action is one of: start, stop, force-stop, pause, resume, reboot, reset

Share update

PATCH /api/shares/:name accepts:

{
  "comment": "My share description",
  "allocator": "highwater",
  "splitLevel": "1",
  "floor": "0"
}

OpenClaw Plugin

The OpenClaw plugin exposes all 44 tools to any AI agent that supports the OpenClaw protocol.

Install

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

Update

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

Configure

Edit ~/.openclaw/openclaw.json:

Single server:

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

Multiple servers:

{
  "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.

Set tlsSkipVerify: true when using the auto-generated self-signed certificate.

Keeping the API key out of the config file: you don't have to hard-code the key in openclaw.json. OpenClaw expands ${VAR} references from the environment at config-load time, so you can point apiKey at an environment variable:

"apiKey": "${UNRAID_API_KEY}"

The secret then lives in your environment (shell, systemd EnvironmentFile, or container secret) and never in openclaw.json. This works for servers[].apiKey in the multi-server form too.

Provider-backed secrets (SecretRef): apiKey also accepts an OpenClaw SecretRef object, so the key can come from one of your configured secret providers (file, env, exec). OpenClaw resolves it before the plugin loads — the plugin only ever sees the resolved string:

"apiKey": { "source": "file", "provider": "default", "id": "/unraidclaw_key" }

source is one of file, env, or exec; provider names a provider from your secrets.providers config; id is the lookup key. This also works per-server on servers[].apiKey.

Tools

Permissions

Permissions use a resource:action format. Configure them from the WebGUI Permissions tab or edit /boot/config/plugins/unraidclaw/permissions.json directly.

The WebGUI includes presets: Read Only, Docker Manager, VM Manager, Full Admin, and None.

Architecture

                                                        GraphQL ──> Unraid API
                                                       /            (list queries, array, disks)
┌─────────────┐     HTTPS      ┌──────────────────┐──+
│  AI Agent   │ ──────────────> │   UnraidClaw     │   \
│  (OpenClaw) │   x-api-key    │   (Fastify)      │    CLI ──────> docker, virsh, mdcmd,
└─────────────┘                 │                  │   /            reboot, ip, ...
                                │  - Auth          │──+
                                │  - Permissions   │   \
                                │  - Activity Log  │    Filesystem > share configs, syslog,
                                └──────────────────┘                 notifications

This is a pnpm monorepo with three packages:

Security

• API keys are hashed with SHA-256 before storage; the plaintext key is never persisted
• All requests require authentication via x-api-key header
• Every API call is checked against the permission matrix before execution
• Activity logging records all requests with timestamps, endpoints, and results
• HTTPS with auto-generated EC (prime256v1) certificates, 10-year validity
• The server runs locally on your Unraid box, no cloud dependencies

License

MIT