truenas-skill（特鲁纳斯技能）

TrueNAS SCALE Skill

Manage a TrueNAS SCALE server and its apps via the TrueNAS API and Dockge Socket.IO.

Setup

Required Environment Variables

TRUENAS_URL       — TrueNAS base URL (e.g., https://10.0.0.5:444)
TRUENAS_API_KEY   — API key from TrueNAS UI → API Keys

Optional: TLS Configuration

TRUENAS_VERIFY_TLS  — Set to "1" to enforce TLS certificate validation (default: skip for self-signed certs)

Optional: Dockge (Docker Compose UI)

DOCKGE_URL        — Dockge URL (e.g., http://10.0.0.5:5001)
DOCKGE_USER       — Dockge login username
DOCKGE_PASS       — Dockge login password

Optional: Homelab Service API Keys

See 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 tagging

API Notes

HTTPS 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.

REST API (Legacy)

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).

WebSocket API (Recommended)

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 <method> [params_json]

Security Notes

• Self-signed certificates: TLS verification is skipped by default (curl -k, rejectUnauthorized: false) because homelab servers typically use self-signed certs. Set TRUENAS_VERIFY_TLS=1 to enforce strict TLS validation.
• API key scope: Use a read-only or least-privilege API key when possible. TrueNAS lets you scope keys to specific endpoints.
• Credentials stay local: All env vars are read at runtime and sent only to the configured service endpoints. Nothing is phoned home.

Core Operations

System Info

curl -sk "$TRUENAS_URL/api/v2.0/system/info" -H "Authorization: Bearer $TRUENAS_API_KEY"

Pool Health

# 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.

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'

Dataset Management

List Datasets

curl -sk "$TRUENAS_URL/api/v2.0/pool/dataset" -H "Authorization: Bearer $TRUENAS_API_KEY" \
  | jq '.[] | {name, type, used: .used.parsed, available: .available.parsed}'

Create Dataset

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"}'

Delete 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"

Snapshots & Replication

List Snapshots

# WebSocket (required on 25.10+, /api/v2.0/zfs/snapshot returns 404)
node scripts/truenas-ws.mjs zfs.snapshot.query '[]'

Create Snapshot

node scripts/truenas-ws.mjs zfs.snapshot.create '[{"dataset": "pool/dataset", "name": "manual-YYYY-MM-DD"}]'

Snapshot Task Status

curl -sk "$TRUENAS_URL/api/v2.0/pool/snapshottask" -H "Authorization: Bearer $TRUENAS_API_KEY" \
  | jq '.[] | {dataset, schedule, enabled}'

Replication Health

curl -sk "$TRUENAS_URL/api/v2.0/replication" -H "Authorization: Bearer $TRUENAS_API_KEY" \
  | jq '.[] | {name, state: .state.state}'

App Management

TrueNAS Apps are the official marketplace for installing containerized services.

List Installed Apps

curl -sk "$TRUENAS_URL/api/v2.0/app" -H "Authorization: Bearer $TRUENAS_API_KEY" \
  | jq '.[] | {name, state, version}'

Check for Updates

curl -sk "$TRUENAS_URL/api/v2.0/app" -H "Authorization: Bearer $TRUENAS_API_KEY" \
  | jq '.[] | select(.upgrade_available) | .name'

Install / Update Apps

See references/app-installation.md for the full installation guide covering:

• Checking app templates and storage requirements
• Creating datasets with proper ACLs
• Installing with correct storage mappings
• Handling apps with multiple storage mounts

App Status

curl -sk "$TRUENAS_URL/api/v2.0/app?name=APP_NAME" -H "Authorization: Bearer $TRUENAS_API_KEY" \
  | jq '.[0] | {name, state, portals}'

Dockge (Docker Compose Stacks)

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.

Prerequisites

npm install   # in this skill's root directory

List Stacks

node scripts/dockge-list.mjs

Update Stacks

# Update all running stacks
node scripts/dockge-update.mjs

# Update specific stacks
node scripts/dockge-update.mjs mystack1 mystack2

Socket.IO Protocol Details

Dockge uses Socket.IO with WebSocket transport.

Status codes:

• 1 = inactive/exited
• 3 = running
• 4 = updating

Key events:

• login — authenticate with username/password
• stackList — get all stacks (received via agent event)
• agent, "", "updateStack", stackName — trigger pull + restart

Note: Stacks prefixed with ix- are TrueNAS-managed apps visible to Dockge — skip those when updating.

Monitoring Checklist

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}'

Homelab Services

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:

Load the relevant reference file when the user asks about a specific service category.

Common Tasks

"Check NAS health"

Run the monitoring checklist above. Summarize pool states, alerts, and any pending updates.

"What's running?"

# 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.mjs

"Install an app"

Follow the guide in references/app-installation.md:

1. Check app template for storage requirements
2. Create dataset(s) under the apps pool
3. Set ACL with apps preset
4. Install app with correct storage mappings

"Take a snapshot"

node scripts/truenas-ws.mjs zfs.snapshot.create '[{"dataset": "pool/dataset", "name": "manual-snapshot-name"}]'

"What's downloading?"

See references/downloads.md for qBittorrent and SABnzbd API commands.

"Add a movie/show"

See references/media-management.md for Overseerr request workflow.