This page explains the basics behind HASS.Agent: what is it and what can it do. We'll be using the abbreviation HA for Home Assistant, so when HA is mentioned, it refers to your Home Assistant instance.
Tip: you can use Home Assistant's glossary to look up words you don't know yet.
Tip: EverythingSmartHome's youtube video is a great guide to get you started: Control Your Windows PC With Home Assistant!. Note that it is based on an older version, so for instance the mentioned missing 'actionable notifications' are already implemented.
In general, HASS.Agent is a client (companion) application for Home Assistant. It's being developed for Windows, with Windows 10 and 11 (fully up-to-date) in mind - previous versions or unpatched systems may work.
The communication goes both ways: HASS.Agent can send data to HA, and HA can send data to HASS.Agent. In other words: you can use HASS.Agent to control and inform HA, and you can use HA to control HASS.Agent.
Globally, these are the functionalities:
|Commands||Control your PC from HA.
Example: lock your session, open notepad or emulate a keypress.
|Sensors||Send PC telemetry to HA.
Example: cpu load, is your webcam active or is the current user active.
|Quick Actions||Trigger any HA entity.
Example: turn on your lights or open the garage door.
|Notifications||Receive a notification from HA, and show it as a Windows notification.
Example: image of who's at the front door.
|Media Player||Control your PC from HA as if it were a mediaplayer.
Example: see what Spotify song's playing, or send a text-to-speech message.
|WebView||Show any webpage, without launching a browser.
Example: show a HA dashboard when rightclicking HASS.Agent's tray icon.
|Satellite Service||Process commands and sensors even when no user's logged in.
Example: shutdown your PC at any time, locked or not.
Let's go over every function for a bit more in-depth.
Commands have their own introduction page: Command Basics.
If you want to go a bit more advanced, have a look at the actions page: Actions Usage and Examples. Actions allow you to send variables alongside your command, so you can for example have you HA automation decide what URL you want to show.
Sensors allow you to send all sorts of telemetry from your PC to HA. A few common examples are what's the current cpu load, are you using your webcam/mic, are you logged in or is your session locked - but there are over 30 of them, so there's much more to explore.
When you create a new sensor, it shows up in HA as an entity:
To find the entities, go to your HA instance, and press
c. This will show the search bar. Now type
devices and press enter. In the
Search devices bar that's shown on top, type the name of your HASS.Agent instance:
Tip: you can always find (and change) the name of your HASS.Agent instance by clicking on the
configurationbutton in the main window.
If your HASS.Agent is properly configured, your pc will now show as a result. You can easily verify it's a HASS.Agent instance by confirming it says
LAB02 Research under the
Click on your pc to see what commands and sensors are currently configured.
Some sensors have multiple relevant data points. For instance, if you add a storage sensor, statistics for all your disks will get sent. You can easily see which sensors are multi-value through this column:
And here you can see the multiple sensors being added (they all start with the name you gave it):
One of the reasons for developing HASS.Agent was the ability to easily trigger HA entities. For instance, if I want to turn on a light, I don't want to open an app or browser and go to the right dashboard. Nor do I always want to say it out load to a Google Home-device of sorts. To make that possible, HASS.Agent has Quick Actions.
You configure them once by selected the desired entity and the desired state:
And from that on you can either execute them by their individual hotkey, or pull up the list of quick actions by their global hotkey:
Another reason for HASS.Agent's creation was the ability to receive notifications from HA. For instance: someone presses the doorbell, and you get a notification with a picture of the guest on your PC. Because I'm usually listening to music with earpods in while working, this would be a good way to get my attention.
Use the integration installation to help get you started, or the notifications example page for inspiration.
The mediaplayer allows you to use your HASS.Agent as a mediaplayer device: see and control what's playing (regardless of what application you're actually using to play media), and send text-to-speech notifications.
Use the integration installation to help get you started or the mediaplayer example page for inspiration.
The webview capability is not something you can see directly like commands and sensors, but more of an underlying technique. It's basically a way to show a website, without having to launch a browser.
There are currently two implementations for the webview component.
This command allows you to open any webpage with some extra configuration, like where on your monitor, and what size. You can use this to launch a predefined URL (like a HA dashboard) or even dynamically when using an Action.
By default, when you right-click the HASS.Agent tray icon (near your clock on the taskbar) you'll get a simple menu. However, you can also configure (through
Tray Icon) to show a webview. This is really neat if you want to quickly show a dashboard with a bit more options than the quick actions:
HASS.Agent is a very easy (at least I think so) tool to configure your sensors and commands. There is however a downside: if you're not logged into Windows, it won't load, so your sensors and commands won't run. Another issue is security-wise: HASS.Agent runs with the least possible privileges, but that means you can't perform commands that would require elevation.
To allow for all that, the satellite service was added. This is a Windows service which runs in the background, and allows you to run sensors and commands without having to be logged in - and with elevated privileges (be careful though when running potential hazardous commands).
You can start tinkering by clicking the
satellite service button in the main window:
The satellite service copies HASS.Agent's MQTT settings, except the
client id (which is required to be unique). If you want to set another user, you can do so on the
MQTT tab. Otherwise, jump straight into adding commands and sensors! HASS.Agent will warn you when a certain command or sensor can't be run via the satellite service.
Remember to click the
send and activate button after adding or modifying your entities!
Tip: if the MQTT status remains
disconnected, restart the service (go to
Configurationin the main window, then tab
Satellite Serviceand click
start servicerespectively) and check again.
Note: you can't do anything that would require an UI in the satellite service - for instance, you can't open a browser. It wouldn't show.
If you need more info or want to talk, please feel free to reach out:
Github Tickets: Report bugs, feature requests, ideas, tips, ..
Discord: Get help with setting up and using HASS.Agent, report bugs or just talk about whatever.
Home Assistant forum: Bit of everything, with the addition that other HA users can help as well.