Scanopy: Auto-Discovering Network Diagrams for Self-Hosted Infrastructure

The Problem Scanopy Addresses

Network diagrams drawn in tools like draw.io go stale quickly. The README states the problem directly: a diagram drawn manually is outdated the week it is saved. Infrastructure-as-code state files describe what was deployed but miss drift and resources provisioned outside the pipeline. Neither source gives you a current picture of what is actually running.

Scanopy addresses this by continuously scanning the network on a schedule and building a model from what it finds, rather than from what was intended to be deployed. Because the daemon runs repeatedly, the diagrams it produces reflect the current state rather than a historical snapshot.

The four views produced from each scan cover different perspectives on the same infrastructure: L2 (physical) shows every switch, every port, and every link; L3 (logical) shows subnets and how hosts connect across them; workloads maps bare metal, hypervisors, and containers; applications shows services and their dependencies, grouped by application. These four views come from a single scan pass rather than four separate discovery runs.

Discovery Mechanism: SNMP, LLDP, ARP, and Docker

The daemon discovers hosts and services by scanning the network. The README describes the approach as one scanner with no per-device agents. Discovery uses SNMP and LLDP for network hardware topology, ARP for host identification, and the Docker socket for containerized services.

Scanopy includes over 230 service definitions for automatic detection. These cover databases, web servers, containers, network infrastructure, and enterprise applications. When a host exposes a known port or protocol, the daemon identifies the service type without needing any configuration on the discovered host.

For networks with multiple VLANs or multiple physical sites, Scanopy supports distributed scanning. You deploy daemon instances across network segments, and they report back to the central server. The server assembles the results into a unified topology model.

The Docker Compose deployment mounts /var/run/docker.sock as a read-only volume on the daemon container, which is what enables Docker service discovery. The comment in the docker-compose.yml is explicit: removing that volume mount disables Docker discovery. The daemon also runs in host network mode and with privileged access, which is required for low-level network scanning.

Self-Hosting with Docker Compose

The quickest way to run Scanopy is with Docker Compose:

curl -O https://raw.githubusercontent.com/scanopy/scanopy/refs/heads/main/docker-compose.yml
docker compose up -d

This pulls three containers: the daemon, a postgres:17-alpine database, and the server. The server listens on port 60072. After the stack starts, open http://your-server-ip:60072 in a browser, create your account, and wait for the first discovery scan to complete.

The .env.example file in the repository documents the environment variables. The critical ones for a minimal deployment are:

SCANOPY_DATABASE_URL=postgresql://postgres:password@localhost:5432/scanopy
SCANOPY_PUBLIC_URL=http://your-domain.com:60072
SCANOPY_LOG_LEVEL=info

For HTTPS, set SCANOPY_USE_SECURE_SESSION_COOKIES=true. SMTP email (for password reset and notifications) requires all four of SCANOPY_SMTP_RELAY, SCANOPY_SMTP_USERNAME, SCANOPY_SMTP_PASSWORD, and SCANOPY_SMTP_EMAIL to be set; if any of the four is missing, email stays disabled. Every SMTP connection is encrypted; there is no plaintext mode.

Scanopy is also available as a Proxmox LXC via a community helper script, and as an Unraid community app. The installation guide at scanopy.net/docs covers additional options.

Four Views from One Scan

The L2 physical view shows every switch, every port, and every physical link discovered via SNMP and LLDP. This is useful for network engineers who need to trace cabling or identify which physical switch port a host is connected to without walking the floor.

The L3 logical view shows subnets and how hosts connect across them. Platform and DevOps teams use this to understand the routing between services without needing to consult a network engineer.

The workloads view maps bare metal servers, hypervisors, and containers. For environments that mix physical servers, VMs, and container workloads, this provides a single view across all three layers.

The applications view groups services by application and shows their dependencies. The README describes this as services and their dependencies, grouped by application. This view is what a team uses when they need to answer "if this database goes down, which services are affected?"

Scanopy can export any view as SVG, Mermaid, or Confluence format. You can also embed live maps and feed the topology model into an existing source of truth. Multi-user access with role-based access control lets you share live views with teammates or external stakeholders.

For teams that do not want to self-host, Scanopy Cloud at scanopy.net offers the same feature set on hosted infrastructure.

AGPL-3.0 License and the Commercial Option

The self-hosted version is released under AGPL-3.0. AGPL extends the GPL copyleft requirement to network services: if you run a modified version of Scanopy as a network service and others can access it, you must make your modified source code available to those users. For most teams running Scanopy internally for their own infrastructure documentation, this is not a constraint. For teams that want to offer Scanopy as part of a managed service product, or that cannot comply with AGPL terms for other reasons, a commercial license is available by contacting [email protected].

Scanopy Cloud is a hosted subscription product for teams that want zero infrastructure management.

The recent release history shows active development: v0.17.17 was published on 2026-09-24, v0.17.16 on 2026-09-16, and v0.17.15 on 2026-09-15. The last push to the repository was on 2026-09-26.

Limitations and When Scanopy Is Not the Right Fit

Scanopy documents topology and service dependencies from network-level discovery. It does not profile application performance, collect distributed traces, measure latency, or aggregate logs. For teams that need to understand slow database queries, service error rates, or the trace of a single request through a microservice stack, Scanopy does not provide that information. It tells you what is connected to what, not how well those connections are performing.

The daemon requires host network mode and privileged access in Docker, which some security-conscious environments restrict. The docker.sock mount for Docker discovery is read-only but still represents a privilege escalation risk in container environments with strict isolation requirements.

For teams that want a diagram-only tool without the scanning daemon, draw.io is the standard manual diagramming tool. Draw.io lets you create network diagrams by hand with full control over the diagram content. The trade-off the README identifies is that manually drawn diagrams go stale; Scanopy's auto-discovery is its primary advantage over draw.io.

The 230+ service definitions cover a broad range, but the README notes contributions are welcome for adding new service definitions. If your infrastructure uses unusual services not yet in the catalog, discovery may be incomplete until the definitions are added.

Editorial conclusion

Scanopy is the right fit for platform teams, network engineers, and MSPs who need network documentation that stays accurate as infrastructure changes, without drawing diagrams by hand. It is not the right tool for teams that need APM traces, distributed tracing, or deep application performance metrics; Scanopy documents topology and dependencies, not request flows. Before deploying, check whether AGPL-3.0 copyleft terms are compatible with your use case, and confirm that your environment allows the daemon to run in host network mode with the docker.sock mounted if you want Docker discovery.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. scanopy/scanopy on GitHub