deviceshelf/deviceshelf-server repository overview

⁠DeviceShelf Server

Headless edition of the DeviceShelf network scanner. It watches a LAN around the clock and keeps an inventory of what is on it: vendor, hostname, OS, device type, open ports and the services behind them. Alerts go out when something new appears, when a device drops offline, or when a port opens that was closed before.

Mirrored from ghcr.io/wealthwallet/deviceshelf-server — same digests, both architectures (amd64, arm64).

⁠Host networking is required

Layer-2 discovery (ARP, mDNS, passive DHCP) only works when the container shares the host's network namespace. That means network_mode: host on a Linux host. It does not work on Docker Desktop for macOS or Windows, where the container never sees the real LAN.

⁠Quick start

services:
  deviceshelf:
    image: deviceshelf/deviceshelf-server:latest
    container_name: deviceshelf-server
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_RAW            # raw sockets for the ARP scan
      - NET_BIND_SERVICE   # UDP/67 for passive DHCP fingerprinting
    environment:
      DEVICESHELF_API_PORT: "8088"
      DEVICESHELF_INTERVAL: "5m"
      DEVICESHELF_PORTSCAN: "true"
    volumes:
      - ./data:/data

mkdir -p data && sudo chown 10001:10001 data
docker compose up -d

The dashboard is then on http://<host>:8088. Leave DEVICESHELF_API_TOKEN unset and the server mints a random bearer token on first start and writes it to data/DeviceShelf/api-token; read it back with docker compose exec deviceshelf deviceshelf-server -token. It is deliberately kept out of the log.

⁠Worth knowing

• Read-only token. DEVICESHELF_API_VIEWER_TOKEN hands someone a view of everything without the ability to change anything. Mutating requests are rejected and the dashboard switches to a read-only view.
• Other VLANs. DEVICESHELF_SNMP_TARGETS reads the ARP tables of your routers and switches, so devices on segments the container cannot reach directly still land in the inventory. SNMPv2c and v3 both work.
• Notifications. DEVICESHELF_NOTIFY takes Apprise URLs (ntfy, Gotify, Discord, mail, and about 120 more); DEVICESHELF_WEBHOOK posts raw JSON.
• Home Assistant. Favourites and infrastructure are published over MQTT discovery and arrive as native entities with presence, IP and latency, plus an event entity for new_device, device_online, device_offline and new_port. Only the MQTT integration is needed.
• Docker and Proxmox. Mount /var/run/docker.sock read-only to monitor containers; a read-only PVEAuditor token covers Proxmox VE.
• Runs unprivileged. The process is uid 10001 and NET_ADMIN is not needed. A bind mount has to be writable by that uid.

⁠Licence

DeviceShelf is proprietary, paid software: €59 once, no subscription. A 7-day trial runs without a licence and without a card, and the same licence covers the desktop apps for macOS, Windows and Linux as well as the iOS and Android apps. Set DEVICESHELF_LICENSE to activate.

Scanning and identification happen on the host. Nothing about the network leaves it unless you switch on one of the optional lookups.

⁠Links

• Product and downloads: https://deviceshelf.app/server⁠
• Full server documentation: https://deviceshelf.app/guide⁠
• Tags and digests on GHCR: https://github.com/wealthwallet/deviceshelf/pkgs/container/deviceshelf-server⁠