# go-hass-agent: exposing a desktop or server to Home Assistant > go-hass-agent is a Go program that publishes the sensors, controls and events of a desktop or server to Home Assistant, the way the official companion app does for phones. It talks to Home Assistant over its native app WebSocket API, and it also works as a standalone MQTT client. **joshuar/go-hass-agent** — A Home Assistant, native app for desktop/laptop devices. - Repository: https://github.com/joshuar/go-hass-agent - Stars: 593 · Forks: 34 - Language: Go - License: MIT - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/joshuar-go-hass-agent ## The companion app idea, applied to machines Go Hass Agent is an application to expose sensors, controls and events from a device to Home Assistant, and the description in the README is that you can think of it as something similar to the Home Assistant companion app for mobile devices, but for your desktop, server, Raspberry Pi and similar. That framing is useful because it sets expectations about what you get. On a phone, the companion app reads the things a phone knows about, battery, connectivity, the apps running, and it can trigger notifications. On a Linux workstation the equivalents are the active application, the display settings, the media player state, whether the webcam and microphone are in use, battery, memory, disk, network and CPU. The project is written in Go, the licence is MIT, and the primary language in the repository metadata is Go with a JavaScript front end alongside it. ## The sensor list, and why it is Linux heavy The table of contents is unusually long, and the reason is that the sensor catalogue is the product. The Linux section alone covers the active application and total running apps, desktop settings, the global MPRIS state for media players, whether the webcam and microphone are in use, battery details, memory stats, disk usage and activity monitoring, disk SMART monitoring, network connection and activity monitoring, CPU stats, power state, screen lock, user monitoring, system information, hardware monitoring and location. Under controls there is volume control, webcam control, power control and D-Bus integration, and under events there are user sessions and out of memory events. Then there is a section for all operating systems, which implies a smaller cross platform set, and the FAQ includes Linux specific questions about disk rate sensors reading non-zero while the IO operations in progress sensor is zero, about what the firmware security sensor means, and about hardware sensors reporting incorrect values. That is an honest catalogue, and the caveats tell you where the reliability sits. ## Script sensors: your own values, in JSON, YAML or TOML The most flexible part of the project is the script sensors, where you run your own code on the machine and publish the result. The README documents the requirements, a list of supported scripting languages, and the output format with examples in JSON, YAML and TOML. Scheduling is handled at three levels, with cron expressions, pre-defined intervals and arbitrary intervals, and the implementation uses the go-quartz scheduler library. There are separate security implications sections for the script sensors and for the MQTT sensors and controls, which tells you the author takes the local execution surface seriously, and you should too, because a script sensor that runs on the agent host is code you are choosing to execute on your machine on a schedule. ## MQTT as an alternative to the native app API Most of the ecosystem communication is done through Home Assistant's native app integration, which is the WebSocket API the official mobile apps use, and the repository links the Home Assistant developer documentation for it. But the project also supports MQTT, and the FAQ asks whether the agent can run in an MQTT-only mode, which it can. That matters in practice, because MQTT is the transport most Home Assistant installations already have configured, and the FAQ also asks about the agent running as root or with privileges, which is a question you have to answer for yourself. The MQTT side has its own configuration section, plus custom D-Bus controls and other custom commands, and its own security implications section. The Go dependencies confirm both paths are real: the Paho MQTT client, the godbus D-Bus library, and the go-hass-anything library that the project uses to talk to Home Assistant. ## A Go service with a small web front end The repository is a Go module with a Go 1.27.1 directive and a directory layout that separates the concerns: an `agent/` directory, a `device/` directory for the platform specific sensor implementations, a `hass/` directory for the Home Assistant side, a `server/` directory for the built in web server, a `scheduler/` directory, a `config/` directory, a `validation/` directory, a `schema/` directory, a `web/` directory, a `logging/` directory, a `pkg/` directory, a `cli/` directory and a `models/` directory. The HTTP stack is chi with the alice and nosurf middlewares, configuration is handled by koanf with TOML parsers and providers, and the templating is done with the templ package. The front end is a separate package.json with Tailwind CSS, daisyUI, htmx and hyperscript, built with esbuild and the Tailwind CLI, and the two build scripts are short: ```json "build:js": "esbuild ./web/assets/scripts.js --bundle --minify --outdir=./web/content/", "build:css": "tailwindcss -i ./web/assets/styles.css -o ./web/content/styles.css --minify", ``` There is also a `web/content/` directory in the tree where the built assets land, which is how the binary serves its own interface without a separate asset pipeline at runtime. ## The container image, and how the binary is built The Dockerfile in the repository is a multi-stage Alpine build, and the details matter if you plan to run the agent in a container. The base images are pinned by digest, both the Go toolchain image and the Alpine one, and the builder stage copies the Go toolchain out of the official image before installing the build dependencies. The frontend is built first with npm, and the comment notes that bun is not used because it is unsupported on some of the architectures supported. The binary is then built with CGO disabled and a version stamped into it, and compressed with upx. The runtime stage is plain Alpine with the environment variable that stops the agent logging to a file, since a container should log to stdout: ```dockerfile ENV GOHASSAGENT_NOLOGFILE=1 ``` The final image carries the standard Opencontainers labels for the title, source and description. The project also ships a systemd unit and an autostart path for desktops, and a `systemd` guide on servers, so the deployment paths are: a package, a container, or a service you run yourself. ## Where this is the wrong choice The limits are worth naming. First, it is an agent, so every machine you want to see needs one, and unlike the phone companion app there is no app store to install it from, so you are managing binaries or containers on each host. Second, the sensor coverage is uneven, and the FAQ admits it, with entries on disk rate sensors reading oddly, on the meaning of the firmware security sensor and on hardware sensors reporting incorrect values, which means a dashboard built from these is a picture of what the kernel and the hardware were willing to report, not a measurement you can defend. Third, the local execution model is a real security surface, since script sensors run code on the host and MQTT controls accept commands, and both have security implications sections, so a deployment has to think about who may publish commands to your machine. Fourth, the project is versioned like a product, with the v14 series and a BREAKING_CHANGES.md at the root, so a version jump can change sensor names, and the FAQ even has an entry about updated agents producing duplicate, removed or disabled sensors, which is a symptom of a design where the sensor set is generated at runtime. Fifth, it is a project, not a product, and there is no support commitment behind it beyond the issue tracker. ## Conclusion go-hass-agent fits a Home Assistant user with a Linux workstation, a home server or a Raspberry Pi who wants the same kind of machine telemetry the companion app gives on mobile, and who is willing to run an agent on each machine. It is the wrong choice if you want the sensors to appear without an agent, because the design is agent based, and the wrong choice if you cannot grant the agent the D-Bus and device access that the Linux sensors need. Before you deploy it, read the FAQ entries on running as root and on the agent's resource usage, and check the compatibility section, since the sensor set depends on the operating system and on what the kernel exposes. The last push was on 2026-10-19 with v14.17.0 released on 2026-09-28, and the licence is MIT. ## FAQ ### What does go-hass-agent do? It is an application to expose sensors, controls and events from a device to Home Assistant, working much like the Home Assistant companion app does for mobile devices but for a desktop, server or Raspberry Pi. On Linux it covers the active application, media player state, webcam and microphone use, battery, memory, disk, network and CPU, plus controls for volume, webcam and power, and events for user sessions and out of memory. ### How does go-hass-agent talk to Home Assistant? Through the native app integration, the WebSocket API the official mobile apps use, and the project also supports MQTT, with an FAQ entry confirming the agent can run in an MQTT-only mode. There are separate configuration and security implications sections for the MQTT sensors and controls. ### Can go-hass-agent publish my own values? Yes, through script sensors, where you run your own code on the machine and return the result. The output can be JSON, YAML or TOML, and scheduling supports cron expressions, pre-defined intervals and arbitrary intervals. ### Does go-hass-agent need to run as root? The README includes an FAQ entry asking whether the agent can or does run as root or with privileges, and a separate entry on the agent's CPU and memory usage. The Linux sensor set draws on D-Bus and device information, so the permissions the agent needs depend on which sensors you enable. ## Sources - [Issues](https://github.com/joshuar/go-hass-agent/issues) - [joshuar/go-hass-agent on GitHub](https://github.com/joshuar/go-hass-agent) - [License: MIT](https://github.com/joshuar/go-hass-agent/blob/main/LICENSE) - [README](https://github.com/joshuar/go-hass-agent/blob/main/README.md) - [Releases](https://github.com/joshuar/go-hass-agent/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/joshuar-go-hass-agent