A Home Assistant, native app for desktop/laptop devices.
MIT License
Go Hass Agent is an application to expose sensors and controls from a device to Home Assistant. You can think of it as something similar to the Home Assistant companion app for mobile devices, but for your desktop, server, Raspberry Pi, Arduino, toaster, whatever. If it can run Go and Linux, it can run Go Hass Agent!
Out of the box, Go Hass Agent will report lots of details about the system it is running on. You can extend it with additional sensors and controls by hooking it up to MQTT. You can extend it even further with your own custom sensors and controls with scripts/programs.
You can then use these sensors/controls in any automations and dashboards, just like the companion app or any other "thing" you've added into Home Assistant.
As examples of some of the things that can be done with the data published by this app:
[!NOTE] The following list shows all potential sensors the agent can report. In some cases, the actual sensors reported may be less due to lack of support in the system configuration or missing hardware.
xscreensaver
or systemd-logind
support.systemd-logind
.systemd-logind
(and D-Bus)fwupd
running on the system.systemd-logind
./sys/class/hwmon
file system.This project follows semantic versioning. Given a version
number MAJOR.MINOR.PATCH
, the gist of it is:
MAJOR
number change means there breakingMINOR
number change means significant changes and new features have beenPATCH
number change indicate minor changes and bug fixes.Currently, only Linux is supported. Though the code is designed to be extensible to other operating systems. See development information in the docs for details on how to extend for other operating systems.
Head over to the releases page and download the appropriate package for your operating system and/or distribution:
.rpm
..deb
..tar.zst
.Packages (and binaries) are available for amd64, arm (v6 and v7) and arm64 architectures.
For distributions not listed above, you can try the binary, or build it yourself from source (see development docs). Note that while Go is known for statically compiled binaries that “run anywhere”, the Fyne UI toolkit used by Go Hass Agent makes use of shared libraries that may need to be installed as well.
Package signatures can be verified with
cosign. To verify a package, you'll need
to download cosign.pub public key and the .sig
file (downloaded from
releases) that matches the
package you want to verify. To verify a package, a command similar to the
following for the rpm
package can be used:
cosign verify-blob --key cosign.pub --signature go-hass-agent-*.rpm.sig go-hass-agent-*.rpm
Container images are available on ghcr.io. Note that it is recommended to use an image tagged with the latest release version over the latest container image, which might be unstable.
Go Hass Agent runs as a tray icon by default. It is operating system, distribution and desktop-environment agnostic and should manifest itself in any tray of any desktop environment.
On first-run, Go Hass Agent will display a window where you will need to enter some details, so it can register itself with a Home Assistant instance to be able to report sensors and receive notifications.
You will need:
When you have entered all the details, click Submit and the agent should start running and reporting sensors to the Home Assistant instance.
Go Hass Agent will automatically detect if there is no GUI available and run in a “headless” mode with no UI. Registration will need to be completed manually as a first step in such environments.
You can register Go Hass Agent on the command-line with by running:
go-hass-agent --terminal register --token _TOKEN_ --server _URL_
You will need to provide a long-lived token _TOKEN_
and the URL of your Home
Assistant instance, _URL_
.
Once registered, running Go Hass Agent again with no options should start tracking and sending sensor data to Home Assistant.
If desired, headless mode can be forced, even in graphical environments, by
specifying the --terminal
command-line option.
If you want to run Go Hass Agent as a service on a headless machine, see the FAQ.
There is rough support for running Go Hass Agent within a container. Pre-built images are available for armv6/v7, arm64 and amd64 architectures. The image is based on the latest stable Alpine Linux release.
To register the agent running in a container, run the following:
podman run --rm --hostname go-hass-agent-container \
--network host \
--volume go-hass-agent:/home/go-hass-agent:U \
ghcr.io/joshuar/go-hass-agent:VERSION register \
--server https://some.server:port \
--token 'longlivedtoken'
VERSION
to the latest version. Do not use latest, which is unstable and likely to break.
--server
to your Home Assistant server.--token
to a long-lived token retrieved from Home--rm
) as weOnce registered, run the agent with:
podman run --hostname go-hass-agent-container --name my-go-hass-agent \
--network host \
--volume go-hass-agent:/home/go-hass-agent:U \
--volume /proc:/host/proc:ro --volume /sys:/host/sys:ro \
--volume /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket:ro \
--volume /run/user/1000/bus:/run/user/1000/bus:ro \
--device /dev/video0:/dev/video0
ghcr.io/joshuar/go-hass-agent:VERSION # add any Go Hass Agent options here.
Change the value passed to --name
to a unique name for your running container
and --hostname
for the hostname that will be presented to Home Assistant
during registration.
All the other volume mounts are optional, but functionality and the sensors reported will be severely limited without them:
--volume /proc:/host/proc:ro --volume /sys:/host/sys:ro
:
--volume /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket:ro
--volume /run/user/1000/bus:/run/user/1000/bus:ro
1000
to the uid of--device /dev/video0:/dev/video0
When running, Go Hass Agent will appear as a device under the Mobile App integration in your Home Assistant instance. It should also report a list of sensors/entities you can use in any automations, scripts, dashboards and other parts of Home Assistant.
The configuration is located in a file called preferences.toml
in
CONFIG_HOME/go-hass-agent/
where CONFIG_HOME
will OS-dependent:
~/.config
.~/Library/Application Support
.LocalAppData
.While the configuration can be edited manually, it is recommended to let the agent manage this file.
Go Hass Agent supports utilising scripts to create sensors. In this way, you can extend the sensors presented to Home Assistant by the agent. Note that as the agent is a “mobile app” in Home Assistant, any script sensors will be associated with the Go Hass Agent device in Home Assistant.
Each script run by the agent can create one or more sensors and each script can run on its own schedule, specified using a Cron syntax.
scripts
folder under the configuration directoryAny typical scripting language that can be invoked with a shebang can be used for scripts. All scripts do not need to be written in the same language. So or the typical shells can be used such as Bash, Sh, Zsh, Fish, Elvish. Scripting languages such as Python, Perl, and Ruby can also be used.
All scripts should produce output that is either valid JSON, YAML or TOML. Scripts do not need to use the same format; you can have one script that produces JSON and another that produces TOML. All scripts will need to output the following fields:
schedule
field containing a cron-formatted schedule.sensors
field containing a list of sensors.Sensors themselves need to be represented by the following fields:
sensor_name
: the friendly name of the sensor in Home Assistant (e.g., Mysensor_icon
: a Material Designmdi:icon_name
.sensor_state
: the current value of the sensor. For numerical states, withouttrue
/false
in quotes.The following optional fields can also be specified, which help control the display in Home Assistant.
sensor_units
: the units for the state value.sensor_type
: the type of sensor. If this is a binary sensor with a booleansensor_device_class
: a Home Assistant Deviceinternal/hass/sensor/deviceClass.go
).sensor_device_class
, it is likely required to set an appropriatesensor_units
as well.sensor_state_class
: the Home Assistant Statesensor_attributes
: any additional attributes to be displayed with theThe following examples show a script that produces two sensors, in different output formats.
JSON output can be either compressed:
{"schedule":"@every 5s","sensors":[{"sensor_name": "random 1","sensor_icon": "mdi:dice-1","sensor_state":1},{"sensor_name": "random 2","sensor_icon": "mdi:dice-2","sensor_state_class":"measurement","sensor_state":6}]}
Or pretty-printed:
{
"schedule": "@every 5s",
"sensors": [
{
"sensor_name": "random 1",
"sensor_icon": "mdi:dice-1",
"sensor_state": 2
},
{
"sensor_name": "random 2",
"sensor_icon": "mdi:dice-2",
"sensor_state_class": "measurement",
"sensor_state": 6
}
]
}
schedule: '@every 5s'
sensors:
- sensor_name: random 1
sensor_icon: mdi:dice-1
sensor_state: 8
- sensor_name: random 2
sensor_icon: mdi:dice-2
sensor_state_class: measurement
sensor_state: 9
schedule = '@every 5s'
[[sensors]]
sensor_icon = 'mdi:dice-1'
sensor_name = 'random 1'
sensor_state = 3
[[sensors]]
sensor_icon = 'mdi:dice-2'
sensor_name = 'random 2'
sensor_state = 3
sensor_state_class = 'measurement'
For a binary sensor, the output should have sensor_type
set to “binary” and
the sensor_state
as true
or false
(without quotes). As an example in
compressed JSON format:
{"schedule":"@every 10s","sensors":[{"sensor_name":"random 4","sensor_type":"binary","sensor_icon":"mdi:dice-3","sensor_state":false}]}
The schedule
field is used to specify the schedule or interval on which the
script will be run by the agent. Each script is run on its own schedule. All
sensors and their values should be returned each time the script is run. The
format is documented by the cron Golang
package.
In most cases, it is presumed that the script needs to be run on some interval
of time. In that case, the easiest way to specify that is with the @every <duration>
as per the example output such as:
@every 5s
: every 5 seconds@every 1h30m
: every 1 and a half hours.Or a pre-defined schedule:
@hourly
.@daily
.@weekly
.@monthly
.@yearly
.However, more cron formats are supported:
"30 * * * *"
: every hour on the half hour."30 3-6,20-23 * * *"
: in the range 3-6am, 8-11pm."CRON_TZ=Asia/Tokyo 30 04 * * *"
: at 04:30 Tokyo time every day.[!WARNING] Some schedules, while supported, might not make much sense.
Running scripts can be dangerous, especially if the script does not have robust error-handling or whose origin is untrusted or unknown. Go Hass Agent makes no attempt to do any analysis or sanitisation of script output, other than ensuring the output is a supported format. As such, ensure you trust and understand what the script does and all possible outputs that the script can produce. Scripts are run by the agent and have the permissions of the user running the agent. Script output is sent to your Home Assistant instance.
[!NOTE] MQTT Sensors and Controls are not enabled by default.
If Home Assistant is connected to MQTT, you can also configure Go Hass Agent to connect to MQTT, which will then expose some sensors and controls in Home Assistant to control the device running the agent. Additionally, you can configure your own custom controls to run either D-Bus commands or scripts and executables.
To configure the agent to connect to MQTT:
Right-click on the Go Hass Agent tray icon.
Select App Settings.
Toggle Use MQTT and then enter the details for your MQTT server (not your Home Assistant server).
Click Save.
Restart Go Hass Agent.
For users running Go Hass Agent in headless mode.
Stop Go Hass Agent if running.
Use the config
command option to specify your MQTT server parameters:
go-hass-agent config --mqtt-server=tcp://localhost:1883 --mqtt-user=some-user --mqtt-password=superseret
--mqtt-server
is required.Restart Go Hass Agent.
After the above steps, Go Hass Agent will appear as a device under the MQTT integration in your Home Assistant.
[!NOTE] Go Hass Agent will appear in two places in your Home Assistant. Firstly, under the Mobile App integration, which will show all the sensors that Go Hass Agent is reporting. Secondly, under the MQTT integration, which will show the controls and sensors exposed over MQTT for Go Hass Agent. Unfortunately, due to limitations with the Home Assistant architecture, these cannot be combined in a single place.
When MQTT is configured, Go Hass Agent will also listen on MQTT and run arbitrary D-Bus commands.
The agent will subscribe to the MQTT topic gohassagent/HOSTNAME/dbuscommand
(where HOSTNAME
is the short hostname of the device running Go Hass Agent) on
the configured MQTT broker and listens for messages with a JSON payload (shown
below) that contains details of the D-Bus method to call. When a message is
recieved, the method will be executed. The easiest way to use this feature is
with the mqtt.publish
service in Home Assistant.
As an example, the following will create a notification on the device running Go Hass Agent (YAML format used for readability):
service: mqtt.publish
data:
qos: 0
topic: gohassagent/HOSTNAME/dbuscommand
payload: |
{
"bus": "session",
"path": "/org/freedesktop/Notifications",
"method": "org.freedesktop.Notifications.Notify",
"destination": "org.freedesktop.Notifications",
"args": [
"my-app-name",
0,
"my-icon",
"summary",
"body",
[],
{},
5000
],
"use_session_path": false
}
You can optionally create a commands.toml
file under the configuration
directory (see Configuration Location with custom
commands to be exposed in Home Assistant.
Supported control types and expected input/output:
display
can be optionally set in the control configuration to specify howauto
, box
or slider
. The default if display
is not set isauto
, where Home Assistant will decide how the control will betype
can be optionally set in the control configuration to specify whetherint
or float
values. The default will be int
if[!NOTE] Commands run as the user running the agent. Commands do not invoke the system shell and does not support expansion/glob patterns or handle other expansions, pipelines, or redirections typically done by shells.
States are not kept in sync. This is most important for all controls besides buttons. For example, if you configure a switch, any changes to the state you make outside of Home Assistant will not be reflected in Home Assistant automatically.
Each command needs the following definition in the file:
# "control" should be replaced with one of the control types above.
[[control]]
# name is required.
# The pretty name of the command that will be the label in Home Assistant.
name = "my command name"
# exec is required.
# The path to the command to execute.
# Arguments can be given as required, and should be quoted if they contain spaces.
exec = '/path/to/command arg1 "arg with space"'
# icon is optional.
# The material design icon to use to represent the control in Home Assistant.
# See https://pictogrammers.com/library/mdi/ for icons you can use.
icon = "mdi:something"
# display is optional and only relevant for certain controls.
# How the control will be shown in Home Assistant. Refer to the control type for valid values.
display = "displayValue"
For number controls, additional configuration may be specified (default values shown):
# type is optional.
# Whether this number control has int or float values. Default is "int".
type = "int"
# min is optional.
# The minimum value of the number. Default is 0.
min = 0
# max is optional.
# The maximum value of the number. Default is 100.
max = 100
# step is optional.
# The amount to change the value by (i.e., increment/decrement), if applicable. Default is 1.
step = 1
The following shows an example that configures various controls in Home Assistant:
[[button]]
name = "My Command With an Icon"
exec = 'command arg1 arg2 "arg3"'
icon = "mdi:chat"
[[button]]
name = "My Command"
exec = "command"
[[switch]]
name = "Toggle a Thing"
exec = "command arg1 arg2"
[[number]]
name = "My number slider"
exec = "command"
display = "slider"
min = 1
max = 500
step = 5
There is a significant discrepancy in permissions between the device running Go Hass Agent and Home Assistant.
Go Hass Agent runs under a user account on a device. So the above controls will only work where that user has permissions to run the underlying actions on that device. Home Assistant does not currently offer any fine-grained access control for controls like the above. So any Home Assistant user will be able to run any of the controls. This means that a Home Assistant user not associated with the device user running the agent can use the exposed controls to issue potentially disruptive actions on a device that another user is accessing.
Go Hass Agent uses Mage for development.
Use the following mage invocation in the project root directory:
go run github.com/magefile/mage -d build/magefiles -w . build:full
This will build a binary and place it in dist/go-hass-agent-amd64
.
Go Hass Agent can also be built for arm (v6/v7) and arm64 with
cross-compilation. This is only supported on Ubuntu or Alpine Linux as the
host for cross-compiles. To build for a different architecture, set the
TARGETPLATFORM
environment variable:
export TARGETPLATFORM=linux/arm64 # or linux/arm/v6 or linux/arm/v7
Install the target architecture libraries for cross-compilation:
go run github.com/magefile/mage -d build/magefiles -w . preps:deps
Then the commands for building and packaging above should work as expected.
[!NOTE] The devcontainer has all the necessary compilers and libraries installed for cross-compilation.
Go Hass Agent uses nfpm to create packages for Fedora, Arch, and Ubuntu/Debian.
To build packages, use the following invocations:
go run github.com/magefile/mage -d build/magefiles -w . package:nfpm
The above mage actions will install the necessary tooling for packaging, if needed.
dist/
folder.A Dockerfile that you can use to build an image can be found here.
You can build an image with a command like the following (using Podman):
podman build --file ./Dockerfile --tag go-hass-agent
As with building a binary, cross-compliation is supported:
# use either linux/arm64, linux/arm/v7 or linux/arm/v6
podman build --file ./Dockerfile --platform linux/arm/v7 --tag go-hass-agent
[!NOTE] By default, the container will run as a user with uid/gid 1000/1000. You can pick a different uid/gid when building by adding
--build-arg UID=999
and--build-arg GID=999
(adjusting the values as appropriate).
This repository is using conventional commit messages. This provides the ability to automatically include relevant notes in the changelog. The TL;DR is when writing commit messages, add a prefix:
feat:
for a new feature, like a new sensor.fix:
when fixing an issue.refactor:
when making non-visible but useful code changes.Please read the Code of Conduct
Check out what I'm working on for future releases.
[!NOTE]
While the agent will stop sending updates for a disabled sensor, it will not stop gathering the raw data for the sensor.
--terminal
command-line option. This should put the memory usageGenerally, Go Hass Agent will try to reserve sensor renames to major version upgrades, which may contain breaking changes.
Unfortunately, sometimes sensor names may inadvertently get changed in non-major releases.
Regrettably, there is no way to rename the sensors in Home Assistant such that long-term statistics and existing automations and dashboards continue to work uninterrupted.
For long-term statistics, you can remove the old sensors manually, under Developer Tools→Statistics in Home Assistant, for example. The list should contain sensors that are no longer “provided” by the agent. Or you can wait until they age out of the Home Assistant long-term statistics database automatically.
For automations and dashboards the repairs integration, will direct you to any broken items and how to fix them.
Stop Go Hass Agent if already running.
Open your Home Assistant mobile_app integrations page:
Locate the entry for your existing Go Hass Agent device. It should be named the same as the hostname of the device it is running on.
Click on the menu (three vertical dots) at the right of the entry:
Choose Delete.
From a terminal, run the agent with the command: go-hass-agent register --force
(add --terminal --server someserver --token sometoken
for
non-graphical registration).
The agent will go through the initial registration steps. It should report that registration was successful.
Restart the agent.
loginctl list-users
and check that your user has LINGER set to “yes”. If not, runloginctl enable-linger
.systemctl --user enable go-hass-agent && systemctl --user start go-hass-agent
.systemctl --user status go-hass-agent
. The agentNo. None of the built-in sensors (or commands if MQTT is enabled) require any privileges. The agent will refuse to run if it is started with privileges. For custom scripts or commands that need privileges, there are most likely ways for the script/command to elevate to the privileges it needs as part of its execution, rather than having the agent run with privileges and the script/command inherit those.