Scanopy: Auto-Generate Interactive Network Diagrams

Clean network diagrams. One-time setup, zero upkeep. This isn't just another tagline—it's a revolutionary promise that's transforming how developers, sysadmins, and IT professionals document their infrastructure. If you've ever spent hours manually updating Visio diagrams or wrestling with spreadsheet inventories, you know the pain. Scanopy eliminates that pain entirely.

Network documentation has always been the chore we love to hate. It’s tedious, error-prone, and outdated the moment you finish. Modern environments—especially home labs, enterprise networks, and containerized deployments—change constantly. Scanopy solves this by automatically discovering your hosts, services, and relationships, then rendering them into beautiful, interactive visualizations that update themselves.

In this deep dive, you'll discover how Scanopy works, why it's trending in DevOps circles, and how to deploy it in minutes. We'll explore real-world use cases, walk through actual code examples from the repository, and compare it against alternatives. By the end, you'll understand why this tool is becoming essential for anyone managing complex networks.

What Is Scanopy and Why It's Revolutionizing Network Documentation

Scanopy is an open-source network mapping and visualization platform that automatically scans your infrastructure, identifies hosts and services, and generates interactive diagrams showing how everything connects. Built with ❤️ in NYC and released under AGPL-3.0, it's designed for the modern era of dynamic, distributed systems.

The project emerged from a simple frustration: existing network documentation tools either require manual input (like Draw.io or Lucidchart) or provide overwhelming data dumps without clear visualization (like traditional SNMP monitors). Scanopy bridges this gap by combining automatic discovery with intuitive, interactive topology maps.

At its core, Scanopy uses a distributed architecture. A lightweight daemon runs on each network segment, performing active and passive scanning to identify devices, open ports, and running services. These daemons report back to a central server that aggregates the data and serves a web-based UI where you can explore your network topology in real-time.

What makes Scanopy particularly powerful is its 200+ built-in service definitions. It doesn't just detect "something on port 5432"—it recognizes PostgreSQL, knows its typical configuration, and can even identify related services like PgBouncer or replication peers. This intelligence extends to web servers, containers, databases, monitoring tools (Prometheus, Grafana), and enterprise applications.

The tool has gained rapid traction because it addresses a universal pain point. Home lab enthusiasts document their ever-growing rack setups. System administrators finally get accurate VLAN visualizations. DevOps teams map microservice dependencies automatically. Managed Service Providers (MSPs) use its multi-tenant features to manage dozens of client networks from a single pane of glass.

With over 2000+ GitHub stars and growing Discord community, Scanopy is becoming the go-to solution for automated network documentation. The recent addition of Scanopy Cloud offers a hosted solution for teams that prefer zero infrastructure management.

Key Features That Make Scanopy Essential

Automatic Discovery Engine

Scanopy's discovery engine goes beyond simple ping sweeps. It employs multiple techniques:

• ARP table inspection for Layer 2 visibility
• mDNS/Bonjour detection for consumer devices and IoT
• SNMP probing for enterprise equipment
• Docker API integration for containerized environments
• Passive traffic analysis to catch ephemeral services

This multi-pronged approach ensures comprehensive coverage, even in complex segmented networks where traditional tools miss devices.

200+ Intelligent Service Definitions

The service recognition database is Scanopy's secret weapon. Each definition includes:

• Port signatures with protocol detection
• Banner parsing for version identification
• Relationship heuristics (e.g., linking web apps to their databases)
• Icon mapping for visual representation
• Health check endpoints where applicable

From Home Assistant instances to Kubernetes API servers, from Redis clusters to Proxmox VE nodes, Scanopy recognizes them all and renders them with appropriate icons and metadata.

Interactive Topology Visualization

The web UI, built with modern React and D3.js, provides:

• Drag-and-drop layout adjustments that persist
• Real-time traffic animations showing data flow
• Filter by service type, VLAN, or custom tags
• Zoom from data center view to individual containers
• Export to PNG/SVG for documentation
• Time-lapse views showing network evolution

Distributed Scanning Architecture

For enterprise networks, Scanopy's daemon model shines:

• Deploy lightweight containers (~50MB) on each VLAN
• Encrypted communication back to central server
• Bandwidth-aware scanning to avoid network impact
• Scan scheduling to distribute load
• Hierarchical aggregation for global topology views

Docker-Native Integration

Scanopy automatically discovers:

• Running containers via Docker socket
• Docker Compose stacks by inspecting labels
• Swarm services and their overlay networks
• Kubernetes pods (when daemon runs as DaemonSet)
• Container relationships based on network connections

Enterprise-Grade Access Control

The organization management system features:

• Multi-tenant isolation for MSPs
• RBAC with viewer, editor, and admin roles
• API key management for automation
• Audit logging of all changes
• SAML/OIDC integration for SSO

