Application Information

Application: scanopy
GitHub Repository: https://github.com/scanopy/scanopy
GitHub Packages: https://github.com/orgs/scanopy/packages?repo_name=scanopy
Template Repository: https://github.com/stefan-matic/unraid-templates
Category: Network, Tools, Productivity

---

Description

Scanopy automatically discovers and visually documents your network topology. It scans your network, identifies hosts and services, and generates an interactive visualization showing how everything connects, making it easy to create and maintain living network documentation.

Key Features:

• 🔍 Automatic Network Discovery - Scans all IPv4 addresses on connected subnets

• 🎯 Service Detection - Recognizes 50+ common services (Plex, Home Assistant, Docker, Proxmox, pfSense, and more)

• 🗺️ Interactive Topology Visualization - Visual map of your entire network infrastructure

• 🏢 Multi-VLAN Support - Deploy multiple daemons to map complex network topologies

• 🐳 Container-Aware - Automatically detects Docker services and relationships

• 📊 Infrastructure Mapping - Identifies DNS, gateways, reverse proxies, and other infrastructure services

• 🔒 Privacy First - All data stored locally, no external services

---

Architecture

Scanopy uses a server-daemon architecture:

1. Scanopy Server - Central hub that stores network data, generates visualizations, and serves the web UI. Includes PostgreSQL database.

2. Scanopy Daemon - Lightweight agent that performs network scanning and reports to the server. Deploy on multiple hosts to map different network segments.

---

Installation

Prerequisites

• Unraid 6.9+ recommended

• Host networking support for daemon container

• Sufficient system resources (scanning can be resource-intensive)

Installation Steps

1. Install Scanopy Server (Required)

   • Search for "Scanopy Server" in Community Applications or template list

   • Configure the WebUI port (default: 60072)

   • Click Apply

   • Wait for the container to start and initialize the database

2. Install Scanopy Daemon (Required)

   • Search for "Scanopy Daemon" in Community Applications or template list

   • IMPORTANT: Set SCANOPY_SERVER_TARGET to your Unraid server IP

   • The daemon requires --privileged and --network=host to scan the network

   • Click Apply

3. Access the WebUI

   • Navigate to http://YOUR-UNRAID-IP:60072

   • Initialize your network with seed data

   • Click the discovery button to start scanning

---

Configuration

Scanopy Server

Parameter	Default	Description
WebUI Port	60072	Port to access the Scanopy web interface
Database	PostgreSQL	Automatically configured with docker-compose
Log Level	info	Logging verbosity (trace, debug, info, warn, error)

Scanopy Daemon

Parameter	Environment Variable	Default	Description
Server Target	SCANOPY_SERVER_TARGET	Required	IP address of your Unraid server running Scanopy Server
Server Port	SCANOPY_SERVER_PORT	60072	Port the Scanopy server is listening on
Daemon Port	SCANOPY_DAEMON_PORT	60073	Port for daemon to listen on
Daemon Name	SCANOPY_NAME	scanopy-daemon	Human-readable name for this daemon
Concurrent Scans	SCANOPY_CONCURRENT_SCANS	15	Max hosts to scan in parallel
Heartbeat Interval	SCANOPY_HEARTBEAT_INTERVAL	30	Seconds between heartbeat updates
Log Level	SCANOPY_LOG_LEVEL	info	Logging verbosity

Performance Tuning

The SCANOPY_CONCURRENT_SCANS setting controls how many hosts are scanned simultaneously:

• Low-resource systems (Raspberry Pi): 5-10

• Developer laptops: 15-20

• Docker containers: 10-30 (depends on memory limits)

• Servers/Unraid: 25-50

If you experience high memory usage, reduce this value.

---

Docker Socket Access (Optional but Recommended)

To enable enhanced Docker service discovery:

1. Edit the Scanopy Daemon container

2. Add volume mapping: /var/run/docker.sock → /var/run/docker.sock

3. This allows the daemon to detect:

   • Container names and metadata

   • Service-to-container relationships

   • Internal Docker networks

   • Container ports and exposed services

---

Usage Guide

Starting Your First Discovery

1. Access the WebUI at http://YOUR-UNRAID-IP:60072

2. A host entry will appear for your daemon

