Skip to content

Host integrations

Some widgets need a little setup on the server itself, because Waylight deliberately does not get the access they would otherwise require. Each section below starts with the reason, then shows the steps. The security model explains the boundaries in more depth.

The examples assume Docker Compose with the repository checked out in /opt/waylight. Adjust the path to your checkout. The settings pages for WireGuard, Wake-on-LAN and the services generate the exact lines for your setup, so you can usually copy them from there.

WireGuard

Why an extra step: wg needs network admin rights, and its output includes the server's private key. Instead of giving the container either, a small script on the host exports only the public peer status.

Run the export every minute with cron:

sudo tee /etc/cron.d/waylight-wireguard <<'CRON'
* * * * * root /opt/waylight/scripts/wireguard-export.sh
CRON

The script runs wg show all dump inside the wireguard container (set WG_CONTAINER= to an empty value if WireGuard runs on the host). It drops the interface line with the private key, blanks preshared keys and writes the result to ./wireguard, which Compose mounts read-only into Waylight. With linuxserver/wireguard, peer names are taken from its peer_<name> folders; you can rename peers under Settings → WireGuard.

A peer counts as online when its last handshake is less than three minutes old.

Disk health

Why an extra step: reading S.M.A.R.T. data needs raw access to the disks, which the container must never have. A host script writes the smartctl output to a folder instead.

Install smartmontools 7.0 or newer (sudo apt install smartmontools) and run the export every 30 minutes:

sudo tee /etc/cron.d/waylight-smart <<'CRON'
*/30 * * * * root /opt/waylight/scripts/smart-export.sh
CRON

The script writes smartctl --json -a for every disk that smartctl --scan-open finds into ./smart and removes files of disks that are gone. Waylight rates each disk like this:

Finding Status
Failed self-assessment, an attribute below its threshold, an NVMe critical warning, spare below threshold, wear of 100 % or more critical
Reallocated, pending or uncorrectable sectors, NVMe media errors, wear of 90 % or more warning
60 °C or more for HDD and SATA, 70 °C or more for NVMe (critical from 70 and 80 °C) warning
Export older than DISKHEALTH_STALE_AFTER (default two hours) unknown

Changes of status are sent through notifications and recorded on the timeline. The export contains model and serial numbers, but nothing stored on the disks.

Wake-on-LAN

Why an extra step: magic packets are broadcasts, and broadcasts cannot leave a Docker bridge network. Moving Waylight into the host network would remove its isolation, so a tiny relay in the host network does this one job.

Service tiles with a MAC address show a power button while the service is offline. Turn on the relay in .env and restart the stack:

COMPOSE_PROFILES=wol
# Only if 255.255.255.255 leaves through the wrong interface:
# WOL_BROADCAST=192.168.178.255:9

The wol-relay service runs from the same image. It has no capabilities, a read-only file system and no access to data, Docker or secrets. It accepts nothing but valid magic packets on UDP port 9009, with a rate limit, and broadcasts them into your LAN. Anyone in your LAN can send it packets, which lets them do what every LAN device can do anyway: wake a computer.

Setup What to do
Docker Compose COMPOSE_PROFILES=wol
Package, Pi image or a container in the host network WOL_RELAY= (empty); Waylight broadcasts itself
Docker without the extra container Enable directed broadcast forwarding on the host (sysctl net.ipv4.conf.all.bc_forwarding=1 and the same for your LAN interface), then set WOL_RELAY= and WOL_BROADCAST=<your-lan>.255:9

The target computer must have Wake-on-LAN enabled in its firmware and its network driver.

Docker actions

Why an extra step: write access to Docker amounts to root access on the host. Instead of loosening the read-only proxy, a second proxy allows nothing but restarts, and Waylight only restarts containers on your list.

The Docker widget can restart containers and show their last 200 log lines. Add to .env:

COMPOSE_PROFILES=docker-actions        # or wol,docker-actions
DOCKER_ACTIONS=true
DOCKER_ACTIONS_CONTAINERS=jellyfin,paperless