Set-and-Forget Automation

Scheduled discovery runs via cron-like expressions:

• Incremental scans every 15 minutes
• Full topology rebuilds nightly
• Service-specific deep scans weekly
• Alert on drift when topology changes
• Webhook notifications to Slack/Teams

Real-World Use Cases Where Scanopy Shines

Home Lab Documentation That Keeps Itself Updated

You've got a Raspberry Pi running Pi-hole, a NAS with Plex, a Proxmox cluster, and a dozen Docker containers. Every time you add a new service, your documentation falls behind. Scanopy solves this by running as a container on your main server, automatically detecting new VMs, containers, and devices. When you spin up that new Home Assistant container, it appears on your diagram within minutes, properly connected to your MQTT broker and database.

Enterprise Multi-VLAN Network Management

A financial institution runs 50+ VLANs across three data centers. Their CMDB is perpetually outdated. By deploying Scanopy daemons on each VLAN, they get real-time topology maps showing which servers talk to which databases, how load balancers connect to application tiers, and where monitoring agents are missing. The security team uses this to verify firewall rules and identify unauthorized connections.

DevOps Microservice Dependency Mapping

A cloud-native team runs 200+ microservices across Kubernetes clusters. Service dependencies were documented in a Confluence page last updated six months ago. Scanopy, deployed as a DaemonSet, automatically maps pod-to-pod communications, identifies database dependencies, and visualizes message queue relationships. When a service fails, engineers instantly see what else is impacted.

MSP Multi-Client Network Oversight

A managed service provider supports 30 small businesses. Each client network was documented in separate Visio files. With Scanopy's multi-organization support, they deploy a daemon per client site and manage everything from a single dashboard. Role-based access ensures technicians only see their assigned clients. New device discovery alerts them to unauthorized additions.

Security Audit and Compliance Automation

During a SOC 2 audit, a SaaS company needs to prove network segmentation. Instead of manual diagrams, they provide auditors with time-stamped Scanopy exports showing exactly how production, staging, and development environments are isolated. The interactive nature allows auditors to drill down into specific connections, dramatically speeding up the process.

Step-by-Step Installation & Setup Guide

Prerequisites

Scanopy requires Docker and Docker Compose. You'll need:

• A Linux server (Ubuntu 20.04+, Debian 11+, or CentOS 8+)
• At least 2GB RAM and 2 CPU cores
• Network access to the segments you want to scan
• Port 60072 available for the web UI

Method 1: Docker Compose (Recommended)

This one-command setup gets you running in under two minutes:

# Download the official docker-compose.yml
curl -O https://raw.githubusercontent.com/scanopy/scanopy/refs/heads/main/docker-compose.yml

# Start all services in detached mode
docker compose up -d

# Check logs to verify startup
docker compose logs -f

The compose file launches three services:

• scanopy-server: Central API and database
• scanopy-daemon: Local network scanner
• scanopy-ui: React-based web interface

Method 2: Proxmox LXC Container

For Proxmox users, the community provides a helper script:

# In Proxmox shell, run the community script
bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/scanopy.sh)"

This script creates an unprivileged LXC container with Scanopy pre-configured, ideal for home labs.

Method 3: Unraid Community App

Search for "Scanopy" in the Unraid Community Applications store. The template includes pre-configured paths and port mappings. Just click install and configure your network ranges in the UI.

Initial Configuration

After installation, access the UI at http://<your-server-ip>:60072:

1. Create Admin Account: The first user becomes the organization owner
2. Configure Network Ranges: Add your subnets (e.g., 192.168.1.0/24)
3. Deploy Additional Daemons: For multiple VLANs, run the daemon on each segment:

   docker run -d \
     --name scanopy-daemon-vlan20 \
     --network vlan20 \
     -e SCANOPY_SERVER=https://your-server:60072 \
     -e SCANOPY_TOKEN=your-api-token \
     mayanayza/scanopy-daemon:latest
   

4. Set Scan Schedule: Configure cron expressions for automated discovery
5. Customize Service Definitions: Add proprietary services via the UI

Cloud Trial Alternative

If self-hosting isn't your preference, Scanopy Cloud offers a free trial at scanopy.net. No installation required—just deploy a daemon that connects to their managed service.

REAL Code Examples from the Repository

Example 1: Basic Docker Compose Installation

This is the exact command from Scanopy's README, explained in detail:

# Download the official Docker Compose configuration file
# This file defines all three Scanopy services (server, daemon, UI)
curl -O https://raw.githubusercontent.com/scanopy/scanopy/refs/heads/main/docker-compose.yml

# Launch all services in detached mode (-d)
# Docker will pull images, create networks, and start containers
docker compose up -d

# The -d flag ensures containers run in the background
# Without it, logs would output to your terminal and Ctrl+C would stop everything