3. Click the Discovery button to start scanning

4. Note: Discovery can take 5-10+ minutes depending on subnet size and network mask

Discovery Process

The daemon will:

• Scan all IPv4 addresses on connected subnets

• Detect running services using pattern matching

• Map network interfaces and subnet relationships

• Identify infrastructure services (DNS, gateways, proxies)

Network Organization

• Subnets: Automatically created during discovery

• Groups: Create logical connections between services (e.g., web app → database)

• Consolidate Hosts: Merge duplicate host entries that represent the same physical device

• Infrastructure Services: Automatically flags DNS, gateway, and proxy hosts

Visualization Customization

• Anchor Points: Click edges to change connection points on nodes

• Subnet Sizing: Drag subnet boundaries to resize

• Layout: Drag hosts and subnets to organize your topology

• Changes persist across sessions

---

Multi-VLAN Setup

To map networks across VLANs:

1. Deploy a Scanopy Daemon on a host in each VLAN

2. Configure each daemon's SCANOPY_SERVER_TARGET to point to your server

3. Run discovery from each daemon

4. Use the Consolidate feature to merge hosts detected from multiple perspectives

NOTE: If you network setup allows to have UNRAID reach out to every other VLAN then this will work out of the box

---

Detected Services

Scanopy automatically detects 50+ services including:

• Media: Plex, Jellyfin, Emby

• Home Automation: Home Assistant, Philips Hue Bridge

• Virtualization: Proxmox, Docker, Kubernetes

• Network: Pi-hole, AdGuard Home, Unifi Controller, pfSense, OPNsense

• Storage: Synology, QNAP, TrueNAS, Nextcloud

• Monitoring: Grafana, Prometheus, Uptime Kuma

• Reverse Proxies: Nginx Proxy Manager, Traefik, Cloudflared

For the complete list, see the service definitions.

---

Troubleshooting

Daemon Can't Connect to Server

• Verify SCANOPY_SERVER_TARGET is set to the correct IP

• Check that port 60072 is accessible (firewall rules)

• Ensure both containers are on the same network or can communicate

High Memory Usage

• Reduce SCANOPY_CONCURRENT_SCANS value

• Start with 10-15 and adjust based on available resources

Discovery Takes Too Long

• This is normal for large subnets (e.g., /24 = 254 hosts to scan)

• Adjust SCANOPY_CONCURRENT_SCANS higher if you have resources

Service Not Detected

• Check if the service is in the supported list

• Open an issue on GitHub to request new service detection

Container Won't Start (Daemon)

• Ensure the container has --privileged flag enabled

• Verify --network=host is set

• Check Unraid logs: docker logs scanopy-daemon

---

Privacy & Security

• All data is stored locally in PostgreSQL on your Unraid server

• No data is sent to external services

• Communication between daemon and server occurs over your local network only

• The daemon requires privileged access to scan network interfaces

---

Support

If you need help or encounter issues, please post in this thread with:

1. Unraid version

2. Scanopy Server version (check container logs)

3. Scanopy Daemon version (check container logs)

4. Description of the issue

5. Relevant logs (use docker logs scanopy-server or docker logs scanopy-daemon)

6. Network setup (e.g., multiple VLANs, subnet sizes)

For bugs or feature requests, you can also open an issue on the GitHub repository.

---

FAQ

Q: Does this work with IPv6?
A: Not currently. Future plans include collecting IPv6 addresses during discovery, but full IPv6 subnet scanning will not be supported.

Q: Can I map multiple VLANs?
A: Yes! Deploy a daemon on a host in each VLAN. Use the Consolidate feature to merge duplicate host entries.

Q: Is my data sent anywhere?
A: No. All data stays local on your Unraid server. No external communication occurs.

Q: How do I add a service that's not detected?
A: Open an issue on GitHub with details about the service.

Q: Can I run multiple daemons?
A: Yes! This is designed for multi-VLAN environments. Each daemon gets its own name and reports to the same server.

---

Changelog

Version 1.3.0

• Update variables to match new update

• Add new Push/Pull mechanism for daemon

Version 1.2.0

• Project renamed from Netvisor to Scanopy

Version 1.1.0

• Logo update

• Support thread link update

Version 1.0.0 (Initial Release)

