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)
  • Virtual machines: state, start, stop, restart, and force stop; resume for a paused VM. Shown when the host has at least one VM. Needs the VM Read role to list and VM Write to act
  • 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
  • Creating, editing, or deleting VMs or VM devices, and the VM console and VM logs - 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

Field Typical value
Port 443
Scheme https
Auth Username + API key (WebSocket login after connect)

Add in Kochab

  1. Open More > Stacks & 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 & 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:

    Terminal window
    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 ships with a self-signed certificate made for localhost. When Kochab first connects, it shows that certificate. Tap Trust. Kochab pins that exact certificate and asks again if it changes, for example after you renew or regenerate it in TrueNAS.

Do not import the default certificate as a CA. It does not list the address you connect with, so the connection fails. Import a CA only if you replaced the default with a certificate from your own CA, and that certificate lists the hostname or IP you use in Kochab. See Certificate trust.

Sign-in security and reverse proxies

How Kochab signs in depends on your TrueNAS version:

  • TrueNAS 26 and later support SCRAM. Kochab proves it holds the API key without sending the key itself.
  • TrueNAS 25.x has no SCRAM. The only way to sign in with an API key is to send the key to TrueNAS.

When you add a TrueNAS that does not offer SCRAM, Kochab asks you to confirm before it sends the key, once per address. That is expected on TrueNAS 25.x. If your TrueNAS runs 26 or later, tap Cancel: secure sign-in should be there, and something on the network may be hiding it.

TrueNAS revokes the key if it arrives over a connection it does not see as encrypted. For a 25.x host, that means:

  • Use https. Kochab will not send the key to a TrueNAS address that uses http, because TrueNAS would revoke it on arrival.
  • A reverse proxy must forward HTTPS to TrueNAS. A proxy that accepts https from your phone and then forwards plain http to TrueNAS gets the key revoked on the first sign-in. TrueNAS decides from its own web server: it treats a request as encrypted only when that request reached TrueNAS itself over TLS (the X-Https: on header its nginx sets). Point the proxy at TrueNAS’s https port, not port 80.

If Kochab reports “TrueNAS revoked this key (insecure connection)”, create a new API key in TrueNAS, fix the connection as above, and edit the service in Kochab with the new key.

On TrueNAS 26 and later, secure sign-in over https is also tied to TrueNAS’s own certificate (SCRAM channel binding). A reverse proxy that decrypts the connection shows your phone its own certificate instead, so sign-in fails, even if the proxy re-encrypts to TrueNAS. To reach a 26.x host from outside your network, use one of these:

  • a VPN such as Tailscale, which carries the connection straight to TrueNAS;
  • a proxy set to TLS passthrough, which forwards the encrypted connection without decrypting it.

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