HASS.Agent .NET10

A modern Windows companion app for Home Assistant.

🌐 Website & screenshots

⭐ Enjoying HASS.Agent? Please star this repo — and the Home Assistant integration too. It helps others find the project and keeps it going!

☕ If HASS.Agent saved you an evening of tinkering, you can buy me a coffee on Ko-fi. Everything stays free — it just helps cover things like the code signing certificate.

HASS.Agent .NET10 began as a fork of the classic HASS.Agent and has grown into a project of its own: a lightweight .NET 10 client built for current Windows desktops. The original client was a .NET 6-era application; this one focuses on a smaller, cleaner runtime, Home Assistant integration via MQTT or WebSocket API, Windows 11-friendly UX, and a split tray app/system service model.

It is designed for Windows PCs you want to observe and control from Home Assistant: media playback, notifications, sensors, shutdown/restart, command buttons, and rich machine state.

The .NET10 line starts at version 10.0.0. The classic client is a separate program: if you want to stay with it, it is still available from its own project, and the integration keeps a legacy branch for it. Thinking about switching? See Coming from HASS.Agent.

Stable: 10.12.0  ·  Beta: 10.13.0-beta.1  ·  What changed  ·  Full changelog

---

Install

Requirements

• Windows 10 version 2004 / build 19041 or newer
• Windows 11 recommended
• x64 Windows
• Home Assistant with MQTT broker (recommended, e.g. Mosquitto) or HA API (WebSocket, e.g. via Nabu Casa)
• The companion Home Assistant integration: v1k70rk4/HASS.Agent.NET10-Integration — version 10.6.7 or newer; the sensors added in 10.7.1 need integration 10.7.0 to appear in Home Assistant (the agent and the integration are released with matching version numbers, so keep them in step)

Windows versions older than Windows 10 2004 are intentionally blocked. The app targets net10.0-windows10.0.19041.0 and uses modern Windows APIs for notifications, media sessions, services, sensors, and desktop state.

If you download a published self-contained build, you do not need to install the .NET runtime separately. If you want to build from source, install the .NET 10 SDK.

Quick Start

1. Install the Home Assistant integration, v1k70rk4/HASS.Agent.NET10-Integration. It is in the Marketplace (HACS in Home Assistant before 2026.11), so no custom repository is needed: open Settings → Marketplace, search for HASS.Agent (or use the button), download it and restart Home Assistant.

2. Install the Windows app with winget:

   winget install v1k70rk4.HASSAgentNET10
   

   Or download the signed installer from Releases (see Code Signing), or build from source.

3. Run the installer or start HASS.Agent.NET10.exe directly.

4. Open the tray icon and go to settings.

5. On the MQTT page, enable MQTT and enter your broker address and credentials. Whoever can log in to the broker can send this PC commands, so keep that login to yourself (more). Alternatively, on the HA API page, enable the WebSocket connection to Home Assistant (useful for remote access via Nabu Casa or when no MQTT broker is available).

6. On the Capabilities page, choose which features are handled by the tray app vs. the service.

7. On the Sensors page, enable built-in sensors and add custom sensors.

8. Optionally install the Windows service from the Service page.

9. On MQTT the PC turns up on its own under Discovered in Settings → Devices & services of Home Assistant; click Add there. Over the HA API the first PC is added by hand, with the button below and then ; once the integration has a device, further PCs on the HA API are discovered as well.

The integration creates the Home Assistant entities from what the agent advertises, so what you switch on or off in the settings appears and disappears there on its own.

Installer

The setup package is built with Inno Setup. It is also what winget installs and upgrades (winget install v1k70rk4.HASSAgentNET10, winget upgrade v1k70rk4.HASSAgentNET10). winget runs it without its wizard pages, showing only the progress, so the options below keep their defaults on a first install (start on login on, the rest off) and their earlier choices on an upgrade; add --interactive to go through the wizard. Options during install:

• Desktop icon (optional)
• Start automatically on login (default: enabled, sets a registry Run key)
• Install system service (optional)
• Clean install (removes existing settings, API key, and log files — useful for a fresh start)
• Who may use it (first install only): Only me or Every user of this PC, see Who May Use It on This PC

The installer automatically configures a Windows Firewall rule (Private profile, TCP port 5115) for the Local HTTP API, so manual firewall setup is not needed if you turn that on (it is off by default).