• Scanopy Server template

• Scanopy Daemon template

• Automatic network discovery

• Interactive topology visualization

• Support for 50+ service types

• Multi-daemon/Multi-VLAN support

---

Links

• GitHub: https://github.com/mayanayza/netvisor

• Template Repository: https://github.com/stefan-matic/unraid-templates

• Service Definitions: https://github.com/scanopy/scanopy/tree/main/backend/src/server/services/definitions

Edited January 10Jan 10 by Fallen94
Remove post move note

Installation of NetVisor Server didn't go as expected.

Error: error with configuration: relative URL without a base

Caused by:

relative URL without a base

Relates to the 'NETVISOR_DATABASE_URL' parameter, which is empty.

5 hours ago, Epoustoufflante said:

Installation of NetVisor Server didn't go as expected.

Error: error with configuration: relative URL without a base

Caused by:

relative URL without a base

Relates to the 'NETVISOR_DATABASE_URL' parameter, which is empty.

The error you're seeing is because the database url is not supplied.
I supplied a generic url example, which needs to be filled out with your database info.

Let's debate further at https://github.com/mayanayza/netvisor/issues/13#issuecomment-3523486394

I'm trying to start the server container but I always get the error I'm attaching:

21 hours ago, zichichi said:

I'm trying to start the server container but I always get the error I'm attaching:

21 hours ago, zichichi said:

I'm trying to start the server container but I always get the error I'm attaching:

I have been having the same invalid port error as well. I have tested deploying this in portainer and in Unraid Docker-compose and get the same error. I have been troubleshooting with I believe the Dev on discord but have not gotten far.

i geht this error

1 hour ago, netconnect said:

i geht this error

I got this error when I did not enter the postgres url correctly.

1 hour ago, bbronz3 said:

Ho ricevuto questo errore quando non ho inserito correttamente l'URL del postgres.

Don't you get a port error when booting? Could you post your configuration? Thanks.

39 minutes ago, zichichi said:

Don't you get a port error when booting? Could you post your configuration? Thanks.

Yes I am also getting the invalid port error. I attached a Yaml of the Docker-Compose I am running. According to the main Dev I shouldnt be having any issues

scanopy.yaml

Someone needs to fix the unraid docker template for the daemon- it is a little bit wrong. Make sure you guys remove the port from the server target. @bbronz3
The server target should just be the root of your server as the port will get filled from the port variable below it. Refer to my screenshot example of what it should be.

Edited December 22, 2025Dec 22 by bucatini

12 hours ago, bucatini said:

Someone needs to fix the unraid docker template for the daemon- it is a little bit wrong. Make sure you guys remove the port from the server target. @bbronz3
The server target should just be the root of your server as the port will get filled from the port variable below it. Refer to my screenshot example of what it should be.

Thank you for the reply! I tried what you suggested but am still getting invalid port number error @bucatini

Edited December 23, 2025Dec 23 by bbronz3

@bbronz3
Why did you add the ' SCANOPY_PUBLIC_URL' = 'http:/ / localhost : 60072' ??
There seems to be an extra space at the beginning of that variable too - but you must have added it because the template doesn't come with that.
Refer to mine

On 12/20/2025 at 9:20 AM, zichichi said:

I'm trying to start the server container but I always get the error I'm attaching:

Your integrated Daemon URL is most likely wrong. Read the comment in the field for what should be there. It should be whatever your docker bridge gateway is - which it should auto fill. So maybe reset the template back to default?

@bucatini

I added SCANOPY_PUBLIC_URL variable because the Dev asked me to during troubleshooting. I have been messing with this all day so I apologize if you see another typo. I adjusted to your pic but I am still getting the invalid port error

Hold On I see another mistake

@bucatini

Did it work? Add me on discord and I can help you "bucatinini"

ok so I have server and daemon working.

but... daemon cannot see normal host network... even though daemon is on HOST network.
Unraid HOST is showing the 192.168.1.12 interface, the subnet br0 192.168.1.0/24

no errors in logs for server, nor daemon

daemon in server shows "no" interfaces this time. previously with other settings had something here. but still no network devices discovered then either.

just WARN (seems irrelevant)

2025-12-24T00:20:33.114083Z INFO scanopy::daemon::discovery::manager: Discovery completed successfully

