WOL-Server

A lightweight HTTP server that sends Wake-on-LAN (WOL) magic packets to power on remote machines on your local network. Supports multiple devices through YAML configuration or direct API parameters.

Quick Start

Docker (Recommended)

services:
  wol-server:
    image: ghcr.io/daltonbr/wol-server:latest
    container_name: wol-server
    network_mode: "host"  # Required for WOL broadcast on Linux
    environment:
      PORT: "5000"  # Optional, defaults to 5000
      WOL_CONFIG: |
        devices:
          desktop:
            mac: "00:11:22:33:44:55"
            ip: "192.168.1.255"
            port: 9
          
          laptop:
            mac: "aa:bb:cc:dd:ee:ff"
            ip: "192.168.1.100"
    restart: unless-stopped
    
    # macOS users: network_mode: "host" doesn't work on Docker Desktop
    # Use port mapping instead and comment out network_mode above:
    # ports:
    #   - "5000:5000"
    
    # Alternative: Mount a config file instead of using WOL_CONFIG env var
    # volumes:
    #   - type: bind
    #     source: ~/.config/wol-server/config.yaml
    #     target: /root/.config/wol-server/config.yaml
    #     read_only: true

Native Binary

# Install config
mkdir -p ~/.config/wol-server
cp config.example.yaml ~/.config/wol-server/config.yaml
# Edit config.yaml with your device details

# Run
go run .

Usage

Wake a configured device:

curl http://localhost:5000/wake?device=desktop

Wake using direct parameters (no config needed):

curl "http://localhost:5000/wake?mac=00:11:22:33:44:55&ip=192.168.1.255"

Check server status:

curl http://localhost:5000/status

Shell Aliases (Optional)

Add these to your .zshrc or .bashrc for quick access:

# WOL Server - Configuration
export WOL_SERVER="http://localhost:5000" #or the IP of the server machine
export COMPUTER1_MAC="00:11:22:33:44:55"
export COMPUTER1_IP="192.168.1.255" # broadcast IP
export COMPUTER2_MAC="aa:bb:cc:dd:ee:ff"
export COMPUTER2_IP="192.168.1.255" # broadcast IP

# WOL Server - Wake devices
alias wol-status='curl $WOL_SERVER/status'
alias wake-computer1='curl "$WOL_SERVER/wake?mac=$COMPUTER1_MAC&ip=$COMPUTER1_IP"'
alias wake-computer2='curl "$WOL_SERVER/wake?mac=$COMPUTER2_MAC&ip=$COMPUTER2_IP"'

After adding, reload your shell: source ~/.zshrc

Configuration

Environment Variables

Variable	Description	Default
PORT	HTTP server port	5000
WOL_CONFIG	YAML configuration (inline)	-

Option 1: Environment Variable (Docker)

Set WOL_CONFIG with YAML content (see docker-compose example above).

Option 2: Config File (Bare Metal)

Create ~/.config/wol-server/config.yaml:

devices:
  desktop:
    mac: "00:11:22:33:44:55"
    ip: "192.168.1.255"
    port: 9           # optional, default: 9
  
  laptop:
    mac: "11:22:33:44:55:66"
    ip: "192.168.1.255"

See config.example.yaml for more examples.

Configuration Fields

Field	Type	Description	Default
mac	string	Target machine's MAC address (required)	-
ip	string	Target IP or broadcast address (required)	-
port	integer	UDP port for WOL	9

API Reference

Endpoints

GET /wake

Wake a device using either a configured device name or direct parameters.

Query Parameters:

Using configured device:

• device - Device name from config (required)

Using direct parameters:

• mac - MAC address in colon format (required)
• ip - Target IP or broadcast address (required)
• port - UDP port (optional, default: 9)

Examples:

# Using device name
GET /wake?device=desktop

# Using direct parameters
GET /wake?mac=00:11:22:33:44:55&ip=192.168.1.255&port=9

GET /status

Check if the server is running.

Response: WOL service is running

Prerequisites

Your target machine must have:

• Wake-on-LAN enabled in BIOS/UEFI
• Wake-on-LAN enabled in network adapter settings
• Connected to power (or battery with WOL support)

Guide: How to enable Wake-on-LAN on Windows 11

Alternative: Volume Mount Config

Instead of using WOL_CONFIG env var, you can mount a config file (see commented example in docker-compose above).

Development

See docs/DEVELOPMENT.md for:

• Building from source (requires Go 1.25.5+)
• Running tests
• Cross-compilation
• Publishing releases