Give your sleeping machines a gentle nudge.

A simple, lightweight Wake-on-LAN (WoL) tool with both command-line and web interfaces. Built for simplicity and reliability in homelab environments.

• 🖥️ CLI Interface - Perfect for scripts and automation
• 🌐 Web Interface - Clean, responsive UI for point-and-click operation
• 🎯 Device Management - JSON-based configuration with friendly names
• 🌍 Multi-Network Support - Per-device broadcast addresses for complex networks
• 📱 Mobile Friendly - Works on phones and tablets
• 🐳 Docker Ready - One-command deployment
• 🔧 Zero Dependencies - Uses standard Python libraries

note: the cli is completely standalone if you need it to be - just ignore the web part and give it a go

# Clone the repository
git clone https://github.com/pbexiga/nudgeWoL.git
cd nudgewol

# Edit device configuration
nano devices.json

# Wake a device
python nudgewol.py --wake "Gaming PC"

# Start web interface
python nudgewol-web.py

# Clone and configure
git clone https://github.com/pbexiga/nudgeWoL.git 
cd nudgewol/app
nano devices.json       # setup your devices
nano docker-compose.yml # set the path to mount the scripts to /app

# Deploy with Docker
docker-compose up -d

# Access web interface at http://your-server:3000

The project consists of just three essential files:

The core Wake-on-LAN engine that can be used independently:

• Sends magic packets to wake devices
• Manages device configurations from JSON
• Provides status checking via ping
• Supports both human-readable and JSON output
• Works standalone without any dependencies

A lightweight Flask application that wraps the core script:

• Provides a clean, responsive web UI
• Calls the same functions as the CLI script
• Perfect for embedding in dashboards like Homarr
• Minimal code - just a thin web wrapper

Simple JSON configuration for your devices:

• Device names, descriptions, MAC addresses, and IPs
• Per-device or global broadcast address settings
• Hot-reloadable (no restart required for changes)

Edit devices.json to configure your devices:

{
  "broadcast_address": "255.255.255.255",
  "devices": [
    {
      "name": "Gaming PC",
      "description": "Windows desktop computer",
      "mac": "d8:bb:c1:3a:16:0a",
      "ip": "192.168.1.100",
      "broadcast_address": "192.168.1.255"
    },
    {
      "name": "Home Server",
      "description": "Linux server in basement",
      "mac": "aa:bb:cc:dd:ee:ff",
      "ip": "10.0.1.50",
      "broadcast_address": "10.0.1.255"
    }
  ]
}

1. CLI override: --broadcast 192.168.1.255
2. Device-specific: "broadcast_address" in device config
3. Global config: Top-level "broadcast_address"
4. Default: 255.255.255.255

# List all configured devices
./nudgewol.py --list

# Wake a device by name
./nudgewol.py --wake "Gaming PC"

# Wake a device by MAC address
./nudgewol.py --mac d8:bb:c1:3a:16:0a

# Check if a device is online
./nudgewol.py --status "Gaming PC"
./nudgewol.py --status-ip 192.168.1.100

# Wake all configured devices
./nudgewol.py --wake-all

# Override broadcast address
./nudgewol.py --wake "Gaming PC" --broadcast 192.168.1.255

# Get JSON output (useful for scripts)
./nudgewol.py --list --json
./nudgewol.py --wake "Gaming PC" --json

# Traditional method (all platforms)
python nudgewol.py --wake "Gaming PC"

The web interface provides:

• Device List: Visual overview of all configured devices
• Individual Wake: Select and wake specific devices
• Status Check: Ping devices to verify they're online
• Bulk Operations: Wake all devices at once
• Manual MAC Entry: Wake devices not in your configuration

Start the web interface:

# Direct execution (Linux/macOS)
./nudgewol-web.py

# Traditional method (all platforms)
python nudgewol-web.py

Access the web interface at http://your-server:3000 after starting.

Create this docker-compose.yml:

mount /app wherever you store the scripts for the container to use

version: '3.8'

services:
  nudgewol:
    image: python:3.11-slim
    working_dir: /app
    volumes:
      - ${PATH_TO_SCRIPTS}:/app  # Mount entire project directory
    network_mode: host  # Required for WoL broadcasts
    restart: unless-stopped
    command: >
      bash -c "
        apt-get update && 
        apt-get install -y iputils-ping &&
        pip install flask flask-cors &&
        python nudgewol-web.py
      "
    environment:
      - PYTHONUNBUFFERED=1

Deploy:

docker-compose up -d

Wake-on-LAN requires sending broadcast packets to the network. Docker's default bridge networking isolates containers and prevents broadcast packets from reaching your actual network devices.

Host networking allows:

• Direct access to your network broadcast domain
• Magic packets to reach sleeping devices
• Proper network interface access for broadcasts

Trade-offs:

• Container shares host network stack
• Less network isolation
• Required for WoL functionality

note: Google it for more updated instructions :)

1. Network Adapter Settings:

   • Open Device Manager → Network adapters
   • Right-click your network adapter → Properties
   • Power Management tab → Check "Allow this device to wake the computer"
   • Advanced tab → Find "Wake on Magic Packet" → Enable

2. BIOS/UEFI Settings:

   • Boot into BIOS/UEFI
   • Look for "Wake on LAN", "Power Management", or "APM"
   • Enable "Wake on LAN" or "Wake on PCI/PCIe"

3. Windows Power Settings:

   • Control Panel → Power Options → Choose what the power buttons do
   • Change settings that are currently unavailable
   • Uncheck "Turn on fast startup" (can interfere with WoL)

1. Check WoL support:

   sudo ethtool eth0 | grep Wake-on

2. Enable WoL:

   sudo ethtool -s eth0 wol g

3. Make permanent (systemd service):

   # Create /etc/systemd/system/wol.service
   [Unit]
   Description=Wake-on-LAN for eth0
   Requires=network.target
   After=network.target
   
   [Service]
   ExecStart=/sbin/ethtool -s eth0 wol g
   Type=oneshot
   
   [Install]
   WantedBy=multi-user.target

4. BIOS Settings: Same as Windows - enable Wake-on-LAN in BIOS/UEFI

1. System Preferences:

   • System Preferences → Energy Saver
   • Check "Wake for network access"

2. Terminal method:

   sudo pmset -a womp 1

• Use sleep/suspend, not shutdown - WoL works from sleep states, not full power-off
• Wired connections work better - WiFi WoL is unreliable
• Check your router - Some routers block WoL packets
• Test locally first - Ensure WoL works on the same network before remote attempts

Use the CLI interface with Home Assistant shell commands:

shell_command:
  wake_gaming_pc: "./nudgewol.py --wake 'Gaming PC'"

The CLI tool returns proper exit codes and supports JSON output for easy integration:

if ./nudgewol.py --wake "Server" --json | jq -r '.success'; then
    echo "Server wake signal sent successfully"
fi

Contributions are welcome! This project aims to stay simple and focused. Ideas for contributions:

• Additional device management features
• Better error handling and logging
• Integration examples with popular tools
• Documentation improvements
• Mobile app companion
• Multi-language support

git clone https://github.com/pbexiga/nudgeWoL.git
cd nudgewol
chmod +x nudgewol.py nudgewol-web.py  # Make scripts executable
pip install flask flask-cors  # For web interface development

MIT License - see LICENSE file for details.

• Built for the homelab community
• Inspired by the need for simple, reliable tools
• Thanks to all contributors and users

nudgeWoL - Because sometimes your machines just need a gentle nudge to wake up. 💤➡️⚡