2025-12-24T00:20:33.114462Z WARN scanopy::daemon::discovery::service::network: Skipping 172.31.200.0/24 with CIDR 172.31.200.0/24, docker bridge subnets are scanning in docker discovery

2025-12-24T00:20:33.114474Z WARN scanopy::daemon::discovery::service::network: Skipping 172.21.0.0/16 with CIDR 172.21.0.0/16, docker bridge subnets are scanning in docker discovery

2025-12-24T00:20:33.114480Z WARN scanopy::daemon::discovery::service::network: Skipping 172.17.0.0/16 with CIDR 172.17.0.0/16, docker bridge subnets are scanning in docker discovery

2025-12-24T00:20:33.114484Z WARN scanopy::daemon::discovery::service::network: Skipping 172.20.0.0/16 with CIDR 172.20.0.0/16, docker bridge subnets are scanning in docker discovery

2025-12-24T00:20:33.114489Z WARN scanopy::daemon::discovery::service::network: Skipping 172.19.0.0/16 with CIDR 172.19.0.0/16, docker bridge subnets are scanning in docker discovery

2025-12-24T00:20:33.114494Z WARN scanopy::daemon::discovery::service::network: Skipping 172.18.0.0/16 with CIDR 172.18.0.0/16, docker bridge subnets are scanning in docker discovery

2025-12-24T00:20:33.119982Z INFO scanopy::daemon::discovery::service::base: Starting Network Discovery discovery session aacb2573-22c0-42bf-b444-44086326803c

Then when Netowork scan starts:

bf-b444-44086326803c discovery_type=Network { subnet_ids: None, host_naming_fallback: BestService }

2025-12-24T00:20:33.160259Z INFO scanopy::daemon::discovery::service::network: Phase 1: Checking host responsiveness total_ips=768 interfaced_ips=512 non_interfaced_ips=256

2025-12-24T00:20:33.163347Z INFO scanopy::daemon::discovery::service::network: Phase 1a: ARP scanning interfaced subnets count=512 concurrency=50

2025-12-24T00:20:44.150887Z INFO scanopy::daemon::runtime::service: Heartbeat sent daemon_id=e4383ce9-08c5-46ab-8597-d4e3450644a3

2025-12-24T00:21:03.140851Z INFO scanopy::daemon::shared::handlers: Received healthcheck request

2025-12-24T00:21:14.146151Z INFO scanopy::daemon::runtime::service: Heartbeat sent daemon_id=e4383ce9-08c5-46ab-8597-d4e3450644a3

2025-12-24T00:21:33.206850Z INFO scanopy::daemon::shared::handlers: Received healthcheck request

2025-12-24T00:21:44.145211Z INFO scanopy::daemon::runtime::service: Heartbeat sent daemon_id=e4383ce9-08c5-46ab-8597-d4e3450644a3

2025-12-24T00:22:03.279161Z INFO scanopy::daemon::shared::handlers: Received healthcheck request

5 min later

no error in log

Edited December 24, 2025Dec 24 by TRusselo

and... I tried to install daemon on my linux-PC (im new to linux as a daily driver)

what does this mean "your parameters"

Edited December 24, 2025Dec 24 by TRusselo

On 12/21/2025 at 4:35 PM, bbronz3 said:

Yes I am also getting the invalid port error. I attached a Yaml of the Docker-Compose I am running. According to the main Dev I shouldnt be having any issues

scanopy.yaml

@zichichi if you didnt figure this out, try making sure your postgres url is correct. I the port back to 5432 and that produced a new error which I was able to fix after adjusting my URL

18 hours ago, TRusselo said:

ok so I have server and daemon working.

but... daemon cannot see normal host network... even though daemon is on HOST network.
Unraid HOST is showing the 192.168.1.12 interface, the subnet br0 192.168.1.0/24

no errors in logs for server, nor daemon

daemon in server shows "no" interfaces this time. previously with other settings had something here. but still no network devices discovered then either.

just WARN (seems irrelevant)

2025-12-24T00:20:33.114083Z INFO scanopy::daemon::discovery::manager: Discovery completed successfully

