Install the NASlab agent

Formerly the NZBLab agent. Container, image and folders are still called nzblab-agent.

Unraid, TrueNAS SCALE, Synology, Linux or Docker · about 5 minutes

The agent is a small container on your NAS. It measures around the clock, every 30 seconds: temperatures, CPU, GPU, memory, disk activity and which programs cause load. That way the app has history even while your phone sleeps.

The agent is free, source code publicly viewable. These app features need the agent; without it they simply don’t appear:

History without gaps: temperatures, CPU, GPU, memory
Disk activity: when a disk spins up and which programs were running
“Today on the NAS”: the last 24 hours in one list
Cache and mover per share, appdata size per container
Duplicates and an inventory of your movies and series
Home network: devices on the network and internet speed
WireGuard devices and disk prices
Overview in the browser (view only)

Read-only. All NAS folders are mounted read-only; the agent may only write to its own folder (history and token). After starting it drops root privileges. Image: ghcr.io/tuxxler/nzblab-agent:latest (amd64 and arm64). Source code publicly viewable (license PolyForm Shield 1.0.0): github.com/Tuxxler/nzblab-agent.

Unraid
TrueNAS SCALE
Synology
Linux
Docker

Unraid

Unraid › Apps › search for “NASlab-Agent” › Install.
Not found? Unraid › Docker › at the bottom “Template repositories”: add https://github.com/Tuxxler/nzblab-agent › Save. Then Docker › Add Container › template “nzblab-agent”.
Check the paths: all host paths are “Read Only”. If you have no pool named “cache”, remove the “Cache pool” path.
Keep the path “Data (/config)” → /mnt/user/appdata/nzblab-agent (Read/Write): the agent stores its token and history there; without it you get a new token after every update.
Apply. Unraid pulls the image and starts the agent.

Token: Unraid › Docker › nzblab-agent icon › Logs. The line with “Agent Token: …” appears there after the first start. Later: file appdata/nzblab-agent/token.txt.

TrueNAS SCALE

TrueNAS › Apps › Discover Apps › ⋮ at the top right › Install via YAML.
Name “nzblab-agent”, paste the text below. Replace “tank” with the name of your pool.
Save. TrueNAS pulls the image and starts the agent.

services:
  nzblab-agent:
    image: ghcr.io/tuxxler/nzblab-agent:latest
    container_name: nzblab-agent
    restart: unless-stopped
    ports:
      - "8099:8099"
    environment:
      TZ: Europe/Zurich
      PUID: "568"
      PGID: "568"
      FILES_EXCLUDE: "ix-applications,.ix-apps,.system,apps"
      CACHE_ROOTS: ""
    volumes:
      - /mnt/tank/apps/nzblab-agent:/config
      - /sys:/host/sys:ro
      - /proc:/host/proc:ro
      - /mnt/tank:/host/mnt/user:ro
    read_only: true
    tmpfs:
      - /tmp
    security_opt:
      - no-new-privileges:true
    mem_limit: 512m
    cpus: 1.0

Token: TrueNAS › Apps › Installed › nzblab-agent › Workloads › Logs. The line with “Agent Token: …” appears there after the first start. Later: file apps/nzblab-agent/token.txt in your pool.

Synology

File Station: in the “docker” folder, create the folder “nzblab-agent”.
Container Manager › Project › Create: name “nzblab-agent”, path /docker/nzblab-agent, source “Create docker-compose.yml”, paste the text below.
Next › Done. The container starts by itself.

services:
  nzblab-agent:
    image: ghcr.io/tuxxler/nzblab-agent:latest
    container_name: nzblab-agent
    restart: unless-stopped
    ports:
      - "8099:8099"
    environment:
      TZ: Europe/Zurich
      PUID: "0"
      PGID: "0"
      FILES_EXCLUDE: "@*,#*,docker"
      CACHE_ROOTS: ""
    volumes:
      - /volume1/docker/nzblab-agent:/config
      - /sys:/host/sys:ro
      - /proc:/host/proc:ro
      - /volume1:/host/mnt/user:ro
    read_only: true
    tmpfs:
      - /tmp
    security_opt:
      - no-new-privileges:true
    mem_limit: 512m
    cpus: 1.0

Token: Container Manager › Container › nzblab-agent › Log. The line with “Agent Token: …” appears there after the first start. Later: file docker/nzblab-agent/token.txt.

