Live network + disk monitoring dashboard for Unraid and other hosts
3.0K
Published twice, same image: this repository is a mirror of the GHCR build (
ghcr.io/thefirstmojo/netspy) β identical tags and digests; pull from whichever registry you prefer.
Real-time monitoring of your servers in one dashboard: per-interface, per-process and per-container network throughput, disk I/O per process, CPU/RAM, and latency/health β 1 s sampling, no database, no .env file. One image, two roles, one compose.
Screenshots show synthetic demo data β no real hosts, IPs or containers.
smbd rows split per client IP (smbd[10.0.0.5]): you see exactly which client is loading a sharedocker-proxy:6379 β π 47)/proc/<pid>/io β real storage bytes incl. CIFS/NFS (SMB transfers show up on the reader)storage_history.json in /netspy/data)servers.yamlSERVERS env entries stay in the env: each row is marked with its origin (env/config) and saving writes only the config rows (edit an env row to move it to the config)0600 in /netspy/data/ssh, never sent back to the browser)ssh asks for the password interactively right in the terminalTTYD_USER + TTYD_PASS of the NetSpy container β set them in the container's env (Unraid: Docker β NetSpy β Edit β Apply, then recreate the container; agents/Portainer: the stack's environment: block). They are not a NetSpy settings-page option and are never stored in NetSpy β the login form only compares what you type against them. Without both variables set the tab shows a hint instead of a login (terminals stay off); the rest of the dashboard stays open either way. Log in once per browser session; a logout button is in the tab header.http://<host-ip>:<port>
β οΈ Requirements:
network_mode: host(the sampler needs the host's/procandss) and root (host PID namespace,/proc/<pid>reads, optional Docker socket β there is no non-root mode). Ports are set viaWEB_PORT/AGENT_PORTβ with host networking the value is the host port.
| You want to⦠| Do this |
|---|---|
| Install on Unraid | It's in the Unraid Community App Store: Apps β NetSpy β Install. Set SERVERS (e.g. Main=local) and AGENT_TOKEN; everything else has sensible defaults. |
| Add an agent (TrueNAS/Debian/β¦) | Copy docker-compose.yml to that host β set ROLE: agent, SERVERS: "", UPLINK (e.g. eth0), same AGENT_TOKEN. On TrueNAS also uncomment security_opt: [apparmor:unconfined] (minimal relaxation, no privileged). Deploy via Portainer stack or docker compose up -d. |
| Prefer Docker Hub? | The image is mirrored to docker.io/thefirstmojo/netspy β same manifest as GHCR (vX.Y, beta, latest). Pull from either registry. |
All settings stay editable later under Docker β NetSpy β edit. Pin the image tag (ghcr.io/thefirstmojo/netspy:vX.Y) for deterministic updates; with :latest tick "Pull latest image" when updating.
All values live directly in docker-compose.yml β no .env file.
| Key | Default | Description |
|---|---|---|
ROLE | web | web (UI + sampler) or agent (sampler only) |
SERVERS | Main=local (optional) | Name=local;Name=http://host:8091 β semicolon-separated. Optional: if unset or empty, a local server (Main=local) is added automatically on first start |
UPLINK | auto (default route) | Comma-separated override, e.g. br0,bond0 |
TZ | UTC | Container timezone, e.g. Europe/Berlin (v0.7.35+, tzdata ships in the image). Decides when the storage history closes its day and month (local midnight instead of 02:00 with UTC) and the zone of all timestamps. Without tzdata the variable would be silently ignored β hence it is part of the image |
WEB_PORT / AGENT_PORT | 8090 / 8091 | Host ports (host networking β the values ARE the external ports) |
AGENT_TOKEN | empty | Shared X-Agent-Token header β must match on all hosts |
TTYD_USER | empty | Terminal tab login β username (v0.7.12+). Container env var only β never stored in NetSpy, no settings-page option. Set both TTYD_USER + TTYD_PASS β the Terminal tab shows a login form and unlocks with these credentials |
TTYD_PASS | empty | Terminal tab login β password (v0.7.12+). Container env var only β never stored in NetSpy. Both empty (TTYD_USER + TTYD_PASS) β terminals stay disabled (tab shows a hint); the rest of the dashboard stays open |
DOCKER_SOCK | /var/run/docker.sock (web) | Docker socket for per-container rows; "" disables |
CONFIG_DIR | auto-detected | Volume for servers.yaml β /netspy mount β /netspy/config |
Plus two commented blocks in the compose, enabled per host: AppArmor (security_opt: [apparmor:unconfined], hosts that enforce it) and the Docker socket volume.
Unraid 10.10.10.10 TrueNAS 10.10.10.20
ββββββββββββββββββββββββββββββββ βββββββββββββββββββββββββββ
β netspy (ROLE=web) β HTTP β netspy (ROLE=agent) β
β :8090 Web UI ββββββββββΊβ :8091 /api/metrics β
β :8091 /api/metrics β poll β /proc + ss (inet_diag) β
ββββββββββββββββββββββββββββββββ βββββββββββββββββββββββββββ
The web instance polls every agent once per second; agents never initiate connections. An unreachable agent is simply marked offline β the rest keeps working.
AGENT_TOKEN (as X-Agent-Token) is the only access control and does not encrypt anything. LAN / trusted network only; don't expose ports 8090/8091 without a VPN or TLS reverse proxy. The token is never written to logs.cap_drop: [ALL] with only SYS_PTRACE added, Docker socket read-only and off by default./proc and ss of all processes (incl. root daemons like smbd): socket attribution, /proc/<pid>/io, /proc/<pid>/stat. Reading another user's proc files needs root; PUID/PGID 99:100 would silently produce empty lists. There is no non-root mode.The settings page writes servers.yaml into the mounted volume. As root without CAP_DAC_OVERRIDE, the container can only write into world-writable directories β so make the mounted base directory world-writable once (the container creates subfolders 0777 and files 0666 itself, so you can still edit them):
chmod 777 /mnt/user/appdata/netspy # Unraid
chmod 777 /opt/netspy # other hosts
β οΈ Do NOT add
--cap-add=DAC_OVERRIDEto fix this β that capability lets the root container bypass all file permission checks, including on every other mounted directory. Fix the folder permissions instead.
/proc/net/dev deltas; "total traffic" = the interface(s) with the default route (auto-detected β br0 on Unraid, eth0/bond0 elsewhere).ss -tinpe per socket inode, deltas aggregated by process, capped at the physical link rate (no impossible artifacts). UDP and kernel traffic (nfsd/kworker) land in the row "not assigned (kernel/UDP)".binhex-*) share the host netns and deliberately get no badge (indistinguishable from host processes)./proc/<pid>/io deltas β storage-layer bytes incl. network filesystems, EMA-smoothed.Known limits: TCP only per process (UDP/kernel β "not assigned") Β· 1 s sampling averages short bursts.
docker build -t netspy:latest . # then use image: netspy:latest in the compose
Backend tests need nothing but Python (no browser, no services):
python3 test_backend_units.py # API payload, polling, storage history, config, terminal targets
python3 app/agent.py --selftest # parser fixtures (ss / route table)
DOM tests render the real app/static in Chromium (Playwright) and check the
terminal tab, the command list tooltip, the filter chips and the resize/auto-scroll
behaviour β run each script directly: python3 test_cmdlist.py,
test_filter_audit.py, test_resize_autoscroll.py, test_terminal_suggested.py.
Provided "as is", without warranty of any kind. Use at your own risk.
Content type
Image
Digest
sha256:04e0e5e15β¦
Size
55.4 MB
Last updated
21 days ago
docker pull thefirstmojo/netspy