Shut down a Windows PC remotely from Gladys via MQTT

Tutorials
1

The context

We all have the same problem: turning a PC on remotely works fine (Wake-on-LAN, Tuya boards, smart plugs…). But shutting it down cleanly is another story.

On my side, I tried the Tuya WiFi boards — one that sends the WOL magic packet, and another wired directly between the motherboard and the PC power button. To turn on, perfect. To shut down… let’s say it’s random.

Gladys doesn’t have a native integration to shut down a PC (no script, no SSH). As with the Sure Petcare cat flap, the solution is a small MQTT agent that runs on the PC and waits for commands.

Once again, developed with Claude Code. The complete script was coded, tested and deployed in one session.

The architecture

Scene Gladys                    Mosquitto               PC Windows
("Send MQTT message") ─────────► (MQTT broker) ─────────► agent.py
                                                           │
                     ◄─────────────────────────────────────┘
                          JSON response + online/offline status

A Python script (~35 MB RAM, 0% CPU) that:

  1. Connects to your Mosquitto broker

  2. Listens on an MQTT topic for commands

  3. Executes the requested action (shutdown, restart, lock, test)

  4. Responds in JSON and maintains an online/offline status (LWT)

What you need

  • Gladys with the MQTT integration configured (Mosquitto)

  • Python 3.10+ installed on the Windows PC to control

  • The PC and the NAS/broker on the same local network

Available commands

Payload MQTT Effect
test Replies with hostname, OS, time — does nothing to the PC
shutdown Shuts down the PC (configurable delay, 5s default)
restart Restarts the PC
lock Locks the Windows session
cancel Cancels a shutdown/restart in progress

The test command is essential to validate that your Gladys scene works without risking shutting down the PC you’re currently working on…

Step 1: Install the agent on the PC

Create a folder on the PC, for example C:\pc-shutdown-agent\.

requirements.txt :

paho-mqtt\u003e=2.0

Install the dependency :

pip install -r requirements.txt

agent.py — the complete code is on GitHub :point_right: david-digitis/pc-shutdown-agent

Copy agent.py into your folder.

Step 2: Configure

Create a .env file next to agent.py :

# PC name (used in the MQTT topics)
PC_NAME=pc-bureau

# IP of your Mosquitto broker (your NAS, Raspberry Pi, etc.)
MQTT_HOST=192.168.x.x
MQTT_PORT=1883

# Delay before shutdown (in seconds, gives you time to cancel)
SHUTDOWN_DELAY=5

The PC_NAME is important: it determines the MQTT topics. If you have multiple PCs, each has its own name and topics.

Step 3: Test

cd C:\pc-shutdown-agent
python agent.py

You should see:

2026-03-22 08:45:39 [INFO] PC Shutdown Agent v1.1 — pc_name=pc-bureau
2026-03-22 08:45:39 [INFO] MQTT broker: 192.168.x.x:1883
2026-03-22 08:45:39 [INFO] Connected to MQTT 192.168.x.x:1883
2026-03-22 08:45:39 [INFO] Subscribed to pc-agent/pc-bureau/command
2026-03-22 08:45:39 [INFO] TEST ping received
2026-03-22 08:45:39 [INFO] Agent running — waiting for commands...

From your broker (or via docker exec if Mosquitto is in Docker) :

# Send a test
mosquitto_pub -t "pc-agent/pc-bureau/command" -m "test"

# See the response
mosquitto_sub -t "pc-agent/pc-bureau/response" -C 1

Response :

{
  "action": "test",
  "status": "ok",
  "pc_name": "pc-bureau",
  "hostname": "Corsair-Bureau",
  "platform": "Windows-11-10.0.26200-SP0",
  "time": "2026-03-22T06:53:09.076466+00:00"
}

Step 4: Gladys Scene

Create a scene with the action « Send an MQTT message » :

  • Topic : pc-agent/pc-bureau/command

  • Message : shutdown

Tip: start with test as the message to validate wiring, then switch to shutdown when you’re sure.

You can trigger this scene from the dashboard, a button, another scene (night mode, away mode…), or whatever you want.

Step 5: Autostart (optional)

To have the agent start automatically at Windows startup without a console window, the repo includes an install.bat that creates a shortcut in the Windows Startup folder.

It uses pythonw (Python without console) so it runs completely silently.

Manual alternative: create a shortcut in %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\ that points to pythonw C:\pc-shutdown-agent\agent.py.

Multiple PCs

Deploy the same script on as many PCs as you want. Just change PC_NAME in the .env of each machine:

# Office PC
PC_NAME=pc-bureau
# → topic: pc-agent/pc-bureau/command

# Bedroom PC
PC_NAME=pc-chambre
# → topic: pc-agent/pc-chambre/command

Each PC has its own topics, no conflicts.

MQTT Topics — summary

Topic Direction Content
pc-agent/{PC_NAME}/command Gladys → PC Command (shutdown, test, etc.)
pc-agent/{PC_NAME}/response PC → Gladys JSON response
pc-agent/{PC_NAME}/status PC → Gladys online / offline (automatic via LWT)

Resource usage

  • RAM: ~35 MB

  • CPU: ~0% (sleeps on a socket, only wakes when it receives a command)

  • Network: 1 persistent TCP connection to the MQTT broker

Technical notes

  • Uses paho-mqtt v2 with CallbackAPIVersion.VERSION1 — v2 has a reconnection loop bug with Mosquitto (session taken over)

  • loop_start() instead of loop_forever() — more stable

  • Built-in .env loader (no need for python-dotenv)

  • LWT (Last Will and Testament): if the agent crashes or the PC is abruptly powered off, Mosquitto automatically publishes offline on the status topic

  • The 5-second delay before shutdown gives you time to send cancel in case of an error

Limitations

  • Windows only for now (the Linux commands are present in the code but not tested)

  • No Wake-on-LAN integrated — this is an agent that runs on a powered-on PC, so by definition it cannot turn on a powered-off PC. For WOL, use your existing solutions (Tuya, smart plug, or a WOL script on your NAS)

Source code

:point_right: GitHub : david-digitis/pc-shutdown-agent

MIT License — do whatever you want with it.

Tested on a Synology DS1520+ NAS (Mosquitto in Docker) + Windows 11 PC with Gladys v4.

1 Like