2025-12-24T00:20:33.114462Z WARN scanopy::daemon::discovery::service::network: Skipping 172.31.200.0/24 with CIDR 172.31.200.0/24, docker bridge subnets are scanning in docker discovery

2025-12-24T00:20:33.114474Z WARN scanopy::daemon::discovery::service::network: Skipping 172.21.0.0/16 with CIDR 172.21.0.0/16, docker bridge subnets are scanning in docker discovery

2025-12-24T00:20:33.114480Z WARN scanopy::daemon::discovery::service::network: Skipping 172.17.0.0/16 with CIDR 172.17.0.0/16, docker bridge subnets are scanning in docker discovery

2025-12-24T00:20:33.114484Z WARN scanopy::daemon::discovery::service::network: Skipping 172.20.0.0/16 with CIDR 172.20.0.0/16, docker bridge subnets are scanning in docker discovery

2025-12-24T00:20:33.114489Z WARN scanopy::daemon::discovery::service::network: Skipping 172.19.0.0/16 with CIDR 172.19.0.0/16, docker bridge subnets are scanning in docker discovery

2025-12-24T00:20:33.114494Z WARN scanopy::daemon::discovery::service::network: Skipping 172.18.0.0/16 with CIDR 172.18.0.0/16, docker bridge subnets are scanning in docker discovery

2025-12-24T00:20:33.119982Z INFO scanopy::daemon::discovery::service::base: Starting Network Discovery discovery session aacb2573-22c0-42bf-b444-44086326803c

Then when Netowork scan starts:

bf-b444-44086326803c discovery_type=Network { subnet_ids: None, host_naming_fallback: BestService }

2025-12-24T00:20:33.160259Z INFO scanopy::daemon::discovery::service::network: Phase 1: Checking host responsiveness total_ips=768 interfaced_ips=512 non_interfaced_ips=256

2025-12-24T00:20:33.163347Z INFO scanopy::daemon::discovery::service::network: Phase 1a: ARP scanning interfaced subnets count=512 concurrency=50

2025-12-24T00:20:44.150887Z INFO scanopy::daemon::runtime::service: Heartbeat sent daemon_id=e4383ce9-08c5-46ab-8597-d4e3450644a3

2025-12-24T00:21:03.140851Z INFO scanopy::daemon::shared::handlers: Received healthcheck request

2025-12-24T00:21:14.146151Z INFO scanopy::daemon::runtime::service: Heartbeat sent daemon_id=e4383ce9-08c5-46ab-8597-d4e3450644a3

2025-12-24T00:21:33.206850Z INFO scanopy::daemon::shared::handlers: Received healthcheck request

2025-12-24T00:21:44.145211Z INFO scanopy::daemon::runtime::service: Heartbeat sent daemon_id=e4383ce9-08c5-46ab-8597-d4e3450644a3

2025-12-24T00:22:03.279161Z INFO scanopy::daemon::shared::handlers: Received healthcheck request

5 min later

no error in log

there was an update overnight. not much changed except my daemon now shows 2 interfaces, neither are the host network that the daemon exists on 192.168.1.0/24

.

Edited December 24, 2025Dec 24 by TRusselo

The project received a lot of updates since the last time i packaged this.

Need to bring the template up to date and then troubleshoot why it doesn't scan the host network properly.

Will report bacl once it's working

On 12/27/2025 at 2:12 PM, Fallen94 said:

The project received a lot of updates since the last time i packaged this.

Need to bring the template up to date and then troubleshoot why it doesn't scan the host network properly.

Will report bacl once it's working

Hi,

thanks for your work - Maybe put a disclaimer at the very top, i've been trying to get it to scan for the last hour. I enabled debug mode on the server and i am getting the following:

2026-01-03T16:31:48.143630Z DEBUG scanopy::server::discovery::service: Updated session session_id=6a66748a-2473-4bf1-ae2c-23d7d441e72c phase=Discovery complete progrsss=100
2026-01-03T16:31:48.144155Z ERROR scanopy::server::discovery::service: Failed to create historical discovery record for session 6a66748a-2473-4bf1

There is stuff in the sql db, so not sure whats happening or not happening.

Trying to install this, and it's asking for "Database URL:" in the template, but the instructions on this page say postgres is part of the container? do I need to supply my own instance, or not?