During upgrades the installer stops the running tray app, stops the system service if installed, replaces the files, reinstalls/starts the service, and restarts the tray app. On uninstall the firewall rule is removed automatically, and you are asked whether the settings (with the tokens and passwords in them) should go too.

---

Features

	What it does	Details
Notifications	Home Assistant notifications as Windows notifications or in the app's own always-visible window, with pictures, buttons and text fields; what is pressed and typed comes back to Home Assistant as an event.	Notifications
Media player	The active Windows media session as a media_player: title, play / pause, skip, seek, volume, cover art, TTS and announcements; its own page in the app.	Media Player
Sendspin player	The PC as a player of Music Assistant, in sync with the other players of its group; off until turned on, on the Media player page.	Sendspin player
Sensors	Built-in system sensors (CPU, memory, drives, network, battery, session, GPU, camera and microphone in use, and more), each with its own polling profile.	Sensors
Custom sensors	Your own: a process, a service, a drive, an attribute of a built-in sensor, the output of a command or script, a LibreHardwareMonitor value.	Custom Sensors
System commands	Lock, sleep, monitor off, volume, shutdown, restart as buttons and a service call; Hibernate and Log off (off by default).	System Commands
Custom commands	Your own buttons: programs, PowerShell scripts, key presses, links, popup windows.	Custom Commands

Documentation

The full documentation is the website, v1k70rk4.github.io/HASS.Agent.NET10, built from the pages under docs/:

• Get started: install, the installer and winget, security and privacy, coming from HASS.Agent
• Features: notifications, media player, dashboard popup, display and audio, hotkeys, Windows service, updates, who may use it, kiosk mode, Danger Zone
• Commands: system commands and custom commands, with the key names
• Sensors: the built-in sensors, their attributes and polling profiles, custom sensors
• Connection: connection modes, MQTT, HA API, the local HTTP API and the firewall rule
• Building and development: build from source, tests, GitHub Actions, the website

---

Code Signing

Starting with 10.6.8, the release assets (HASS.Agent.NET10-Setup-<version>.exe, its uninstaller, and HASS.Agent.NET10.exe in the zip) are signed with a Certum Open Source code signing certificate:

Issued to	Open Source Developer Viktor Révész
Issued by	Certum Code Signing 2021 CA
SHA-1 thumbprint	0C09522639318AF1069507568599DFC5B7F86EE4
Timestamp	time.certum.pl (the signature stays valid after the certificate expires)

To check a download, open its Properties → Digital Signatures tab, or from the Windows SDK:

signtool verify /pa /v HASS.Agent.NET10-Setup-10.6.8.exe

Signing happens on the maintainer's machine through SimplySign, unlocked with a one-time code from the SimplySign app; the private key lives in Certum's cloud HSM and is never exported. The GitHub Actions build itself is unsigned — the signed files replace its assets on the release. A certificate this new has no SmartScreen reputation yet, so Windows may still show a "Windows protected your PC" prompt for a while; the publisher name on that prompt is what confirms the file is genuine.

From 10.9.0 on, every release also carries a Sigstore signature per asset (<asset>.sigstore.json). A workflow of this repository makes it once the release is out: it checks that the file carries the Certum signature above, then signs it with the workflow's GitHub identity, without any key to keep. It shows that the file is the one this repository published, and it can be checked on any system with cosign:

cosign verify-blob HASS.Agent.NET10-Setup-<version>.exe \
  --bundle HASS.Agent.NET10-Setup-<version>.exe.sigstore.json \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github\.com/v1k70rk4/HASS\.Agent\.NET10/\.github/workflows/sign-release\.yml@'

Privacy Policy

This program will not transfer any information to other networked systems unless specifically requested by the user or the person installing or operating it.

HASS.Agent .NET10 communicates only with:

• the Home Assistant instance and/or MQTT broker configured by the user, to provide its core functionality,
• the GitHub API (api.github.com / github.com), to check for application updates and download release assets.

No telemetry, analytics, or usage data is collected or transmitted.

---

What Changed

10.13.0-beta.1

Beta. Out on the beta channel: tick Beta updates on the Danger Zone page to be offered the beta, or take it from the releases page. The current stable release is 10.12.0, below.

The first beta of 10.13.0: the PC as a Sendspin player of Music Assistant. Works with the Home Assistant integration 10.6.7 or newer; there is no new integration with this one. Signed release.

