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.

• 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.
• 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 option: install the host agent only (no coordinator). This does not require an always-on coordinator or a domain; it is easy to deploy but has limitations — the control scripts work only on the same LAN. See the detailed example in docs/examples/agent-installation.md.

Note for Windows users: Windows agents are only available as self-extracting archives. You must manually configure the agent to start on boot using a service manager like NSSM.

⚠️ Important behavioral difference: The PowerShell self-extracting script (self-extracting-pwsh) runs attached to the service process, unlike the shell version which automatically backgrounds the process. To run the PowerShell script in the background, start the script itself in the background (e.g., Start-Process -WindowStyle Hidden).

Install the released agent installer and generate a direct-control script:

# Install the agent:
curl -fsSL https://github.com/9SMTM6/shuthost/releases/latest/download/shuthost_host_agent_installer.sh | sh
# Generate a direct-control script (run on the machine where the agent binary is installed):
# If the agent is in your PATH (it should be by default):
sudo shuthost_host_agent generate-direct-control

# For Windows (PowerShell):
curl.exe -fLO "https://github.com/9SMTM6/shuthost/releases/latest/download/shuthost_host_agent_installer.ps1"
powershell -ExecutionPolicy Bypass -File .\shuthost_host_agent_installer.ps1
# Then generate direct-control script from the self-extracting script:
powershell -ExecutionPolicy Bypass -File .\shuthost_host_agent_self_extracting.ps1 generate-direct-control

# Move the script to the device you want to use as the controller (same LAN).
# copy via scp, USB, etc.
# Ensure its executable (on Unix):
chmod +x shuthost_direct_control_<hostname>

After moving the direct-control script to the controller device, you can run ./shuthost_direct_control_<hostname> wake, ./shuthost_direct_control_<hostname> status or ./shuthost_direct_control_<hostname> shutdown while on the same LAN. See the example document for tradeoffs and security notes.

---

📷 UI screenshots

More screenshots can be found in the frontend/tests/visual-regression.spec.ts-snapshots and the frontend/tests/mobile-navigation.spec.ts-snapshots folders. These are generated or validated automatically as part of the test suite, and thus are guaranteed to be up-to-date (if the tests pass).

---

🚀 Potential Future Features

🎯 Core Features

• 🔌 Custom Wakers: Support for alternative wake mechanisms beyond WOL, such as smart plugs or custom scripts (e.g., via API integrations). This would allow hosts without WOL support to be managed through external devices or services.
• 🔔 Notifications about host state changes through the PWA
• 📊 Host state tracking for statistics
• 🛡️ Rate limiting of requests by shuthost clients

🖥️ Platform Support

• 🐡 BSD support might happen
  • ⚠️ Requires using more advanced cross compilation
  • I have no ability to test these practically myself.

🔧 Management Features

• 🗑️ Uninstalls
• 📝 Self-registration endpoint for host agents
  • ❓ Unclear how to deal with authorization:
    • Server secret?