All core modules are functional. Discovery, monitoring, analytics, credential vault, and remote access all work. Contributions and feedback welcome!

Your HomeLab command center. SubNetree discovers devices on your network, monitors their status, and gives you one-click access to everything -- without typing passwords a thousand times a day.

• Why SubNetree?
• Screenshots
• What You'll Need
• Quick Start
• First Steps After Install
• Features
• Guides
• Troubleshooting
• How SubNetree Compares
• Community
• Support the Project
• Development
• License

HomeLabbers juggle dozens of tools: UnRAID for storage, Proxmox for VMs, Home Assistant for automation, plus routers, NAS boxes, and random IoT devices. SubNetree doesn't replace any of them -- it's your dashboard and aggregator that:

• Discovers everything on your LAN automatically (ARP, ICMP, mDNS, SNMP, LLDP/CDP -- with UPnP planned)
• Shows status at a glance from multiple platforms in one place
• Launches anything with one click -- web UIs, SSH -- credentials handled
• Extends via plugins to monitor whatever you need

• A computer on your network running Docker (Linux, macOS, or Windows)
• Docker installed and running (Get Docker)
• 5 minutes for initial setup

That's it. No databases, no config files, no dependencies to install.

docker run -d --name subnetree -p 8080:8080 -v subnetree-data:/data ghcr.io/herbhall/subnetree:latest

Open http://localhost:8080 -- the setup wizard will guide you through creating an admin account.

docker run -d --name subnetree --network host -v subnetree-data:/data ghcr.io/herbhall/subnetree:latest

See docker-compose.yml for a ready-to-use Compose file:

docker compose up -d

The Scout agent runs on monitored Linux machines and reports system metrics, hardware inventory, and service status back to SubNetree.

# Download latest release
curl -fsSL https://github.com/HerbHall/subnetree/releases/latest/download/scout_linux_amd64.tar.gz | tar xz
sudo ./install.sh --server http://your-subnetree-server:8080 --start

See deploy/scout/ for the systemd service file and install script.

1. Open the dashboard -- navigate to http://localhost:8080
2. Create your admin account -- the setup wizard appears on first visit
3. Run your first scan -- click "Start Scan" on the Dashboard to discover devices on your network
4. Explore your network -- browse the device list, click devices for details, or switch to the Topology view
5. Set up monitoring -- go to Monitoring to configure health checks and alerts for your devices
6. Secure your credentials -- open the Vault to store SSH passwords, API keys, and other credentials with AES-256 encryption

• Finds every device on your network automatically (ARP, ICMP, mDNS, SNMP, LLDP/CDP, WiFi scanning with manufacturer identification)
• Classifies devices by type using weighted confidence scoring (MAC OUI, SNMP, LLDP, port fingerprinting, TTL analysis)
• Scans nearby WiFi networks to discover access points (Linux nl80211, Windows Wlanapi)
• Detects unmanaged switches and infers network hierarchy from scan data
• Interactive network topology map showing how devices connect across layers
• SNMP FDB table walks reveal which devices are connected to which switch ports
• ICMP traceroute and interactive diagnostics (ping, DNS lookup, port check)
• Full device inventory with search, categorization, and bulk operations

• Tracks device health in real time with automatic alerting (OK / Warning / Critical states)
• Alerts you when device behavior changes (statistical anomaly detection with EWMA baselines, Z-score, and CUSUM)
• Predicts trends before problems happen (linear regression forecasting)
• Scan analytics dashboard with per-phase metrics and health scoring
• Publishes events to MQTT brokers for integration with Home Assistant and other IoT platforms
• Sends alerts to Alertmanager-compatible receivers (Grafana, PagerDuty, Slack)
• Ask questions about your network in plain English via AI (Ollama, OpenAI, Anthropic -- bring your own key)
• Plugin-extensible -- monitor anything

• Bank-level encryption for stored credentials (AES-256-GCM envelope encryption, Argon2id key derivation)
• Supports 7 credential types with automatic key rotation
• Seal/unseal model -- credentials are locked until you unlock the vault

• Launch any device's web UI with one click -- no re-typing passwords
• Browse remote services through a built-in reverse proxy (HTTP)
• SSH gateway with WebSocket transport and session audit trail (browser terminal UI planned)

• Discovers Docker containers and captures their configuration automatically
• Tracks configuration changes over time with snapshot versioning and retention policies
• Side-by-side diff viewer for spotting exactly what changed (LCS-based comparison)

• Modern, responsive dashboard with device list, detail pages, and topology view
• Dark mode, keyboard shortcuts, and real-time scan progress via WebSocket
• Secure login with automatic session management (JWT-based authentication)
• First-run setup wizard -- no manual configuration needed
• Backup and restore your data with a single CLI command
• One-click Scout agent deployment with platform-specific installers and download page
• Subnet grouping with collapsible headers and contextual help across all pages
• CSV import/export for bulk device management
• Demo mode for showcasing without setup (--demo flag or NV_DEMO_MODE=true)
• Ready-to-run Docker image with health checks

• Multi-tenant support for MSPs
• Tailscale integration for overlay network monitoring
• AI-generated incident summaries and root cause analysis
• Auto-update with binary signing
• MFA/TOTP authentication

