Connect TrueNAS SCALE

Add TrueNAS to Kochab with a username and API key for apps, VMs, pools, and system health.

TrueNAS SCALE is an infrastructure service. Kochab uses the TrueNAS WebSocket API for pools, system health, workloads, and alerts.

What Kochab exposes through TrueNAS

• Storage: ZFS pool capacity, health, and disk temperatures
• System: CPU, RAM, load, and network-oriented stats
• SCALE apps: list, start, stop, restart; redeploy/restart where the installed API supports it; app logs when available
• Standalone containers: start/stop (Docker workloads outside catalog apps)
• Alerts: TrueNAS alert feed on the infra surface

Not exposed through TrueNAS

• Unraid-style parity array UI or Unraid container autostart/image-update buttons
• Multi-host Docker or Portainer environment switching
• Direct Sonarr/Radarr API access (add those services separately)
• Container detail with live Engine stats
• VM lifecycle control (start/stop/restart) - use TrueNAS’s own UI

See Infrastructure vs container integrations.

Before you start

In TrueNAS: Credentials -> API Keys. Create a key. Note the username tied to the key (required on TrueNAS 26+ for SCRAM auth).

Default connection

Add in Kochab

1. Open Services -> Add service and choose TrueNAS.
2. Enter your TrueNAS hostname or IP.
3. Port 443.
4. Enter username and API key.
5. Tap Test and add.
6. Use Infrastructure for pools, apps, and containers.

Notifications (optional webhook bridge)

Kochab can push TrueNAS alerts. TrueNAS Alert Services are a fixed set of drivers (Slack, PagerDuty, email, and similar) with no generic outbound webhook, so notifications use a small bridge: a cron job reads the alert feed and POSTs one wake per new alert to your Kochab hook URL.

1. In Kochab, open the Notifications screen, find this TrueNAS instance, and copy its hook URL.

2. On the NAS (root shell), store the URL in a private curl config so it never appears in the process list:

   umask 077
   printf 'url = "https://push.kochab.io/hook/<hookId>.<token>"\n' > /root/.kochab_truenas.curl

3. Save this bridge script (e.g. /root/kochab-bridge.sh) and chmod 600 it:

   #!/bin/sh
   set -eu
   CURL_CFG="/root/.kochab_truenas.curl"
   STATE="/root/.kochab_truenas_seen"
   touch "$STATE"
   midclt call alert.list | jq -c '.[] | select(.dismissed==false) | {id, level}' |
   while IFS= read -r row; do
     id=$(printf '%s' "$row" | jq -r '.id')
     level=$(printf '%s' "$row" | jq -r '.level')
     grep -qxF "$id" "$STATE" && continue
     case "$level" in
       CRITICAL|ERROR|ALERT|EMERGENCY) event=truenas.alertCritical ;;
       WARNING|NOTICE)                 event=truenas.alertWarning ;;
       *) echo "$id" >> "$STATE"; continue ;;
     esac
     curl -fsS -K "$CURL_CFG" -X POST -H 'content-type: application/json' \
       -d "{\"eventType\":\"$event\"}" >/dev/null && echo "$id" >> "$STATE"
   done

4. Add a Cron Job (System Settings -> Advanced -> Cron Jobs) that runs the script path as root every few minutes. Do not paste the script inline into the Command field: inline text is stored in the config DB and can end up in unencrypted config backups.

Only the fixed eventType token reaches the request body, so no alert text leaves the NAS; Kochab fetches detail over its own authenticated connection. Keep both files chmod 600 and root-owned. The token in the hook URL is a credential: TrueNAS config backups can sweep in files under /root, so if a backup is exposed, revoke and re-mint the hook in Kochab to rotate the token.

TLS

TrueNAS often uses a private CA or self-signed cert. Import your CA or trust TOFU when prompted. See Certificate trust.

Tips

• API keys should be scoped for read/control as you prefer; Kochab needs app and system query methods.
• Standalone Docker containers (outside catalog apps) appear under Containers in the TrueNAS surface.

Official docs

TrueNAS API documentation