truenas-skillManage TrueNAS SCALE via API. Check pool health, manage datasets and snapshots, monitor alerts, control services, manage apps, orchestrate Dockge container stacks, and manage bookmarks. Use when the user asks about their NAS, storage, backups, containers, bookmarks, or homelab services.
Install via ClawdBot CLI:
clawdbot install anotb/truenas-skillManage a TrueNAS SCALE server and its apps via the TrueNAS API and Dockge Socket.IO.
TRUENAS_URL — TrueNAS base URL (e.g., https://10.0.0.5:444)
TRUENAS_API_KEY — API key from TrueNAS UI → API KeysTRUENAS_VERIFY_TLS — Set to "1" to enforce TLS certificate validation (default: skip for self-signed certs)DOCKGE_URL — Dockge URL (e.g., http://10.0.0.5:5001)
DOCKGE_USER — Dockge login username
DOCKGE_PASS — Dockge login passwordSee the references/ directory for per-service env vars. Common ones:
SONARR_URL, SONARR_API_KEY — TV show management
RADARR_URL, RADARR_API_KEY — Movie management
PROWLARR_URL, PROWLARR_API_KEY — Indexer management
OVERSEERR_URL, OVERSEERR_API_KEY — Media request UI
PLEX_URL — Media server (no auth on LAN)
TAUTULLI_URL, TAUTULLI_API_KEY — Plex analytics
QBITTORRENT_URL — Torrent client (no auth)
SABNZBD_URL, SABNZBD_API_KEY — Usenet client
AUDIOBOOKSHELF_URL, AUDIOBOOKSHELF_API_KEY
NTFY_URL — Push notifications
SYNCTHING_URL, SYNCTHING_API_KEY — File sync
N8N_URL, N8N_API_KEY — Workflow automation
NOCODB_URL, NOCODB_API_KEY — Database
CHANGEDETECTION_URL, CHANGEDETECTION_API_KEY
CRAFTY_URL, CRAFTY_API_KEY — Game servers
LAZYLIBRARIAN_URL, LAZYLIBRARIAN_API_KEY
METUBE_URL — YouTube downloader
KARAKEEP_URL, KARAKEEP_API_KEY — Bookmarks with AI taggingHTTPS REQUIRED: TrueNAS auto-revokes API keys used over HTTP.
REST API Deprecation Notice: The REST API (/api/v2.0/) is deprecated in TrueNAS 25.04
and fully removed in 26.04. Use the WebSocket API (via scripts/truenas-ws.mjs) as
the forward-compatible method. REST examples below still work on 24.10 and 25.x.
curl -sk "$TRUENAS_URL/api/v2.0/[endpoint]" \
-H "Authorization: Bearer $TRUENAS_API_KEY"The -k flag is needed for self-signed certificates (common on home servers).
The WebSocket API uses a DDP-like protocol (Meteor style). REST paths become dot notation:
/api/v2.0/app → app.query, /api/v2.0/system/info → system.info.
// Connect: wss://<host>/websocket (rejectUnauthorized: false for self-signed)
// 1. Handshake
send: {"msg": "connect", "version": "1", "support": ["1"]}
recv: {"msg": "connected", "session": "..."}
// 2. Authenticate
send: {"id": "1", "msg": "method", "method": "auth.login_with_api_key", "params": ["API_KEY"]}
recv: {"id": "1", "msg": "result", "result": true}
// 3. Call methods
send: {"id": "2", "msg": "method", "method": "system.info", "params": []}
send: {"id": "3", "msg": "method", "method": "app.query", "params": []}Use the helper script for WebSocket calls: node scripts/truenas-ws.mjs
curl -k, rejectUnauthorized: false) because homelab servers typically use self-signed certs. Set TRUENAS_VERIFY_TLS=1 to enforce strict TLS validation.curl -sk "$TRUENAS_URL/api/v2.0/system/info" -H "Authorization: Bearer $TRUENAS_API_KEY"# All pools with health status
curl -sk "$TRUENAS_URL/api/v2.0/pool" -H "Authorization: Bearer $TRUENAS_API_KEY" \
| jq '.[] | {name, healthy}'
# Or via WebSocket
node scripts/truenas-ws.mjs pool.query '[]'The API returns a .healthy boolean per pool. For deeper status, inspect the full pool object.
curl -sk "$TRUENAS_URL/api/v2.0/alert/list" -H "Authorization: Bearer $TRUENAS_API_KEY" \
| jq '.[] | {level, formatted}'curl -sk "$TRUENAS_URL/api/v2.0/service" -H "Authorization: Bearer $TRUENAS_API_KEY" \
| jq '.[] | select(.state == "RUNNING") | .service'curl -sk "$TRUENAS_URL/api/v2.0/pool/dataset" -H "Authorization: Bearer $TRUENAS_API_KEY" \
| jq '.[] | {name, type, used: .used.parsed, available: .available.parsed}'curl -sk -X POST "$TRUENAS_URL/api/v2.0/pool/dataset" \
-H "Authorization: Bearer $TRUENAS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "pool/path/new-dataset"}'# Destructive — confirm with user first
curl -sk -X DELETE "$TRUENAS_URL/api/v2.0/pool/dataset/id/DATASET_ID" \
-H "Authorization: Bearer $TRUENAS_API_KEY"# WebSocket (required on 25.10+, /api/v2.0/zfs/snapshot returns 404)
node scripts/truenas-ws.mjs zfs.snapshot.query '[]'node scripts/truenas-ws.mjs zfs.snapshot.create '[{"dataset": "pool/dataset", "name": "manual-YYYY-MM-DD"}]'curl -sk "$TRUENAS_URL/api/v2.0/pool/snapshottask" -H "Authorization: Bearer $TRUENAS_API_KEY" \
| jq '.[] | {dataset, schedule, enabled}'curl -sk "$TRUENAS_URL/api/v2.0/replication" -H "Authorization: Bearer $TRUENAS_API_KEY" \
| jq '.[] | {name, state: .state.state}'TrueNAS Apps are the official marketplace for installing containerized services.
curl -sk "$TRUENAS_URL/api/v2.0/app" -H "Authorization: Bearer $TRUENAS_API_KEY" \
| jq '.[] | {name, state, version}'curl -sk "$TRUENAS_URL/api/v2.0/app" -H "Authorization: Bearer $TRUENAS_API_KEY" \
| jq '.[] | select(.upgrade_available) | .name'See references/app-installation.md for the full installation guide covering:
curl -sk "$TRUENAS_URL/api/v2.0/app?name=APP_NAME" -H "Authorization: Bearer $TRUENAS_API_KEY" \
| jq '.[0] | {name, state, portals}'Dockge is a companion UI for Docker Compose stacks not in the TrueNAS Apps catalog.
It uses Socket.IO, not REST. Use the provided scripts.
npm install # in this skill's root directorynode scripts/dockge-list.mjs# Update all running stacks
node scripts/dockge-update.mjs
# Update specific stacks
node scripts/dockge-update.mjs mystack1 mystack2Dockge uses Socket.IO with WebSocket transport.
Status codes:
Key events:
login — authenticate with username/passwordstackList — get all stacks (received via agent event)agent, "", "updateStack", stackName — trigger pull + restartNote: Stacks prefixed with ix- are TrueNAS-managed apps visible to Dockge — skip those when updating.
Run these commands for a quick health overview:
# Pool health
curl -sk "$TRUENAS_URL/api/v2.0/pool" -H "Authorization: Bearer $TRUENAS_API_KEY" \
| jq '.[] | {name, healthy}'
# Active alerts
curl -sk "$TRUENAS_URL/api/v2.0/alert/list" -H "Authorization: Bearer $TRUENAS_API_KEY" \
| jq '.[] | {level, formatted}'
# Running services
curl -sk "$TRUENAS_URL/api/v2.0/service" -H "Authorization: Bearer $TRUENAS_API_KEY" \
| jq '.[] | select(.state == "RUNNING") | .service'
# App updates available
curl -sk "$TRUENAS_URL/api/v2.0/app" -H "Authorization: Bearer $TRUENAS_API_KEY" \
| jq '.[] | select(.upgrade_available) | .name'
# Replication status
curl -sk "$TRUENAS_URL/api/v2.0/replication" -H "Authorization: Bearer $TRUENAS_API_KEY" \
| jq '.[] | {name, state: .state.state}'This skill includes reference files for common homelab service categories. Each covers
API patterns, env vars, and common agent tasks for services that typically run alongside
TrueNAS:
| Reference | Services | File |
|-----------|----------|------|
| Media management | Overseerr, Sonarr, Radarr, Prowlarr, Plex, Tautulli | references/media-management.md |
| App installation | TrueNAS native app install guide | references/app-installation.md |
| Download clients | qBittorrent, SABnzbd, FlareSolverr | references/downloads.md |
| Homelab services | ntfy, Syncthing, n8n, NocoDB, ChangeDetection, Crafty | references/homelab-services.md |
| Books & media | Audiobookshelf, LazyLibrarian, Calibre-Web, MeTube | references/books-and-media.md |
| Bookmarks | Karakeep (AI-powered bookmark manager) | references/bookmarks.md |
Load the relevant reference file when the user asks about a specific service category.
Run the monitoring checklist above. Summarize pool states, alerts, and any pending updates.
# TrueNAS apps
curl -sk "$TRUENAS_URL/api/v2.0/app" -H "Authorization: Bearer $TRUENAS_API_KEY" \
| jq '.[] | select(.state == "RUNNING") | .name'
# Dockge stacks (if configured)
node scripts/dockge-list.mjsFollow the guide in references/app-installation.md:
node scripts/truenas-ws.mjs zfs.snapshot.create '[{"dataset": "pool/dataset", "name": "manual-snapshot-name"}]'See references/downloads.md for qBittorrent and SABnzbd API commands.
See references/media-management.md for Overseerr request workflow.
Generated Mar 1, 2026
Home users managing personal NAS systems can monitor pool health, check active alerts, and view dataset usage to ensure data integrity and prevent storage failures. This scenario supports proactive maintenance for media libraries, backups, and containerized applications running on TrueNAS SCALE.
Enthusiasts running media servers like Plex or Jellyfin can use this skill to manage storage pools, create snapshots for backup, and control associated services such as Sonarr or Radarr via optional API keys. It helps automate media acquisition and organization while ensuring server uptime.
Small businesses relying on TrueNAS for data backups can automate snapshot creation, monitor replication tasks, and check system alerts to maintain data redundancy. This scenario reduces manual oversight and enhances disaster recovery readiness for critical business files.
Developers and IT professionals can orchestrate Docker Compose stacks via Dockge integration, manage app services on TrueNAS, and monitor container health. This scenario streamlines deployment and management of homelab or development environments using containerized tools.
Users leveraging bookmarking tools like KaraKeep can integrate AI-tagged bookmark management with storage monitoring, allowing for organized access to saved resources alongside NAS health checks. This scenario combines personal productivity with infrastructure oversight.
Offer the core TrueNAS management features for free, while charging for advanced integrations with services like Overseerr, n8n, or Crafty. This model attracts homelab users initially and monetizes power users needing automation and specialized tooling.
Provide paid consulting to businesses for customizing the skill to their specific TrueNAS setups, including integration with proprietary systems or enhanced security configurations. This model leverages expertise in NAS management and API development.
Target small to medium enterprises using TrueNAS in production by offering support packages for troubleshooting, updates, and compliance with security best practices. This model ensures reliable operation and generates recurring revenue from service agreements.
💬 Integration Tip
Ensure environment variables are securely stored and use the WebSocket API for future compatibility, as the REST API is deprecated in newer TrueNAS versions.
Manage torrents with qBittorrent. Use when the user asks to "list torrents", "add torrent", "pause torrent", "resume torrent", "delete torrent", "check download status", "torrent speed", "qBittorrent stats", or mentions qBittorrent/qbit torrent management.
Search indexers and manage Prowlarr. Use when the user asks to "search for a torrent", "search indexers", "find a release", "check indexer status", "list indexers", "prowlarr search", "sync indexers", or mentions Prowlarr/indexer management.
Interact with Uptime Kuma monitoring server. Use for checking monitor status, adding/removing monitors, pausing/resuming checks, viewing heartbeat history. Triggers on mentions of Uptime Kuma, server monitoring, uptime checks, or service health monitoring.
Backup Clawdbot workspace and config to GitHub with git-crypt encryption. Use for daily automated backups or manual backup/restore operations.
Query and monitor Unraid servers via the GraphQL API. Use when the user asks to 'check Unraid', 'monitor Unraid', 'Unraid API', 'get Unraid status', 'check disk temperatures', 'read Unraid logs', 'list Unraid shares', 'Unraid array status', 'Unraid containers', 'Unraid VMs', or mentions Unraid system monitoring, disk health, parity checks, or server status.
CLI tool for interacting with Atlassian Jira and Confluence