# Connect TrueNAS SCALE

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

Canonical: https://kochab.io/docs/services/truenas/

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](/docs/infra-vs-containers/).

## 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 **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:

   ```sh
   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:

   ```sh
   #!/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](/docs/cert-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](https://api.truenas.com/)