On Synology the agent stays root because DSM controls shares with ACLs that do not map to a user inside the container. All NAS paths are still mounted read-only.

Linux server (Debian, Ubuntu …) · beta

For a Linux server without its own NAS interface. In the app: Settings › Server connections › NAS server › type “Linux (Beta)”. Overview and storage come from the agent (version 1.14.0 or newer); the app controls Docker containers optionally through Portainer (access token: Portainer › My account › Access tokens › Add access token). Beta: tested with test data only.

Create the folders and give the folder for token and history to the agent user (65534, no login): mkdir -p ~/nzblab-agent/nzblab-agent-config && sudo chown 65534:65534 ~/nzblab-agent/nzblab-agent-config
Save the text below as docker-compose.yml in ~/nzblab-agent.
Adjust the /srv line: mount every folder whose usage the app should show read-only under /host/fs/<name>. Never mount the whole system (/); the agent doesn’t need it.
Start it in the folder: docker compose up -d

services:
  nzblab-agent:
    image: ghcr.io/tuxxler/nzblab-agent:latest
    container_name: nzblab-agent
    restart: unless-stopped
    network_mode: host
    user: "65534:65534"
    environment:
      TZ: Europe/Zurich
      FILES_ROOT: "/host/fs"
      CACHE_ROOTS: ""
    volumes:
      - ./nzblab-agent-config:/config
      - /sys:/host/sys:ro
      - /proc:/host/proc:ro
      - /etc/os-release:/host/os-release:ro
      - /srv:/host/fs/data:ro
    read_only: true
    tmpfs:
      - /tmp
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    mem_limit: 512m
    cpus: 1.0

Token: docker logs nzblab-agent 2>&1 | grep "Agent Token". Later: file nzblab-agent-config/token.txt next to docker-compose.yml.

Host networking, so the agent sees the server’s real network cards. Never expose port 8099 to the internet. The agent gets no docker.sock; Docker goes through Portainer. It runs without root and without capabilities; don’t start it as root or as your own user.

Docker (other Linux NAS)

Create a folder and save the text below in it as docker-compose.yml.
Replace the path /mnt/user with the folder that holds your files (stays read-only).
Start it in that folder: docker compose up -d

services:
  nzblab-agent:
    image: ghcr.io/tuxxler/nzblab-agent:latest
    container_name: nzblab-agent
    restart: unless-stopped
    ports:
      - "8099:8099"
    environment:
      TZ: Europe/Zurich
      PUID: "99"
      PGID: "100"
    volumes:
      - ./nzblab-agent:/config
      - /sys:/host/sys:ro
      - /proc:/host/proc:ro
      - /mnt/user:/host/mnt/user:ro
    read_only: true
    tmpfs:
      - /tmp
    security_opt:
      - no-new-privileges:true
    mem_limit: 512m
    cpus: 1.0

Token: docker logs nzblab-agent 2>&1 | grep "Agent Token". Later: file nzblab-agent/token.txt next to docker-compose.yml.

Connect the app

In the app: Settings › Server connections › NASlab-Agent › “Install agent: guide and search”.
Tap “Search”: the app checks port 8099 on your NAS and fills in the address.
Paste the token › “Save and test”.

In a browser, http://<nas-address>:8099 shows a dashboard (display only); it asks for the token as well.

Frequently asked questions

Why a token?

It protects the agent's values: without it the agent only answers “I'm alive”. On first start the agent creates a random token and writes it to the container log exactly once, afterwards only to the file token.txt. New token: delete token.txt and restart the container.

A new token after every update?

Then the /config path is missing. Unraid › Docker › nzblab-agent › Edit › path /config → /mnt/user/appdata/nzblab-agent (Read/Write) › Apply. From agent 1.13.0 the agent warns in its log and on the browser overview when the path is missing.

Away from home?

Never expose port 8099 to the internet. Connect through a VPN such as WireGuard or Tailscale; the address stays the same as at home.

The search finds nothing

Is the container running? Are you on your home network or connected via VPN? Does the container log say “Agent … auf Port 8099”? On Unraid, port 8099 must be free.

Container names or appdata sizes are missing

Only root may read those files. Set the variable PUID to 0; NAS paths stay read-only.

Home network devices are missing (Unraid)

With network type “Bridge”, Docker hides the device table. With “Host” the agent can see it. This is optional.