The read-only proxy stays as it is. The additional docker-actions-proxy accepts only POST /containers/<name>/stop|restart|kill and refuses everything else, including reads, creating containers and exec. Waylight itself only calls restart, and only for the listed containers.

Logs are read through the read-only proxy and can contain secrets. List only containers whose logs you are happy to see on the dashboard.

Docker autodiscovery

Containers can bring their own service tile. Add labels in your compose file, then turn on Settings → Services → Docker autodiscovery, or press Sync now. The labels are read through the existing read-only proxy; no new permission is needed.

services:
  jellyfin:
    labels:
      waylight.name: Jellyfin
      waylight.url: https://jellyfin.example.com
      waylight.icon: 🎬
      waylight.description: Films and series
Label Also accepted Meaning
waylight.url homepage.href Link and health-check address of the tile. Required.
waylight.name homepage.name Name of the tile; defaults to the container name.
waylight.icon homepage.icon An emoji or an image URL.
waylight.description homepage.description A short description.
waylight.enable false skips the container.

Stacks labelled for Homepage work unchanged; homepage.group and homepage.widget.* are ignored.

Tiles are matched by container name, so recreating a container keeps its tile, position and history. A few rules:

  • Edits. You can edit a discovered tile. With Labels win on the next sync (the default), the labels overwrite your changes on the next sync; with Keep my changes, an edited tile is left alone.
  • Removed containers. The tile is hidden, not deleted, and marked in the settings. It returns with the container. Hidden tiles are not checked, so a removed container does not trigger an offline alert.
  • Interval. Between 1 and 1440 minutes, five by default. Labels that do not make sense, such as a URL without http:// or https://, are skipped and counted in the result of the last sync.

Home Assistant

The smart home widget shows the entities you pick, with their state and last change. In Home Assistant, create a long-lived access token (your profile → Security), then enter the address and the token under Settings → Home Assistant. The token is stored encrypted and never shown again. States are read on demand, at most every ten seconds and only while a widget is open; nothing is polled in the background.

Switches and buttons are off by default. A Home Assistant token can do everything its user can, so Waylight keeps its own list of entities that may be controlled:

SMARTHOME_ACTIONS_ENTITIES=switch.coffee_machine,button.garage_door

Switches, lights, fans and input_boolean entities are toggled; buttons, input_button, scripts and scenes are pressed. Each action asks for confirmation and is written to the security log. MQTT is not supported.

Proxmox VE

The Proxmox widget shows each node's CPU, memory and root disk, and every VM and container with its state and uptime. It needs only a read-only API token. Create one on any node:

pveum user add monitor@pve
pveum aclmod / -user monitor@pve -role PVEAuditor
pveum user token add monitor@pve waylight --privsep 0   # prints the secret once

Enter the address (https://<node>:8006), the token ID (monitor@pve!waylight) and the secret under Settings → Proxmox. Proxmox uses a self-signed certificate, so also paste its SHA-256 fingerprint, which you find under node → System → Certificates or with:

openssl x509 -in /etc/pve/local/pve-ssl.pem -noout -fingerprint -sha256

Waylight then trusts exactly this certificate. Certificate checks are never switched off.

Start and shutdown are off by default. List the guests in .env and give the token the right to power exactly these:

PROXMOX_ACTIONS_GUESTS=100,105
pveum aclmod /vms/100 -user monitor@pve -role PVEVMUser   # once per guest

The widget then offers start for stopped guests and shutdown for running ones. Shutdown is always a clean ACPI or container shutdown, never a hard stop. Each action asks for confirmation and is written to the security log.

DNS filter pause

The AdGuard Home and Pi-hole widget can switch blocking off for 5, 30 or 60 minutes, for when a site breaks because of a blocked domain. That affects your whole network, so it is off by default:

DNS_PAUSE_PROVIDERS=adguard        # or pihole, or adguard,pihole

The DNS filter turns itself back on when the time is up. Every pause is written to the security log.