mad0x20wizard/desomnia repository overview

⁠Desomnia

Intelligent power management for home labs and small networks.

Desomnia keeps machines asleep until they are actually needed, wakes them the moment a connection arrives, and puts them back to sleep once the last client disconnects — transparently, without changes to the connecting clients.

On Linux, the primary use case is as a Wake-on-LAN proxy: deploy it on an always-on device (Raspberry Pi, NAS, small server) and it will watch the network in promiscuous mode, detect connection attempts directed at sleeping hosts, and send Magic Packets on their behalf. No software or reconfiguration is required on either the waking clients or the target hosts.

⁠Quick Start

Create a docker-compose.yml:

services:
  desomnia:
    image: mad0x20wizard/desomnia

    volumes:
      - ./config:/etc/desomnia
      - ./plugins:/var/lib/desomnia/plugins  # optional
      - ./logs:/var/log/desomnia             # optional

    restart: unless-stopped

    network_mode: host

    cap_add:
      - NET_RAW
      - NET_ADMIN

network_mode: host and the two capabilities are required — Desomnia needs raw network access to capture packets and send Magic Packets.

Place your configuration file at ./config/monitor.xml, then run:

docker compose up -d

⁠Minimal Configuration (WoL Proxy)

./config/monitor.xml:

<?xml version="1.0" encoding="utf-8"?>
<SystemMonitor version="1">

  <NetworkMonitor watchMode="promiscuous" autoDetect="IPv4">
    <RemoteHost name="my-server" MAC="00:1A:2B:3C:4D:5E" IPv4="192.168.1.10">
      <Service name="SSH" port="22" />
      <Service name="RDP" port="3389" />
    </RemoteHost>
  </NetworkMonitor>

</SystemMonitor>

Replace the MAC and IP with those of your sleeping host. Any client on the network that tries to reach it on SSH or RDP will trigger a Magic Packet automatically.

⁠Volume Layout

⁠Limited Sleep Management support

The container is primarily designed for the Wake-on-LAN proxy use case. If you also want to use it to control the sleep of the host, you have to add the D-Bus socket and run the container in privileged mode:

desomnia:
  privileged: true
  volumes:
    - /run/dbus:/run/dbus

This works only, if the host uses systemd. When the D-Bus is accessible, Desomnia can suspend the system and monitor inhibition locks as it would on a native installation. Monitoring of processes will not be available for obvious reasons.

⁠Links

• Full documentation: https://desomnia.readthedocs.io/⁠
• Docker installation guide: https://desomnia.readthedocs.io/en/latest/installation/docker.html⁠
• WoL proxy guide: https://desomnia.readthedocs.io/en/latest/guides/wol-proxy.html⁠
• GitHub: https://github.com/mad0x20wizard/Desomnia⁠
• Discord: https://discord.gg/RzrBjcy2⁠

Desomnia is licensed under GPL-3.0.