What's happening behind the scenes:

• The docker-compose.yml defines a bridge network for inter-service communication
• The server container initializes a PostgreSQL database for topology storage
• The daemon container starts scanning the local Docker network immediately
• The UI container serves the React app on port 60072
• Persistent volumes are created for data retention across restarts

Example 2: Multi-Network Daemon Deployment

For scanning multiple VLANs, you'll deploy additional daemons. Here's a production pattern:

# Deploy daemon on VLAN 10 (Management network)
docker run -d \
  --name scanopy-daemon-mgmt \
  --network vlan10 \
  --restart unless-stopped \
  -e SCANOPY_SERVER=https://scanopy.company.internal:60072 \
  -e SCANOPY_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... \
  -e SCANOPY_NETWORKS=10.0.10.0/24,10.0.11.0/24 \
  mayanayza/scanopy-daemon:latest

# Deploy daemon on VLAN 20 (Production servers)
docker run -d \
  --name scanopy-daemon-prod \
  --network vlan20 \
  --restart unless-stopped \
  -e SCANOPY_SERVER=https://scanopy.company.internal:60072 \
  -e SCANOPY_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... \
  -e SCANOPY_NETWORKS=10.0.20.0/24 \
  mayanayza/scanopy-daemon:latest

Key parameters explained:

• --network vlan10: Attaches the container to a specific Docker network that bridges to your VLAN
• SCANOPY_SERVER: Points to your central Scanopy server (use HTTPS in production!)
• SCANOPY_TOKEN: API token generated from the UI for authentication
• SCANOPY_NETWORKS: Comma-separated list of CIDR blocks to scan from this daemon
• --restart unless-stopped: Ensures the daemon comes back up after host reboots

Example 3: API Query for Network Topology

Scanopy's REST API lets you integrate topology data into other tools. Here's how to fetch all hosts:

import requests
import json

# Set API endpoint and authentication
API_URL = "http://localhost:60072/api/v1"
API_TOKEN = "your-api-token-here"

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

# Get all discovered hosts
response = requests.get(f"{API_URL}/hosts", headers=headers)
hosts = response.json()

# Print discovered services for each host
for host in hosts['data']:
    print(f"Host: {host['hostname']} ({host['ip']})")
    for service in host['services']:
        print(f"  - {service['name']} on port {service['port']}")
        
# Get topology graph for visualization
response = requests.get(f"{API_URL}/topology/graph", headers=headers)
topology = response.json()

# Save to file for external processing
with open('network_topology.json', 'w') as f:
    json.dump(topology, f, indent=2)

Use cases for the API:

• CMDB synchronization: Push discovered assets to your configuration management database
• Custom dashboards: Build Grafana panels showing network topology metrics
• Automation: Trigger Ansible playbooks when new hosts appear
• Compliance: Export daily topology snapshots for audit trails

Example 4: Custom Service Definition

Scanopy's power comes from its service definitions. Here's how to add a proprietary service:

# Save as custom-service.yaml and upload via UI
service_definitions:
  - name: "Acme Payment Gateway"
    ports: [8443, 9443]
    protocol: "tcp"
    banner_patterns:
      - "Acme-Gateway"
      - "payment.acme.com"
    icon: "credit-card"
    category: "application"
    health_check:
      endpoint: "/health"
      method: "GET"
      expected_status: 200
    relationships:
      - type: "depends_on"
        service: "postgresql"
        probability: 0.9

Definition components:

• banner_patterns: Regex to match in service banners during scanning
• icon: Visual representation in the topology map
• health_check: Optional endpoint for service status monitoring
• relationships: Heuristics to auto-draw connection lines to dependencies

Example 5: Scheduled Scan Configuration

Configure automated discovery using cron expressions:

# In Scanopy UI, navigate to Settings > Scan Schedules
# Or via API:

schedule_payload = {
    "name": "Production Network Daily Scan",
    "networks": ["10.0.20.0/24"],
    "daemon": "scanopy-daemon-prod",
    "cron": "0 2 * * *",  # Daily at 2 AM
    "scan_type": "deep",  # Full port scan vs. fast topology
    "notify_on_changes": True,
    "webhook_url": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
}

response = requests.post(
    f"{API_URL}/schedules",
    headers=headers,
    json=schedule_payload
)

Schedule options:

• cron: Standard cron format (minute hour day month weekday)
• scan_type: "fast" for topology-only, "standard" for common ports, "deep" for all ports
• notify_on_changes: Triggers webhook only when topology differs from previous scan
• webhook_url: POSTs JSON payload to Slack, Teams, or custom endpoints

Advanced Usage & Best Practices

Multi-Site Deployment Strategy

