unraidclaw 0.1.12 → 0.1.14

package/README.md

@@ -4,7 +4,7 @@
 
 [![npm](https://img.shields.io/npm/v/unraidclaw)](https://www.npmjs.com/package/unraidclaw)
 
-This is the [OpenClaw](https://github.com/openclaw/openclaw) plugin for **[UnraidClaw](https://github.com/emaspa/unraidclaw)**. It exposes **44 tools** to any AI agent running on OpenClaw, letting it monitor and manage your Unraid server. The plugin talks to the UnraidClaw gateway (a permission-enforcing REST API) running on your Unraid box.
+This is the [OpenClaw](https://github.com/openclaw/openclaw) plugin for **[UnraidClaw](https://github.com/emaspa/unraidclaw)**. It exposes **55 tools** to any AI agent running on OpenClaw, letting it monitor and manage your Unraid server. The plugin talks to the UnraidClaw gateway (a permission-enforcing REST API) running on your Unraid box.
 
 ## Prerequisites
 
@@ -71,6 +71,24 @@ With multi-server config, every tool accepts an optional `server` parameter (e.g
 
 Set `tlsSkipVerify: true` when using UnraidClaw's 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`. Two options:
+
+**Environment variable** — OpenClaw expands `${VAR}` references at config-load time:
+
+```json
+"apiKey": "${UNRAID_API_KEY}"
+```
+
+**Provider-backed secret (`SecretRef`)** — point `apiKey` at one of your configured secret providers; OpenClaw resolves it before the plugin loads, so the plugin only ever sees the resolved string:
+
+```json
+"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. Both forms also work per-server on `servers[].apiKey`. (Requires unraidclaw 0.1.12+.)
+
 ## Usage
 
 Once installed and configured, just ask your agent:
@@ -80,17 +98,23 @@ Once installed and configured, just ask your agent:
 - "What's the array status?"
 - "Show me disk temperatures"
 - "Create a new nginx container with port 8080"
+- "Find me a Community Applications backup tool"
+- "Install Jellyfin from Community Applications, media on /mnt/user/media"
+- "Update the jellyfin container to the latest image"
+- "Which of my Unraid plugins have updates?"
 - "Check parity status"
 - "Reboot the server"
 
 ## Tools
 
-44 tools across 11 categories:
+55 tools across 13 categories:
 
 | Category | Tools |
 |----------|-------|
 | Health | `unraid_health_check` |
 | Docker | `unraid_docker_list`, `unraid_docker_inspect`, `unraid_docker_logs`, `unraid_docker_create`, `unraid_docker_start`, `unraid_docker_stop`, `unraid_docker_restart`, `unraid_docker_pause`, `unraid_docker_unpause`, `unraid_docker_remove` |
+| Community Apps | `unraid_ca_search`, `unraid_ca_app`, `unraid_ca_install`, `unraid_ca_update`, `unraid_ca_remove` |
+| Plugins | `unraid_plugins_list`, `unraid_plugin_info`, `unraid_plugin_install`, `unraid_plugin_check_updates`, `unraid_plugin_update`, `unraid_plugin_remove` |
 | VMs | `unraid_vm_list`, `unraid_vm_inspect`, `unraid_vm_start`, `unraid_vm_stop`, `unraid_vm_pause`, `unraid_vm_resume`, `unraid_vm_force_stop`, `unraid_vm_reboot` |
 | Array | `unraid_array_status`, `unraid_array_start`, `unraid_array_stop`, `unraid_parity_status`, `unraid_parity_start`, `unraid_parity_pause`, `unraid_parity_resume`, `unraid_parity_cancel` |
 | Disks | `unraid_disk_list`, `unraid_disk_details` |
@@ -101,7 +125,11 @@ Once installed and configured, just ask your agent:
 | Users | `unraid_user_me` |
 | Logs | `unraid_syslog` |
 
-Every tool is gated by a 22-key `resource:action` permission matrix configured from the Unraid WebGUI, so you control exactly what agents can do.
+`unraid_ca_update` and `unraid_ca_remove` act on an installed app, so their `name` is the container's name from the Docker tab, not the app's name in the catalog. Update keeps the configuration saved on the server and restores the running or stopped state; remove deletes the container and leaves appdata, volumes, the image and the template alone. Both take `dryRun`.
+
+The six plugin tools manage Unraid `.plg` plugins through Unraid's own plugin manager. Installing one runs vendor code as root, checking for an update downloads a plugin file and stages it, and removing one runs the plugin's removal script, which may take its data with it. All four mutating tools take `dryRun`.
+
+Every tool is gated by a 30-key `resource:action` permission matrix configured from the Unraid WebGUI, so you control exactly what agents can do.
 
 ## Links
 

package/dist/index.js

@@ -113,6 +113,20 @@ function errorResult(err) {
   const message = err instanceof Error ? err.message : String(err);
   return { content: [{ type: "text", text: `Error: ${message}` }] };
 }
+function checkParams(params, allowed) {
+  for (const key of Object.keys(params)) {
+    if (allowed.includes(key)) continue;
+    const near = allowed.find((a) => a.toLowerCase() === key.toLowerCase());
+    throw new Error(
+      near ? `Unknown parameter "${key}". Did you mean "${near}"? Nothing was sent to the server.` : `Unknown parameter "${key}". Allowed parameters are: ${allowed.join(", ")}. Nothing was sent to the server.`
+    );
+  }
+  if (params.dryRun !== void 0 && typeof params.dryRun !== "boolean") {
+    throw new Error(
+      `"dryRun" must be true or false, not ${JSON.stringify(params.dryRun)}. Nothing was sent to the server.`
+    );
+  }
+}
 
 // src/tools/health.ts
 function registerHealthTools(api, getClient) {
@@ -289,6 +303,359 @@ function registerDockerTools(api, getClient) {
   });
 }
 
+// src/tools/ca.ts
+function registerCaTools(api, getClient) {
+  api.registerTool({
+    name: "unraid_ca_search",
+    description: "Search the Unraid Community Applications catalog by name, description, Docker image or maintainer. Returns matching apps with their icon, categories and whether UnraidClaw can install them. Use this to find an app before calling unraid_ca_app or unraid_ca_install.",
+    parameters: {
+      type: "object",
+      properties: {
+        q: { type: "string", description: "Search text, e.g. 'plex' or 'backup tool'. All words must match." },
+        limit: { type: "number", description: "Maximum results to return (1-100, default: 25)" },
+        includeDeprecated: { type: "boolean", description: "Include templates the maintainer deprecated (default: false)" },
+        includePlugins: { type: "boolean", description: "Include Unraid plugin (.plg) entries, which are not containers (default: false)" },
+        server: { type: "string", description: "Target server name (optional, uses default server)" }
+      },
+      required: ["q"]
+    },
+    execute: async (_id, params) => {
+      try {
+        const query = { q: String(params.q ?? "") };
+        if (params.limit) query.limit = String(params.limit);
+        if (params.includeDeprecated) query.includeDeprecated = "true";
+        if (params.includePlugins) query.includePlugins = "true";
+        return textResult(await getClient(params.server).get("/api/ca/search", query));
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  });
+  api.registerTool({
+    name: "unraid_ca_app",
+    description: "Get the full Community Applications template for one app: its Docker image, icon, WebUI, network mode, and every configurable port, volume and environment variable with its default. Also reports which required fields have no default and any reason the app cannot be installed. Several apps share a name; pass repo to disambiguate when the call reports an ambiguity.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "App name exactly as it appears in the catalog, e.g. 'Jellyfin'" },
+        repo: { type: "string", description: `Owning repository, e.g. "linuxserver's Repository". Required when several templates share the name.` },
+        server: { type: "string", description: "Target server name (optional, uses default server)" }
+      },
+      required: ["name"]
+    },
+    execute: async (_id, params) => {
+      try {
+        const query = {};
+        if (params.repo) query.repo = String(params.repo);
+        return textResult(
+          await getClient(params.server).get(
+            `/api/ca/app/${encodeURIComponent(String(params.name))}`,
+            query
+          )
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  });
+  api.registerTool({
+    name: "unraid_ca_install",
+    description: "Install a Community Applications app on the Unraid server using its template defaults. Writes an Unraid docker-manager template and has Unraid create and start the container, so it appears on the Docker tab like any other app. Required fields with no default must be supplied in overrides; call unraid_ca_app first to see them. Pass dryRun=true to get the resolved template and a preview of the docker command without changing anything. Refuses apps whose templates need unsupported or unsafe options rather than installing something different from the template.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "App name exactly as it appears in the catalog, e.g. 'Jellyfin'" },
+        repo: { type: "string", description: "Owning repository. Required when several templates share the name." },
+        containerName: {
+          type: "string",
+          description: "Name for the new container. Defaults to the app name. Letters, digits, dot, dash and underscore only."
+        },
+        overrides: {
+          type: "object",
+          additionalProperties: { type: "string" },
+          description: "Values for template fields, keyed by the field's name or its container-side target, e.g. {'/data/tvshows': '/mnt/user/media/tv', 'PUID': '99'}. An unknown key is an error."
+        },
+        dryRun: {
+          type: "boolean",
+          description: "Resolve and validate everything and return the plan without installing (default: false)"
+        },
+        server: { type: "string", description: "Target server name (optional, uses default server)" }
+      },
+      required: ["name"],
+      additionalProperties: false
+    },
+    execute: async (_id, params) => {
+      try {
+        checkParams(params, ["name", "repo", "containerName", "overrides", "dryRun", "server"]);
+        const body = {};
+        if (params.repo) body.repo = params.repo;
+        if (params.containerName) body.name = params.containerName;
+        if (params.overrides) body.overrides = params.overrides;
+        if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+        return textResult(
+          await getClient(params.server).post(
+            `/api/ca/app/${encodeURIComponent(String(params.name))}/install`,
+            body
+          )
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  }, { optional: true });
+  api.registerTool({
+    name: "unraid_ca_update",
+    description: "Update an app that is already installed on the Unraid server: pulls the newest image for the tag it runs and recreates the container from the template saved on the server, keeping its ports, paths, variables and its running or stopped state. The name is the INSTALLED CONTAINER NAME as shown on the Docker tab, not the app's name in the Community Applications catalog; call unraid_docker_list to find it and never guess it from a catalog name. Nothing is refreshed from the catalog, so values the user changed are kept. A failed pull leaves the running app untouched, the previous image is never deleted, and no appdata is removed. Pass dryRun=true to see the resolved configuration and the exact docker command without changing anything.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Installed container name, e.g. 'jellyfin'. Not the catalog app name." },
+        dryRun: {
+          type: "boolean",
+          description: "Check everything and report what would happen without pulling or recreating anything (default: false)"
+        },
+        server: { type: "string", description: "Target server name (optional, uses default server)" }
+      },
+      required: ["name"],
+      additionalProperties: false
+    },
+    execute: async (_id, params) => {
+      try {
+        checkParams(params, ["name", "dryRun", "server"]);
+        const body = {};
+        if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+        return textResult(
+          await getClient(params.server).post(
+            `/api/ca/app/${encodeURIComponent(String(params.name))}/update`,
+            body
+          )
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  }, { optional: true });
+  api.registerTool({
+    name: "unraid_ca_remove",
+    description: "Remove an installed app's Docker container from the Unraid server. The name is the INSTALLED CONTAINER NAME as shown on the Docker tab, not the app's name in the Community Applications catalog; call unraid_docker_list to find it and never guess it from a catalog name. Only the container is removed: its appdata, its Docker volumes, its image and the saved template all stay, so the app can be recreated with the same configuration. Pass dryRun=true to see exactly what would be removed and what would be kept.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Installed container name, e.g. 'jellyfin'. Not the catalog app name." },
+        dryRun: {
+          type: "boolean",
+          description: "Report what would be removed and what would be kept, without removing anything (default: false)"
+        },
+        server: { type: "string", description: "Target server name (optional, uses default server)" }
+      },
+      required: ["name"],
+      additionalProperties: false
+    },
+    execute: async (_id, params) => {
+      try {
+        checkParams(params, ["name", "dryRun", "server"]);
+        const body = {};
+        if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+        return textResult(
+          await getClient(params.server).post(
+            `/api/ca/app/${encodeURIComponent(String(params.name))}/remove`,
+            body
+          )
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  }, { optional: true });
+}
+
+// src/tools/plugins.ts
+function registerPluginTools(api, getClient) {
+  api.registerTool({
+    name: "unraid_plugins_list",
+    description: "List the Unraid plugins (.plg) installed on the server, with author, version, update URL and whether an update is already staged. Unraid plugins are not Docker containers and not Community Applications: they install files and run scripts on the server itself. Plugins marked builtin belong to Unraid OS and cannot be changed through UnraidClaw.",
+    parameters: {
+      type: "object",
+      properties: {
+        server: { type: "string", description: "Target server name (optional, uses default server)" }
+      }
+    },
+    execute: async (_id, params) => {
+      try {
+        return textResult(await getClient(params.server).get("/api/plugins"));
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  });
+  api.registerTool({
+    name: "unraid_plugin_info",
+    description: "Show one installed Unraid plugin in full: its metadata, support link, Unraid version requirements, changelog text and the structure of the files it installs. Inline scripts inside the plugin are described but never returned or executed.",
+    parameters: {
+      type: "object",
+      properties: {
+        plugin: {
+          type: "string",
+          description: "Plugin file name, e.g. 'unassigned.devices.plg'. The .plg suffix is optional."
+        },
+        server: { type: "string", description: "Target server name (optional, uses default server)" }
+      },
+      required: ["plugin"]
+    },
+    execute: async (_id, params) => {
+      try {
+        return textResult(
+          await getClient(params.server).get(
+            `/api/plugins/${encodeURIComponent(String(params.plugin))}`
+          )
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  });
+  api.registerTool(
+    {
+      name: "unraid_plugin_install",
+      description: "Install an Unraid plugin from an explicit https URL to a .plg file. The plugin file is an installer that Unraid runs as root, so this executes code from whoever controls that URL: only use a URL the user gave you or one from a source they trust. The URL must be https, public, credential-free and end in .plg. Use dryRun first to see exactly what would happen. This is not the way to install Community Applications apps; those are Docker containers (unraid_ca_install).",
+      parameters: {
+        type: "object",
+        properties: {
+          url: {
+            type: "string",
+            description: "Direct https URL of the .plg file, e.g. 'https://example.com/myplugin.plg'"
+          },
+          dryRun: {
+            type: "boolean",
+            description: "Validate the URL and return the plan without downloading, writing or installing anything (default: false)"
+          },
+          server: { type: "string", description: "Target server name (optional, uses default server)" }
+        },
+        required: ["url"],
+        additionalProperties: false
+      },
+      execute: async (_id, params) => {
+        try {
+          checkParams(params, ["url", "dryRun", "server"]);
+          const body = { url: String(params.url ?? "") };
+          if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+          return textResult(
+            await getClient(params.server).post("/api/plugins/install", body)
+          );
+        } catch (err) {
+          return errorResult(err);
+        }
+      }
+    },
+    { optional: true }
+  );
+  api.registerTool(
+    {
+      name: "unraid_plugin_check_updates",
+      description: "Check whether a newer version of an installed Unraid plugin has been published, and stage it for installation. This is not a read-only lookup: it downloads the plugin file from the plugin's own update URL and writes it to the plugin manager's staging directory, where this tool's update call and the Unraid web UI will then offer to install it. Nothing is installed or executed by the check. Run this before unraid_plugin_update.",
+      parameters: {
+        type: "object",
+        properties: {
+          plugin: { type: "string", description: "Plugin file name, e.g. 'unassigned.devices.plg'" },
+          dryRun: {
+            type: "boolean",
+            description: "Return the plan without downloading or staging anything (default: false)"
+          },
+          server: { type: "string", description: "Target server name (optional, uses default server)" }
+        },
+        required: ["plugin"],
+        additionalProperties: false
+      },
+      execute: async (_id, params) => {
+        try {
+          checkParams(params, ["plugin", "dryRun", "server"]);
+          const body = {};
+          if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+          return textResult(
+            await getClient(params.server).post(
+              `/api/plugins/${encodeURIComponent(String(params.plugin))}/check`,
+              body
+            )
+          );
+        } catch (err) {
+          return errorResult(err);
+        }
+      }
+    },
+    { optional: true }
+  );
+  api.registerTool(
+    {
+      name: "unraid_plugin_update",
+      description: "Install the plugin version staged by unraid_plugin_check_updates. Unraid's plugin manager runs the new plugin's install scripts as root and there is no rollback. The result says whether the installed version actually changed; a plugin manager exit code alone is not treated as success.",
+      parameters: {
+        type: "object",
+        properties: {
+          plugin: { type: "string", description: "Plugin file name, e.g. 'unassigned.devices.plg'" },
+          dryRun: {
+            type: "boolean",
+            description: "Return the plan, including which version would replace which, without installing (default: false)"
+          },
+          server: { type: "string", description: "Target server name (optional, uses default server)" }
+        },
+        required: ["plugin"],
+        additionalProperties: false
+      },
+      execute: async (_id, params) => {
+        try {
+          checkParams(params, ["plugin", "dryRun", "server"]);
+          const body = {};
+          if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+          return textResult(
+            await getClient(params.server).post(
+              `/api/plugins/${encodeURIComponent(String(params.plugin))}/update`,
+              body
+            )
+          );
+        } catch (err) {
+          return errorResult(err);
+        }
+      }
+    },
+    { optional: true }
+  );
+  api.registerTool(
+    {
+      name: "unraid_plugin_remove",
+      description: "Remove an installed Unraid plugin through the plugin manager. The plugin's own removal scripts run as root and decide what they delete: some keep their configuration and data, others delete it, so removal cannot be promised to be data-preserving. Anything depending on the plugin stops working. Use dryRun first and confirm with the user before removing.",
+      parameters: {
+        type: "object",
+        properties: {
+          plugin: { type: "string", description: "Plugin file name, e.g. 'unassigned.devices.plg'" },
+          dryRun: {
+            type: "boolean",
+            description: "Return the plan and its warnings without removing anything (default: false)"
+          },
+          server: { type: "string", description: "Target server name (optional, uses default server)" }
+        },
+        required: ["plugin"],
+        additionalProperties: false
+      },
+      execute: async (_id, params) => {
+        try {
+          checkParams(params, ["plugin", "dryRun", "server"]);
+          const body = {};
+          if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+          return textResult(
+            await getClient(params.server).post(
+              `/api/plugins/${encodeURIComponent(String(params.plugin))}/remove`,
+              body
+            )
+          );
+        } catch (err) {
+          return errorResult(err);
+        }
+      }
+    },
+    { optional: true }
+  );
+}
+
 // src/tools/vms.ts
 function registerVMTools(api, getClient) {
   api.registerTool({
@@ -870,6 +1237,8 @@ function register(api) {
   }
   registerHealthTools(api, getClient);
   registerDockerTools(api, getClient);
+  registerCaTools(api, getClient);
+  registerPluginTools(api, getClient);
   registerVMTools(api, getClient);
   registerArrayTools(api, getClient);
   registerDiskTools(api, getClient);

package/openclaw.plugin.json

@@ -6,6 +6,11 @@
       "unraid_array_start",
       "unraid_array_status",
       "unraid_array_stop",
+      "unraid_ca_app",
+      "unraid_ca_install",
+      "unraid_ca_remove",
+      "unraid_ca_search",
+      "unraid_ca_update",
       "unraid_disk_details",
       "unraid_disk_list",
       "unraid_docker_create",
@@ -29,6 +34,12 @@
       "unraid_parity_resume",
       "unraid_parity_start",
       "unraid_parity_status",
+      "unraid_plugin_check_updates",
+      "unraid_plugin_info",
+      "unraid_plugin_install",
+      "unraid_plugin_remove",
+      "unraid_plugin_update",
+      "unraid_plugins_list",
       "unraid_service_list",
       "unraid_share_details",
       "unraid_share_list",
@@ -52,8 +63,14 @@
   "configContracts": {
     "secretInputs": {
       "paths": [
-        { "path": "apiKey", "expected": "string" },
-        { "path": "servers.*.apiKey", "expected": "string" }
+        {
+          "path": "apiKey",
+          "expected": "string"
+        },
+        {
+          "path": "servers.*.apiKey",
+          "expected": "string"
+        }
       ]
     }
   },
@@ -68,14 +85,31 @@
       "apiKey": {
         "description": "API key for authenticating with UnraidClaw (single-server mode). A plaintext string, or an OpenClaw SecretRef object resolved before the plugin loads.",
         "anyOf": [
-          { "type": "string" },
+          {
+            "type": "string"
+          },
           {
             "type": "object",
-            "required": ["source", "provider", "id"],
+            "required": [
+              "source",
+              "provider",
+              "id"
+            ],
             "properties": {
-              "source": { "type": "string", "enum": ["env", "file", "exec"] },
-              "provider": { "type": "string" },
-              "id": { "type": "string" }
+              "source": {
+                "type": "string",
+                "enum": [
+                  "env",
+                  "file",
+                  "exec"
+                ]
+              },
+              "provider": {
+                "type": "string"
+              },
+              "id": {
+                "type": "string"
+              }
             },
             "additionalProperties": false
           }
@@ -103,14 +137,31 @@
             "apiKey": {
               "description": "API key for authenticating with this server. A plaintext string, or an OpenClaw SecretRef object resolved before the plugin loads.",
               "anyOf": [
-                { "type": "string" },
+                {
+                  "type": "string"
+                },
                 {
                   "type": "object",
-                  "required": ["source", "provider", "id"],
+                  "required": [
+                    "source",
+                    "provider",
+                    "id"
+                  ],
                   "properties": {
-                    "source": { "type": "string", "enum": ["env", "file", "exec"] },
-                    "provider": { "type": "string" },
-                    "id": { "type": "string" }
+                    "source": {
+                      "type": "string",
+                      "enum": [
+                        "env",
+                        "file",
+                        "exec"
+                      ]
+                    },
+                    "provider": {
+                      "type": "string"
+                    },
+                    "id": {
+                      "type": "string"
+                    }
                   },
                   "additionalProperties": false
                 }
@@ -126,7 +177,11 @@
               "description": "Use this server when no server name is specified"
             }
           },
-          "required": ["name", "serverUrl", "apiKey"]
+          "required": [
+            "name",
+            "serverUrl",
+            "apiKey"
+          ]
         }
       }
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "unraidclaw",
-  "version": "0.1.12",
-  "description": "OpenClaw plugin to manage your Unraid server — Docker, VMs, array, shares, system, and more.",
+  "version": "0.1.14",
+  "description": "OpenClaw plugin to manage your Unraid server: Docker, Community Applications, plugins, VMs, array, shares, system, and more.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",