See the phased roadmap for the full plan.

• Development Setup -- local dev environment
• Tailscale Deployment -- running SubNetree + Scout over Tailscale
• Tailscale Serve & Funnel -- exposing the dashboard without port forwarding

Docker: Scanning finds no devices -- Use host networking for full ARP/ICMP access:

docker run -d --network host -v subnetree-data:/data ghcr.io/herbhall/subnetree:latest

Or ensure NET_RAW and NET_ADMIN capabilities are set.

First-time setup -- Navigate to http://localhost:8080 -- the setup wizard will prompt you to create an admin account.

Backup your data --

# Create backup
subnetree backup --data-dir /data --output my-backup.tar.gz

# Restore from backup
subnetree restore --input my-backup.tar.gz --data-dir /data --force

*BSL 1.1 converts to Apache 2.0 after 4 years. Free for personal/HomeLab use.

• GitHub Discussions -- questions, ideas, and general chat
• Issue Tracker -- bug reports and feature requests
• Contributing Guide -- how to get involved

New here? Check out the Welcome thread or share your setup in Show Your Setup.

SubNetree is free for personal, HomeLab, and non-competing production use. If you find it useful:

• GitHub Sponsors
• Ko-fi
• Buy Me a Coffee

You can also contribute by reporting bugs, requesting features, testing alpha releases, or building plugins.

graph TD
    Dashboard["Dashboard<br/><small>React + TypeScript</small>"]
    Scout["Scout Agent"]
    Devices["Network Devices"]

    subgraph Server["SubNetree Server"]
        Recon["Recon"]
        Pulse["Pulse"]
        Docs["Docs"]
        Insight["Insight"]
        LLM["LLM"]
        Dispatch["Dispatch"]
        Vault["Vault"]
        Gateway["Gateway"]
        Webhook["Webhook"]
        MQTT["MQTT"]
        Tailscale["Tailscale"]
        MCP["MCP"]
        EventBus(["Event Bus"])

        Recon --> EventBus
        Pulse --> EventBus
        Docs --> EventBus
        Insight --> EventBus
        Webhook --> EventBus
        MQTT --> EventBus
    end

    Dashboard -- "REST / WebSocket" --> Server
    Scout -- "gRPC" --> Dispatch
    Recon -- "ARP / ICMP" --> Devices
    Pulse -- "ICMP" --> Devices
    Insight --> LLM
    MQTT -- "MQTT" --> HA["Home Assistant"]

Prerequisites: Go 1.25+, Node.js 20+, Make (optional)

# Build everything (server + frontend)
make build

# Or build separately
make build-server
cd web && pnpm install --frozen-lockfile && pnpm run build

# Start server (serves dashboard at :8080)
./bin/subnetree

# With config file
./bin/subnetree -config configs/subnetree.example.yaml

# Run tests
make test

# Run linter
make lint

# Generate protobuf
make proto

cmd/
  subnetree/     Server entry point
  scout/          Agent entry point
internal/
  recon/          Network discovery module
  pulse/          Monitoring module
  docs/           Infrastructure documentation module
  dispatch/       Agent management module
  vault/          Credential management module
  gateway/        Remote access module
  webhook/        Webhook notification module
  llm/            LLM plugin (Ollama provider)
  insight/        Analytics and anomaly detection
  mqtt/           MQTT publisher with HA auto-discovery
  tailscale/      Tailscale network integration
  mcp/            Model Context Protocol server
  netbox/         NetBox DCIM export
  autodoc/        Infrastructure documentation engine
web/              React dashboard (Vite + shadcn/ui)
pkg/
  plugin/         Public plugin SDK (Apache 2.0)
  llm/            LLM provider interface (Apache 2.0)
  roles/          Plugin role definitions (Apache 2.0)
  models/         Shared data types
api/
  proto/v1/       gRPC service definitions

• v0.3.0 (shipped): Scout agents, mTLS, service mapping, monitoring dashboard
• v0.4.x (shipped): mDNS discovery, metrics history, alert suppression, vault UI, analytics dashboard
• v0.5.0 (shipped): MQTT publisher, Alertmanager webhooks, CSV import/export, recommendation engine
• v0.6.x (shipped): Device classification engine, LLDP discovery, composite scoring, scan analytics, network hierarchy
• Sprints 1-11 (shipped): Traceroute, diagnostics, SNMP FDB walks, E2E tests, hardware profiles, MCP server, WiFi scanning, demo mode, Windows installer, Proxmox VE monitoring, MFA/TOTP, Tailscale, autodoc engine
• Next: NetBox integration, Home Assistant MQTT discovery, community launch, multi-tenant, PostgreSQL

SubNetree uses a split licensing model:

• Core (server, agent, built-in modules): Business Source License 1.1 -- free for personal, HomeLab, educational, and non-competing production use. Converts to Apache 2.0 after 4 years.
• Plugin SDK (pkg/plugin/, pkg/roles/, pkg/models/, api/proto/): Apache License 2.0 -- build plugins and integrations with no restrictions.

See LICENSING.md for full details.