<img src="frontend/assets/favicon.svg" alt="ShutHost" width="24" height="24"> ShutHost

A neat helper that manages the standby state of unix and windows hosts with Wake-On-Lan (WOL) configured, with Web-GUI.

Note: LARGE parts of this project were LLM generated. None were blindly committed, but it is what it is.

played at 2x speed, using the WebUI installed as PWA

⚠️ Note: the short demo clip shown above is slightly out of date with respect to theming and layout. Check the live demo or screenshots below for the current UI.

🌐 Live Demo

You can try a demo of the ShutHost WebUI via GitHub Pages.

This demo runs entirely in your browser and does not control any real hosts. It is useful for previewing the UI and some of the features.

Note that the theme (light/dark) of the WebUI is selected based on your system preference.

---

✨ Features

• Manage standby state of Linux, MacOS and Windows hosts with Wake-On-Lan (WOL) and lightweight agents
• Web-based GUI for easy management
  • Light/Dark theme are selected based on system preference (with CSS media queries)
  • installable as PWA
    • this allows behavior similar to an native app on e.g. Android
• API for machine-to-machine control (e.g. backups)
• customizable, e.g. custom shutdown/sleep command per host
• Should support extension (e.g. Home Assistant)
• Convenience scripts for simple installation of agents, clients and coordinator
• Docker and simple binary deployment options for the coordinator (due to how Wake-on-LAN works docker only supports Linux though)
• simplified agent-only deployment doesn't require a coordinator on an always-on host
• security wasn't an afterthought

---

📚 Documentation & Resources

Extended documentation, examples, and additional resources to help you get the most out of ShutHost:

• 🧭 ShutHost Design & Operation
• 💿 Installation
• ⚡ Agent-only Install
• 📚 Examples
• 📋 Requirements
• 🔒 Security Considerations
• ❓ FAQ
• 📷 UI screenshots
• 🖥️ Platform Support
• 🏗️ Architecture
• 🚀 Potential Future Features
• 🤝 Contributing

---

🧭 ShutHost Design & Operation

ShutHost began from a simple observation: Wake-on-LAN (WOL) is reasonably standardized for starting machines on a LAN, but there is no well-established, safe equivalent for remotely shutting down running systems. Some projects try to solve this—for example, sleep-on-lan and snippets/guides that log in via SSH and shut down the computer that way—but those approaches commonly enlarge the attack surface, are difficult to deploy, and lack usability.

ShutHost addresses these challenges through three key design decisions:

• Authorization & safety: Remote shutdown commands pose risks of accidental or malicious denial-of-service. To mitigate this, ShutHost requires authenticated requests: shutdowns are authorized using HMAC-signed messages with timestamps to prevent replay attacks and avoid sending plaintext credentials over the network.
• Privilege & init integration: Performing a shutdown usually requires elevated privileges and must persist across reboots. ShutHost provides lightweight host agents that integrate with common service managers so the shutdown capability is available after restarts. Supported integrations include systemd (the dominant init on most mainstream Linux distributions), openrc (used by distributions like Alpine and Gentoo), and launchd (macOS). A "self-extracting" mode is also available for custom or manual setups where users handle init integration themselves (see Deploying the Self-Extracting Agent on Unraid for an example).
• Network reachability & central control: Wake-on-LAN only operates on the local broadcast domain. To manage hosts from outside the LAN, ShutHost includes a coordinator component: a single LAN-hosted coordinator provides a web GUI (installable as a PWA) and an API. The coordinator sends WOL packets to start machines locally and forwards authenticated shutdown requests to host agents over IP.

Host agents are intentionally minimal and designed for security. They use IP-addressed, authenticated requests and avoid running full-featured HTTP servers. This reduces the attack surface for components that typically run with elevated privileges. The host_agent performs the actual shutdown and registers with the host's service manager so the capability survives reboots. The host_agent can also be used standalone with direct control scripts (see Agent-only Installation); its API is documented in docs/API.md. The host_agent supports custom shutdown commands, allowing users to define how their systems should be powered down or put to sleep—this can also be seen in the Unraid example.

The coordinator glues the pieces together and provides usability features:

• A web UI and API make it easy to start/stop machines and integrate with other services.
• The coordinator doesn't require elevated privileges to run.
• The coordinator offers an installer and convenience scripts that simplify deploying host_agents on the LAN and clients over the internet.
• A lease system prevents hosts from being shut down while a client holds an active lease (for instance, while a backup job is running).

  This safety depends on all starts and stops going through the coordinator (either the UI or a client using the coordinator API); actions performed outside the coordinator are outside its control.

💿 Installation

Choose either the binary or the container (Linux only) installation. Windows isn't supported by the coordinator; use a Linux VM or install the agent only (see Agent-only Install).

Binary

• Use the automated installation script:

  curl -fsSL https://github.com/9SMTM6/shuthost/releases/latest/download/shuthost_coordinator_installer.sh | sh
  

  This script will automatically detect your platform, download the appropriate binary, print the checksum, and install the coordinator as a system service. Pass -i to see all available install subcommand options (e.g. custom port or user).

• Or follow the manual steps.

Docker (Linux only)

• Download the example_config.toml and docker-compose.yaml from Github and run the service:

  # Create config directory and download the example config from GitHub
  mkdir -p coordinator_config data
  curl -L -o coordinator_config/config.toml \
    https://raw.githubusercontent.com/9SMTM6/shuthost/main/docs/examples/example_config.toml
  
  # Set restrictive permissions (readable/writable by owner only)
  chmod 600 coordinator_config/config.toml
  # Download the docker-compose file
  curl -L -o docker-compose.yaml \
    https://raw.githubusercontent.com/9SMTM6/shuthost/main/docs/examples/docker-compose.yaml
  
  # Run the service in the background
  docker-compose up -d shuthost
  
  # Access the WebUI at http://localhost:8080
  

• Notes:
  • Uses network_mode: host to reach the hosts with the Wake-on-LAN packet. This setting is Linux-only and will not work properly on Docker Desktop for Mac/Windows. Use the binary on Mac or run on a Linux VM with bridged networking on Mac or Windows.

Agent / Client installation

• To install a host-agent (controls the hosts): open the web UI, open "Install Host Agent" and follow the instructions shown. Pass --install-help (shell) or -InstallHelp (PowerShell) to the install script to see all available install subcommand options.

• To install a client (M2M, e.g., backup scripts): switch to the Clients tab, open "Install Client" and follow the instructions shown.

⚡ Agent-only Install

Lightweight opt