For organizations with multiple locations, deploy one daemon per site and use site tags to organize topologies. Create separate Scanopy organizations per business unit, with read-only access for auditors and editor access for network engineers.

Performance Optimization

• Scan throttling: Limit daemon to 50 concurrent connections to avoid overwhelming small devices
• Subnet exclusions: Add printer and IoT VLANs to ignore lists to reduce noise
• Database pruning: Set a 90-day retention policy for old topology snapshots
• SSD storage: Run the server container on SSD for faster graph rendering

Security Hardening

• TLS everywhere: Use Let's Encrypt certificates for the server
• Network policies: Restrict daemon-to-server communication via firewall rules
• API key rotation: Rotate tokens every 90 days using the UI's key management
• Read-only daemons: Run daemons with --read-only filesystem mounts
• Secrets management: Store API tokens in HashiCorp Vault or Docker secrets

Integration Patterns

• Export to NetBox: Use the API to sync discovered devices into NetBox as a source of truth
• Grafana annotations: Create annotations when topology changes occur
• PagerDuty alerts: Trigger incidents when critical services disappear
• GitOps: Commit daily topology exports to Git for change tracking

Comparison: Scanopy vs. Alternatives

Why Choose Scanopy?

• Speed: Running in 2 minutes vs. hours of manual diagramming
• Accuracy: Always up-to-date vs. static, outdated documents
• Intelligence: Recognizes services and relationships automatically
• Scalability: Distributed architecture handles complex networks
• Cost: Free self-hosted option vs. expensive enterprise tools

Frequently Asked Questions

What is Scanopy and how does it work?

Scanopy is an automated network mapping tool that scans your infrastructure, identifies hosts and services, and generates interactive diagrams. It uses distributed daemons for discovery and a central server for visualization, updating automatically on a schedule you define.

How do I install Scanopy?

The fastest method is Docker Compose: curl -O https://raw.githubusercontent.com/scanopy/scanopy/main/docker-compose.yml && docker compose up -d. This launches all three components (server, daemon, UI) in under two minutes. Alternative methods include Proxmox LXC and Unraid Community Apps.

What networks can Scanopy scan?

Scanopy can scan any IP network you have access to: local LANs, VLANs, WANs, and even cloud VPCs (when a daemon is deployed in the cloud environment). It supports IPv4 and IPv6, with bandwidth-aware scanning to avoid disrupting production networks.

Is Scanopy really free?

Yes! The self-hosted version is free under AGPL-3.0. This requires you to disclose source code if you provide network services to others. For commercial use without copyleft requirements, a paid commercial license is available. A hosted cloud version offers a free trial.

How does Scanopy compare to NetBox?

NetBox is a powerful IPAM/DCIM tool but requires manual data entry. Scanopy excels at automatic discovery and visualization. Many users combine them: Scanopy for discovery and NetBox for authoritative documentation, syncing via API.

Can Scanopy scan cloud environments?

Absolutely. Deploy a daemon in your AWS, GCP, or Azure environment (as a container or VM) and it will discover cloud resources, including VPC peering, load balancers, and container services. The daemon uses cloud metadata APIs for enhanced discovery.

What are the system requirements?

For small networks (<100 devices), 2GB RAM and 2 CPU cores suffice. For enterprise deployments, allocate 4GB RAM and 4 cores for the server, plus 512MB per daemon. Storage needs are minimal (~10MB per 1000 devices). All components run on Linux via Docker.

Conclusion: Why Scanopy Deserves a Place in Your Toolbox

Network documentation doesn't have to be a soul-crushing manual task. Scanopy proves that automation can be both powerful and elegant, delivering interactive network diagrams that maintain themselves. Its one-time setup, zero upkeep promise isn't marketing fluff—it's the reality of a well-architected tool that respects your time.

What sets Scanopy apart is its intelligent service recognition and distributed architecture. It's not just drawing boxes and lines; it's understanding that your PostgreSQL instance talks to your Redis cache, that your Nginx load balancer fronts three application servers, and that your Prometheus monitors are correctly positioned. This context-aware mapping turns a simple diagram into a operational insights dashboard.

The AGPL-3.0 licensing makes it accessible to everyone, from home lab enthusiasts to large enterprises. The commercial option provides flexibility for organizations with strict compliance requirements. And for those who'd rather not manage infrastructure, Scanopy Cloud offers a hassle-free alternative.

If you're still manually updating network diagrams or struggling with outdated CMDB data, give Scanopy 10 minutes. Run the Docker Compose command, let it scan your network, and watch your topology come alive. The moment you see your entire infrastructure visualized accurately—without lifting a finger—you'll understand why this tool is generating so much excitement.

Ready to automate your network documentation? Visit the Scanopy GitHub repository to get started, join their Discord community for support, or start a free trial at scanopy.net. Your future self will thank you every time you avoid opening Visio.