Go Hass Agent

A Home Assistant, native app integration for desktop/laptop devices.

🎉 Features

📈 Sensors

This app will add some sensors to a Home Assistant instance:

• Device location.
• Current active application and list of running applications.
• Battery status (for example, laptop battery and any peripherals).
• Network status (for example, network connection status, internal and external IP addresses and Wi-Fi details where relevant).
• Memory and swap usage (total/free/used).
• Disk usage.
• Load Averages.
• Uptime.
• Power profile.
• Screen lock.
• Problems detected by ABRT.
• User-specified script output.

A full list of sensors can be found in the docs.

The code can be extended to add additional sensors. See the development docs for details.

🕹️ Controls (via MQTT)

If you have Home Assistant configured with MQTT, you can set up Go Hass Agent to respond to commands from Home Assistant. See the docs.

🤔 Use-cases

As examples of some of the things that can be done with the data published by this app:

• Change your lighting depending on:
  • What active/running apps are on your laptop/desktop. For example, you could set your lights dim or activate a scene when you are gaming.
  • Whether your screen is locked or the device is shutdown/suspended.
• With your laptop plugged into a smart plug that is also controlled by Home Assistant, turn the smart plug on/off based on the battery charge. This can force a full charge/discharge cycle of the battery, extending its life over leaving it constantly charged.
• Like on mobile devices, create automations based on the location of your laptop running this app.
• Monitor network the data transfer amount from the device, useful where network data might be capped.
• Monitor CPU load, disk usage and any temperature sensors emitted from the device.
• Receive notifications from Home Assistant on your desktop/laptop. Potentially based on or utilising any of the data above.

See also the FAQ.

🤝 Compatibility

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.

⬇️ Installation

📦 Packages

Head over to the releases page and download the appropriate package for your operating system and/or distribution:

• Fedora: use the .rpm.
• Ubuntu: use the .deb.
• Debian: use the .tar.xz.
• Arch: use the .tar.zst.

Other 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

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.

🖱️ Usage

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.

First-run

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:

• A long-lived access token. You can generate one on your account profile page.
• The web address (URL) on which a Home Assistant instance can be found.
  • Go Hass Agent will try to auto-detect this for you, and you can select it in the Auto-discovered servers list. Otherwise, you will need to select Use Custom Server?, and enter the details manually in Manual Server Entry.

When you have entered all the details, click Submit and the agent should start running and reporting sensors to the Home Assistant instance.

Running “Headless”

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.

Running in a container

There is rough support for running Go Hass Agent within a container. Pre-built images are available.

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/gouser \
  ghcr.io/joshuar/go-hass-agent register \
  --server https://some.server:port \
  --token longlivedtoken

Adjust the --server and --token values as appropriate.

Once registered, run the agent with:

podman run --hostname go-hass-agent-container --name my-go-hass-agent \
  --network host \
  --volume go-hass-agent:/home/gouser \
  --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 \
  ghcr.io/joshuar/go-hass-agent

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.

Regular Usage

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.

Issues, Feature Requests, Contributing

• Found an issue? Please report it!
• Have a suggestion for a feature? Want a particular sensor/measurement added? Submit a feature request!
• Want to help develop Go Hass Agent? See the contributing guidelines.

Versioning

This project follows semantic versioning. Given a version number MAJOR.MINOR.PATCH, the gist of it is:

A MAJOR number change means breaking changes from the previous release
A MINOR number change means significant changes and new features have been added, but not breaking changes 
A PATCH number change indicate minor changes and bug fixes

🙌 Acknowledgements

The app icon is taken from the Home Assistant project.

License

MIT