PowerBeacon

GitHub Repository | Report an Issue | Documentation

A Centralized Wake-on-LAN (WoL) Orchestration Platform

PowerBeacon is a self-hosted Wake-on-LAN orchestration platform built around three layers: a FastAPI backend, a React frontend, and one or more Go agents that run close to the target LAN.

Current domain model

• Clusters group related devices and agents.
• Devices belong to zero or one cluster.
• Devices can be associated with multiple agents.
• A wake request fans out through every associated online agent for the target device.
• Cluster detail pages allow waking one device or the whole cluster.

Core capabilities

• Cluster management for organizing devices and agents
• Multi-agent Wake-on-LAN delivery for individual devices
• Cluster-level wake orchestration
• Agent registration, heartbeat tracking, and cluster visibility
• Local auth and OIDC authentication
• Responsive UI for devices, clusters, agents, users, and settings

Architecture summary

Frontend -> Backend API -> PowerBeacon Agent -> LAN broadcast -> Target device

The backend stays the control plane. It never sends magic packets directly; all WOL traffic is dispatched through registered agents.

Quick start

Docker Compose

docker compose up -d

Development Compose

docker compose -f docker-compose.dev.yml up -d

Local development

Backend:

cd backend
uv run fastapi run dev main.py

Frontend:

cd frontend
npm install
npm run dev

Agent:

cd agent
make deps
make run

Development note

The schema has been refactored directly for the current development phase. If you still have a database from the older single-agent device model, reset it before starting this version of the app.

Agent container image

• Dedicated image: kotsiossp97/powerbeacon-agent
• Multi-architecture support: linux/amd64 and linux/arm64
• Built and published by the dedicated GitHub Actions workflow in .github/workflows/agent-image.yml
• On tag pushes, the workflow builds the agent image only when there are changes under agent/

Key API routes

• POST /api/auth/login
• GET /api/devices and POST /api/devices/{id}/wake
• GET /api/clusters, GET /api/clusters/{id}, and POST /api/clusters/{id}/wake
• GET /api/agents, POST /api/agents/register, and POST /api/agents/heartbeat

Wake behavior

When a device is woken, PowerBeacon resolves every agent associated with that device and attempts dispatch through all online agents. This improves reliability when the same machine can be reached from multiple relay hosts or overlapping network segments.

Documentation

• Interactive API docs: http://localhost:8000/api/docs
• Project docs: PowerBeacon Documentation

License

MIT