FriendNet

What it is

FriendNet is a distributed system for monitoring home networks across multiple physical locations connected via Tailscale. It consists of lightweight Python agents deployed on local machines (e.g., Raspberry Pis) that perform mDNS/Bonjour scanning and port fingerprinting, and a central React/FastAPI dashboard that aggregates this data to provide a unified view of all devices and services across the network.

Features

• Automatic mDNS/Bonjour service discovery across local subnets
• Service fingerprinting for Plex, Home Assistant, SSH, SMB, and more
• Centralized dashboard aggregating multiple remote homes via Tailscale
• Lightweight Python agent with configurable scan intervals
• Client-side password protection for dashboard access
• SQLite-backed storage for persistent device history

Quickstart

git clone https://github.com/davidbmar/tailscale-3-node-network.git
cd tailscale-3-node-network
cd backend
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
PYTHONPATH=. python app/main.py
cd ../frontend
npm install
npm run dev

Architecture

flowchart TD
    subgraph House_A["House A (Remote)"]
        Agent_A["FriendNet Agent\n(Python/Zeroconf)"]
        Local_Net_A["Local LAN Devices\n(mDNS Services)"]
    end

    subgraph House_B["House B (Remote)"]
        Agent_B["FriendNet Agent\n(Python/Zeroconf)"]
        Local_Net_B["Local LAN Devices\n(mDNS Services)"]
    end

    subgraph Central["Central Dashboard Host"]
        Dashboard_API["FastAPI Backend\n(SQLite)"]
        Dashboard_UI["React Frontend\n(Vite)"]
    end

    Tailscale["Tailscale VPN Tunnel"]

    Local_Net_A -- "mDNS Scan" --> Agent_A
    Local_Net_B -- "mDNS Scan" --> Agent_B
    Agent_A -- "HTTP POST /report" --> Tailscale
    Agent_B -- "HTTP POST /report" --> Tailscale
    Tailscale --> Dashboard_API
    Dashboard_UI -- "Fetch Status" --> Dashboard_API

How it's built

The system uses a hub-and-spoke architecture. The 'Agent' (Python) runs on each node, using `zeroconf` for mDNS discovery and `httpx` for HTTP fingerprinting of services like Plex, Home Assistant, and SSH. It reports findings to the 'Dashboard' (FastAPI + SQLite) via HTTP POST. The Dashboard serves a React frontend (Vite) that visualizes the network topology and service status. Authentication is handled via a client-side SHA-256 hash gate for simplicity.

How it runs

sequenceDiagram
    participant Agent as FriendNet Agent
    participant Zeroconf as zeroconf Library
    participant Network as Local LAN
    participant API as Dashboard API (FastAPI)
    participant DB as SQLite Database

    loop Every N seconds
        Agent->>Zeroconf: Start Service Browser
        Zeroconf->>Network: Send mDNS Queries
        Network-->>Zeroconf: Return Service Records
        Zeroconf-->>Agent: Discovered Services List
        
        Agent->>Agent: Fingerprint Services (HTTP/Port checks)
        
        Agent->>API: POST /api/report (House ID, Services)
        API->>DB: Upsert Nodes & Services
        DB-->>API: Confirm Save
        API-->>Agent: 200 OK
    end

How to apply & reuse

Deploy the Agent on any machine within a Tailscale network that has visibility to the local subnet (using Tailscale Subnet Routing or exit nodes). Configure the Agent with the Dashboard's URL and a unique House ID. Use the Dashboard to monitor service availability, discover new devices automatically, and verify connectivity between remote homes without exposing ports to the public internet.

At a glance