• The PC as a Sendspin player of Music Assistant. A new card on the Media player page: turn it on, and the PC plays what Music Assistant sends it, in sync with the other players of its group, in another room, on a speaker, on another PC. Music Assistant finds the PC on the network and asks for a pairing token, which the page copies to the clipboard; for a network where it is not found, the PC connects to an address you give. The sound goes to the Windows default output or to a device you choose, and an output that goes away (a headset unplugged, a TV that drops its HDMI audio) is replaced by whatever is there, with the PC staying in its group. An announcement of the app silences the player meanwhile. The PC is the player, whoever is signed in at its screen: a user switch hands the player over within a few seconds, and so does an update of the app. For a PC set up by a script or by Intune, or a kiosk PC with no window, HASS.Agent.NET10.exe --sendspin-token gives the pairing token on the command line. Needs Music Assistant 2.10.7 or newer; the player's entity in Home Assistant comes from Music Assistant's own integration. See Sendspin player.
• Setup lets the app through the Windows firewall for the player (TCP 8928 and UDP 5353, private networks only, the same way as the Local API) and removes the rule at uninstall.
• The library the player brings along (libsodium) is signed with the program; the other libraries beside the program carry Microsoft's signature. See Signed releases.
• The program is 3 MB larger than 10.12.0, not 58. A library of the Sendspin SDK asks for WPF, which this app does not use; it is kept out of the program.
• Two users signed in at once no longer take turns on MQTT. Every signed-in user has a tray app, and both connected with the PC's client id, so the broker closed one for the other every few seconds and the PC flickered in Home Assistant. One app talks now, the one in the session at the PC's screen (on a PC used over Remote Desktop only, the active session's); the other waits and says so on its General page, and a switch of users hands the connection over. See Several users signed in at once.

10.12.0

A release for people coming from the classic HASS.Agent: the app takes over its settings. With it, the dashboard popup keeps its zoom, an uninstaller that stops the app, the service's update notes in the registry, and Russian. Works with the Home Assistant integration 10.6.7 or newer; the notice in Home Assistant for a PC on the old client is fixed in the integration 10.12.0, out at the same time. Built on the same .NET 10.0.14 as 10.11.0. Signed release.

Coming from the classic HASS.Agent

• Coming from the classic HASS.Agent? Its settings come over. When the app finds the classic client's settings on the PC (the LAB02 original or the community one, the tray client and the Satellite Service) and has no connection set up yet, it offers once, when its window opens, to take them over; the Danger Zone's new Import from HASS.Agent button does the same later. What comes over: the MQTT and HA API connection with their secrets kept protected, the device name, the sensors with a built-in counterpart, process, service and PowerShell sensors as custom ones, the system commands, and custom, PowerShell, key, URL and popup window commands. What has no counterpart here is listed by name at the end. The classic client's token is an administrator's as a rule: once the PC is connected, the app offers to swap it for a user of the PC's own. The classic install is only read. See Coming from HASS.Agent.

Translations

• Russian, translated by @vorlocsev in #167, thank you! A Windows set to Russian picks it, or choose it under UI language on the General page; the entity names in Home Assistant can be Russian too, under HA entity language. A text that is cut off or reads oddly is worth an issue.

Also in this release

• The dashboard popup opens at the zoom it was last shown at. A zoom set with Ctrl+scroll (or Ctrl and plus or minus) was gone when the popup closed: the popup makes a new browser each time it opens, and the browser keeps a zoom set this way only for the page it is on. The app keeps the level now, by address and per Windows user, and gives it back to the browser as its default zoom when the page opens again. Ctrl+0 returns to that level rather than to 100%; 100% is a step or two away with Ctrl+plus or Ctrl+minus. A page opened with the WebView command keeps its zoom the same way, each address on its own. Reported in #171.
• Fixed: the uninstaller could not stop the tray app and left its files behind. It only had Windows' Restart Manager, which cannot close a program with no window, and in kiosk mode the task started the app again at once. The uninstaller now does what Setup does before an install: pauses the kiosk task, asks the app to exit, ends it if it stays, and stops the service. This is the uninstaller of this version onwards; removing an older version still needs the app closed by hand.
• Removing the settings at uninstall removes the "HASS.Agent Users" group too. It says who may use those settings; kept with them otherwise, so a reinstall finds the same users allowed.
• The service's update notes moved to the registry. The version the installer replaced, and the version the service last reported, were files in the settings folder, which every user of the PC may write; they are values of the app's key under HKLM now, which only administrators and SYSTEM may write, and are taken only when they look like a version. The old files are removed once.

A bigger release: kiosk mode, for a PC where the person in front of the screen must not change anything; German, and the kiosk texts in Simplified Chinese; a media player that cannot start no longer takes the connection down; and the .NET security update of October. Works with the Home Assistant integration 10.6.7 or newer. Signed release.

Kiosk mode

• Kiosk mode, for a PC where the sensors need the tray app but the person in front of the screen must not change anything. The users ticked in Danger Zone → Kiosk mode get only the tray icon, with Kiosk mode as its tooltip: no window, no menu, no Exit. Notifications, hotkeys and the pages Home Assistant opens with the WebView command work as before. The app starts when they log on and comes back when it is closed: at once when it closes or crashes, within a minute when it is ended in Task Manager. They can read the settings but not change them, and their app logs to a file of their own. The kiosk users are the local group HASS.Agent Kiosk, which an administrator can also change with Windows' own tools or a domain's group policy; a user put in it gets kiosk mode from their next logon. No password: Windows' file permissions keep the settings, and a scheduled task brings the app back. Turning it on needs an administrator (UAC), or HASS.Agent.NET10.exe --kiosk on USER [USER ...] / --kiosk off. See Kiosk mode. Requested in #155.
• An administrator can be a kiosk user too. Asked for in the kiosk mode discussion: on some kiosk PCs the account in front of the screen is an administrator, and hiding the window and the menu from it is what is wanted. The HASS.Agent Kiosk group alone decides: whoever is in it gets the kiosk tray, administrator or not, also when put there with Windows' own tools. The Kiosk mode window lets an administrator be ticked and asks first, since for them it is a cover, not a lock: it is theirs to undo, by leaving the group or turning kiosk mode off (--kiosk off), and the full app is back from the next logon. In the window you cannot tick yourself, as it would lock your own app; the command line lets you name yourself, on purpose.
• Setup pauses the kiosk task while it replaces the files, turns it back on at the end and runs it at once, so a kiosk user has their app back right after an update; uninstalling turns kiosk mode off.
• The Kiosk mode window shows whether you are a kiosk user: saving the list no longer takes a kiosk user out of the group when they open the window before their next logon.

Translations

• German, translated by @Schumey in #150, thank you! A Windows set to German picks it, or choose it under UI language on the General page. The kiosk mode texts are in English for now.
• The kiosk mode texts in Simplified Chinese, translated by @natsu-tsuki in #164, thank you! Kiosk mode is 终端模式 there.
• Longer translations fit. A button is at least as wide as its text on one line: in German "Installieren / aktualisieren" on the Service page and "Auf GitHub mit einem Stern markieren" on the About page were cut off. The API key label on the General page is as wide as its text ("API-Schlüssel").
• "Devices & services" keeps its "&" in the help of turning the PC on and off from Home Assistant, on the Media player page, in English and German: the label took it for a keyboard shortcut.

Also in this release

• A media player that cannot start no longer takes the connection down. On a PC without the Windows media features (an N edition without the Media Feature Pack, Windows Server), or an app started from a scheduled task without a desktop, the media player monitor failed and took the whole MQTT connection with it: it reconnected every ten seconds and the log only showed a Windows error. The sensors and commands stay up now, the log says the player is what failed, and it is tried again on the next connect.
• A finished update is reported by the service when it is installed, also while a tray app runs: the service has every right, the tray app may have few. The version that last ran is one record for the PC now, which every user may write, so the app of a user who can only read the settings does not report the same update at every start.
• Settings that cannot be written back no longer stop the start: they are used as read.

Security

• Built on .NET 10.0.14 (SDK 10.0.403), the .NET security update of October. Its runtime, inside the app, fixes CVE-2026-111497 (Brotli decoder) and completes the fix of CVE-2026-70197 (SocketAsyncEventArgs), which the October 13 update did not fully address. Windows Update does not patch the runtime inside the app, so this release is how the fixes reach it. The other two CVEs of the update are for the Linux tarball and the Blazor WebAssembly packages, which the app does not use.

Older versions are in the changelog.

---

Status

This is a project of its own, not the original LAB02 release line, and it is not affiliated with it. It began as a fork of HASS.Agent and has been developed independently since.

The goal is a focused Windows/Home Assistant companion that keeps the useful HASS.Agent ideas, drops legacy weight, and is built around .NET 10, MQTT or the HA API, and a tray app/service split. The classic client stays with its own project; the integration keeps a legacy branch for it.

License

MIT