NASlab

Install the NASlab agent: step by step

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

The agent is a small container on your NAS or server. It only reads and changes nothing. It gives the app history around the clock. You need about 5 minutes, a computer on the same home network and the NASlab app.

The pictures are schematic drawings (simplified, with demo names), not photos of the real screens. Menus may be named or placed slightly differently depending on your version.

Short version with all commands: Install the agent

Unraid

Container template from Apps

Install

Unraid Apps: search and Install (schematic)
Unraid Apps: search and Install (schematic)

Not in the catalog yet? Use step 4 (add the template repository).

  1. Open Unraid in your browser and click “Apps” at the top.
  2. Type “NASlab-Agent” into the search box.
  3. Click “Install” on the result.
  4. Not found? Unraid › Docker › bottom “Template repositories”: paste https://github.com/Tuxxler/unraid-templates › Save. Then Docker › Add Container › template “NASlab-Agent”.

Check the paths

Unraid template with the paths (schematic)
Unraid template with the paths (schematic)
  1. Keep the path “Data (/config)” as is: /mnt/user/appdata/nzblab-agent, Read/Write. The agent keeps token and history here. Without it you get a new token after every update.
  2. All other paths stay “Read Only”.
  3. No pool named “cache”? Remove the “Cache pool” row.
  4. Click “Apply” at the bottom. Unraid downloads the image and starts the agent.

Get the token

Log with the token line, token hidden (schematic)
Log with the token line, token hidden (schematic)
  1. Open Unraid › Docker.
  2. Click the icon of “nzblab-agent” › “Logs”.
  3. Copy the line “NZBLab-Agent Token”. Later it is also in the file appdata/nzblab-agent/token.txt.

In the app your server type is “Unraid”. The agent sees home network devices only with network type “Host” (optional).

Synology (DSM 7.2 or newer)

Container Manager, project

Install

Synology create project (schematic)
Synology create project (schematic)
  1. Install “Container Manager” from Package Center (if missing).
  2. Open “File Station”. In the folder “docker” create a new folder nzblab-agent.
  3. “Container Manager” › “Project” › “Create”.
  4. Enter the project name nzblab-agent.
  5. Choose the path /docker/nzblab-agent.
  6. Choose source “Create docker-compose.yml” and paste the text below.
  7. “Next” › “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   # example: only set if times in the log are wrong; use your own time zone
      PUID: "1026"   # your DSM user ID (SSH: id), 1026 is only an example
      PGID: "100"
      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
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - FOWNER
      - SETUID
      - SETGID
    security_opt:
      - no-new-privileges:true
    mem_limit: 512m
    cpus: 1.0

Get the token

Log with token, hidden (schematic)
Log with token, hidden (schematic)
  1. “Container Manager” › “Container” › “nzblab-agent” › “Details”.
  2. Open the “Log” tab.
  3. Copy the line “NZBLab-Agent Token”. Later it is in docker/nzblab-agent/token.txt.

If your storage is not “volume1”, replace /volume1 in the text with your name. In PUID and PGID, 1026 and 100 are only an example: enter the numbers of your DSM user (via SSH: id); the agent does not run as root. So far only tested with Synology DSM 7.2 in a virtual machine, not on real Synology hardware. The menu names above were not re-checked on a running DSM.

TrueNAS SCALE (24.10 or newer)

Install from a YAML text

The agent runs on 24.10 or newer. The app itself only talks to the TrueNAS interface from version 25.04.

Install

TrueNAS Install via YAML (schematic)
TrueNAS Install via YAML (schematic)
  1. Open TrueNAS in your browser › “Apps” › “Discover Apps”.
  2. Click “⋮” at the top right › “Install via YAML”.
  3. Enter nzblab-agent as the name.
  4. Paste the text below. Replace every tank with the name of your pool.
  5. Click “Save”. TrueNAS downloads 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   # example: only set if times in the log are wrong; use your own time zone
      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
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - FOWNER
      - SETUID
      - SETGID
    security_opt:
      - no-new-privileges:true
    mem_limit: 512m
    cpus: 1.0

Get the token

Log with token, hidden (schematic)
Log with token, hidden (schematic)
  1. “Apps” › “Installed” › “nzblab-agent”.
  2. Under “Workloads” click the log icon of the container.
  3. Copy the line “NZBLab-Agent Token”. Later it is in apps/nzblab-agent/token.txt in your pool.

Tip: first create a folder apps/nzblab-agent under Datasets, owned by the user “apps” (568). In the app your server type is “TrueNAS”.

Linux (Debian, Ubuntu …) · Beta

With Docker in the terminal

Install

Terminal with the commands (schematic)
Terminal with the commands (schematic)
  1. Open a terminal on the server (or connect by SSH).
  2. Create the folder: mkdir -p ~/nzblab-agent/nzblab-agent-config
  3. Give the folder to the agent: sudo chown 65534:65534 ~/nzblab-agent/nzblab-agent-config
  4. Change into the folder: cd ~/nzblab-agent
  5. Create the file: nano docker-compose.yml, paste the text below, save (Ctrl+O, Enter, Ctrl+X).
  6. Start it: docker compose up -d. On Debian with the “docker.io” package the command is docker-compose up -d (with a hyphen).
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   # example: only set if times in the log are wrong; use your own time zone
      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

Get the token

Terminal with token, hidden (schematic)
Terminal with token, hidden (schematic)
  1. Type in the terminal: docker logs nzblab-agent 2>&1 | grep "Agent Token"
  2. Copy the token. Later it is in nzblab-agent-config/token.txt.

Beta: tested only with test data and a Debian 13 test machine. In the app choose server type “Linux (Beta)”. In the text change the /srv line to your data folder; never mount the whole system (/). Never expose port 8099 to the internet.

Connect to the app

On first start the agent writes a secret token to its log once. The app uses it to connect. Never share it.

NASlab app: find the agent and paste the token (schematic)
NASlab app: find the agent and paste the token (schematic)
  1. Put your phone on the same home network as the NAS (or use a VPN).
  2. App: Settings › Server connections › NASlab-Agent.
  3. Tap “Search”. The app finds the agent on port 8099 and fills in the address.
  4. Paste the token.
  5. Tap “Save and test”. Green means connected.

Set up within 30 minutes: the agent hands out the keys of your services only in the first 30 minutes after it starts and only over HTTPS (address https://<nas-address>:8099). Connect the app within that time; otherwise restart the container. Once keys were handed out, a restart no longer opens the window (from agent 1.20.1): create an empty file keys-unlock in appdata/nzblab-agent instead (open for 10 minutes). If you open the address in a browser, it warns once because the agent uses its own certificate: compare the fingerprint with the line in the container log.

Still stuck? Questions and answers are at the bottom of Install the agent, otherwise Help and contact.