{"id":15086217,"url":"https://github.com/joshuar/go-hass-agent","last_synced_at":"2026-04-01T20:34:14.690Z","repository":{"id":152786439,"uuid":"626668603","full_name":"joshuar/go-hass-agent","owner":"joshuar","description":"A Home Assistant, native app for desktop/laptop devices.","archived":false,"fork":false,"pushed_at":"2026-03-21T00:34:22.000Z","size":12194,"stargazers_count":479,"open_issues_count":24,"forks_count":20,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-03-21T13:51:17.499Z","etag":null,"topics":["automation","fyneapp","go","golang-app","hass","home-assistant","home-automation","linux-app","monitoring-tool","mqtt","scripting"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joshuar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"ko_fi":"astralcars"}},"created_at":"2023-04-11T23:48:14.000Z","updated_at":"2026-03-21T00:33:20.000Z","dependencies_parsed_at":"2024-02-07T00:27:18.572Z","dependency_job_id":"fab42014-7d6c-4d36-9962-d64494e28b95","html_url":"https://github.com/joshuar/go-hass-agent","commit_stats":{"total_commits":1919,"total_committers":8,"mean_commits":239.875,"dds":"0.10526315789473684","last_synced_commit":"895125fb530e475086ffa1ce9b8dfec0c2c67a5a"},"previous_names":[],"tags_count":137,"template":false,"template_full_name":null,"purl":"pkg:github/joshuar/go-hass-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshuar%2Fgo-hass-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshuar%2Fgo-hass-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshuar%2Fgo-hass-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshuar%2Fgo-hass-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joshuar","download_url":"https://codeload.github.com/joshuar/go-hass-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshuar%2Fgo-hass-agent/sbom","scorecard":{"id":125689,"data":{"date":"2025-08-16T01:40:19Z","repo":{"name":"github.com/joshuar/go-hass-agent","commit":"18e7a67419c714099e472db666db93914abc1569"},"scorecard":{"version":"v5.2.1","commit":"ab2f6e92482462fe66246d9e32f642855a691dc1"},"score":7.8,"checks":[{"name":"Code-Review","score":0,"reason":"Found 0/4 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#code-review"}},{"name":"Dependency-Update-Tool","score":10,"reason":"update tool detected","details":["Info: detected update tool: Dependabot: .github/dependabot.yml:1"],"documentation":{"short":"Determines if the project uses a dependency update tool.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#dependency-update-tool"}},{"name":"Maintained","score":10,"reason":"30 commit(s) and 7 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#binary-artifacts"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: SECURITY.md:1","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#security-policy"}},{"name":"Token-Permissions","score":10,"reason":"GitHub workflow tokens follow principle of least privilege","details":["Info: jobLevel 'packages' permission set to 'read': .github/workflows/analysis-codeql.yml:24","Info: jobLevel 'actions' permission set to 'read': .github/workflows/analysis-codeql.yml:25","Warn: jobLevel 'contents' permission set to 'write': .github/workflows/build.yml:24","Warn: jobLevel 'contents' permission set to 'write': .github/workflows/build.yml:48","Warn: jobLevel 'contents' permission set to 'write': .github/workflows/build.yml:153","Info: jobLevel 'contents' permission set to 'read': .github/workflows/build.yml:250","Info: jobLevel 'pull-requests' permission set to 'read': .github/workflows/test.yml:73","Info: topLevel 'contents' permission set to 'read': .github/workflows/analysis-codeql.yml:12","Info: topLevel 'contents' permission set to 'read': .github/workflows/analysis-nilaway.yml:10","Info: topLevel 'contents' permission set to 'read': .github/workflows/build.yml:12","Info: topLevel permissions set to 'read-all': .github/workflows/scorecard.yml:18","Info: topLevel 'contents' permission set to 'read': .github/workflows/test.yml:10"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":10,"reason":"all dependencies are pinned","details":["Info:  19 out of  19 GitHub-owned GitHubAction dependencies pinned","Info:  28 out of  28 third-party GitHubAction dependencies pinned","Info:   2 out of   2 containerImage dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#pinned-dependencies"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#license"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#cii-best-practices"}},{"name":"Packaging","score":10,"reason":"packaging workflow detected","details":["Info: Project packages its releases by way of GitHub Actions.: .github/workflows/build.yml:150"],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#packaging"}},{"name":"Vulnerabilities","score":8,"reason":"2 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GO-2025-3754 / GHSA-2x5j-vhc8-9cwm","Warn: Project is vulnerable to: GO-2025-3533 / GHSA-wq9g-9vfc-cfq9"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":9,"reason":"SAST tool detected but not run on all commits","details":["Info: SAST configuration detected: CodeQL","Warn: 22 commits out of 26 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#sast"}},{"name":"Signed-Releases","score":8,"reason":"5 out of the last 5 releases have a total of 5 signed artifacts.","details":["Info: signed release artifact: go-hass-agent-13.3.2-1-aarch64.pkg.tar.zst.sig: https://github.com/joshuar/go-hass-agent/releases/tag/v13.3.2","Info: signed release artifact: go-hass-agent-13.3.1-1-aarch64.pkg.tar.zst.sig: https://github.com/joshuar/go-hass-agent/releases/tag/v13.3.1","Info: signed release artifact: go-hass-agent-13.3.0-1-aarch64.pkg.tar.zst.sig: https://github.com/joshuar/go-hass-agent/releases/tag/v13.3.0","Info: signed release artifact: go-hass-agent-13.2.8-1-aarch64.pkg.tar.zst.sig: https://github.com/joshuar/go-hass-agent/releases/tag/v13.2.8","Info: signed release artifact: go-hass-agent-13.2.7-1-aarch64.pkg.tar.zst.sig: https://github.com/joshuar/go-hass-agent/releases/tag/v13.2.7","Warn: release artifact v13.3.2 does not have provenance: https://api.github.com/repos/joshuar/go-hass-agent/releases/238730651","Warn: release artifact v13.3.1 does not have provenance: https://api.github.com/repos/joshuar/go-hass-agent/releases/235413881","Warn: release artifact v13.3.0 does not have provenance: https://api.github.com/repos/joshuar/go-hass-agent/releases/233730625","Warn: release artifact v13.2.8 does not have provenance: https://api.github.com/repos/joshuar/go-hass-agent/releases/230152480","Warn: release artifact v13.2.7 does not have provenance: https://api.github.com/repos/joshuar/go-hass-agent/releases/220820229"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#branch-protection"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#fuzzing"}},{"name":"Contributors","score":0,"reason":"project has 0 contributing companies or organizations -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project has a set of contributors from multiple organizations (e.g., companies).","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#contributors"}},{"name":"CI-Tests","score":8,"reason":"11 out of 13 merged PRs checked by a CI test -- score normalized to 8","details":null,"documentation":{"short":"Determines if the project runs tests before pull requests are merged.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#ci-tests"}}]},"last_synced_at":"2025-08-16T03:47:18.419Z","repository_id":152786439,"created_at":"2025-08-16T03:47:18.419Z","updated_at":"2025-08-16T03:47:18.419Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","fyneapp","go","golang-app","hass","home-assistant","home-automation","linux-app","monitoring-tool","mqtt","scripting"],"created_at":"2024-09-25T07:33:42.446Z","updated_at":"2026-04-01T20:34:14.680Z","avatar_url":"https://github.com/joshuar.png","language":"Go","funding_links":["https://ko-fi.com/astralcars"],"categories":["Go"],"sub_categories":[],"readme":"\u003c!--\n Copyright 2025 Joshua Rich \u003cjoshua.rich@gmail.com\u003e.\n SPDX-License-Identifier: MIT\n--\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n  \u003cimg src=\"web/content/go-hass-agent.png\" alt=\"logo\" width=\"200\" height=\"auto\" /\u003e\n  \u003ch1\u003eGo Hass Agent\u003c/h1\u003e\n\n  \u003cp\u003e\n    A \u003ca href=\"https://www.home-assistant.io/\"\u003eHome Assistant\u003c/a\u003e, \u003ca href=\"https://developers.home-assistant.io/docs/api/native-app-integration\"\u003enative app\n    integration\u003c/a\u003e for desktop/laptop devices.\n  \u003c/p\u003e\n\n\u003c!-- Badges --\u003e\n\u003cp\u003e\n  \u003ca href=\"https://github.com/joshuar/go-hass-agent/graphs/contributors\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/contributors/joshuar/go-hass-agent\" alt=\"contributors\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/joshuar/go-hass-agent/commits/main/\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/last-commit/joshuar/go-hass-agent\" alt=\"last update\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/joshuar/go-hass-agent/network/members\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/forks/joshuar/go-hass-agent\" alt=\"forks\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/joshuar/go-hass-agent/stargazers\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/joshuar/go-hass-agent\" alt=\"stars\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/joshuar/go-hass-agent/issues/\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/issues/joshuar/go-hass-agent\" alt=\"open issues\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/joshuar/go-hass-agent/blob/master/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/joshuar/go-hass-agent.svg\" alt=\"license\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch4\u003e\n    \u003ca href=\"https://github.com/joshuar/go-hass-agent\"\u003eDocumentation\u003c/a\u003e\n  \u003cspan\u003e · \u003c/span\u003e\n    \u003ca href=\"https://github.com/joshuar/go-hass-agent/issues/new?assignees=joshuar\u0026labels=\u0026template=bug_report.md\u0026title=%5BBUG%5D\"\u003eReport Bug\u003c/a\u003e\n  \u003cspan\u003e · \u003c/span\u003e\n    \u003ca href=\"https://github.com/joshuar/go-hass-agent/issues/new?assignees=joshuar\u0026labels=\u0026template=feature_request.md\u0026title=\"\u003eRequest Feature\u003c/a\u003e\n  \u003c/h4\u003e\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n## 📔 Table of Contents\n\n- [📔 Table of Contents](#-table-of-contents)\n- [🌟 About the Project](#-about-the-project)\n- [🎯 Features](#-features)\n- [🤔 Use-cases](#-use-cases)\n- [📈🕹️📢 List of Sensors/Controls/Events (by Operating System)](#️-list-of-sensorscontrolsevents-by-operating-system)\n  - [🐧 Linux](#-linux)\n    - [📈 Sensors](#-sensors)\n      - [Active App and Total Running Apps](#active-app-and-total-running-apps)\n      - [Desktop Settings](#desktop-settings)\n      - [Global MPRIS State](#global-mpris-state)\n      - [Webcam and Microphone In Use](#webcam-and-microphone-in-use)\n      - [Battery Details](#battery-details)\n      - [Memory Stats](#memory-stats)\n      - [Disk Usage and Activity Monitoring](#disk-usage-and-activity-monitoring)\n      - [Disk SMART Monitoring](#disk-smart-monitoring)\n      - [Network Connection and Activity Monitoring](#network-connection-and-activity-monitoring)\n      - [CPU Stats](#cpu-stats)\n      - [Power State Monitoring](#power-state-monitoring)\n      - [Screen Lock](#screen-lock)\n      - [User Monitoring](#user-monitoring)\n      - [System Information](#system-information)\n      - [Hardware Monitoring](#hardware-monitoring)\n      - [Location](#location)\n    - [🕹️ Controls](#️-controls)\n      - [Volume Control](#volume-control)\n      - [Webcam Control](#webcam-control)\n      - [Power Control](#power-control)\n      - [D-Bus Integration](#d-bus-integration)\n    - [📢 Events](#-events)\n      - [User Sessions](#user-sessions)\n      - [Out Of Memory (OOM) Events](#out-of-memory-oom-events)\n  - [All Operating Systems](#all-operating-systems)\n- [🧰 Getting Started](#-getting-started)\n  - [🤝 Compatibility](#-compatibility)\n  - [🔽 Installation](#-installation)\n    - [📦 Packages](#-packages)\n    - [🚢 Container](#-container)\n    - [🗒️ Versioning](#️-versioning)\n- [👐🏻 Usage](#-usage)\n  - [🚩 First-run](#-first-run)\n  - [🔄 Subsequent runs and running automatically](#-subsequent-runs-and-running-automatically)\n    - [On a desktop using autostart functionality](#on-a-desktop-using-autostart-functionality)\n    - [On a server using systemd](#on-a-server-using-systemd)\n  - [🐳 Running in a container](#-running-in-a-container)\n  - [🔧 Alternative System Mount Points](#-alternative-system-mount-points)\n  - [🔧 Web server configuration Options](#-web-server-configuration-options)\n  - [🤖 Home Assistant Integration](#-home-assistant-integration)\n  - [🗒️ Preferences](#️-preferences)\n  - [🐚 Script Sensors](#-script-sensors)\n    - [Requirements](#requirements)\n    - [Supported Scripting Languages](#supported-scripting-languages)\n    - [Output Format](#output-format)\n      - [Examples](#examples)\n        - [JSON](#json)\n        - [YAML](#yaml)\n        - [TOML](#toml)\n    - [Schedule](#schedule)\n      - [Cron Expressions](#cron-expressions)\n      - [Pre-defined Intervals](#pre-defined-intervals)\n      - [Arbitrary Intervals](#arbitrary-intervals)\n    - [Security Implications](#security-implications)\n  - [💬 MQTT Sensors and Controls](#-mqtt-sensors-and-controls)\n    - [Configuration](#configuration)\n    - [Custom D-Bus Controls](#custom-d-bus-controls)\n    - [Other Custom Commands](#other-custom-commands)\n    - [Security Implications](#security-implications-1)\n- [⚙️ Building/Compiling Manually](#️-buildingcompiling-manually)\n  - [Build Requirements](#build-requirements)\n  - [Compiling](#compiling)\n  - [Cross Compilation](#cross-compilation)\n  - [Packages](#packages)\n  - [Container Images](#container-images)\n- [👋 Contributing](#-contributing)\n  - [💾 Committing Code](#-committing-code)\n  - [📜 Code of Conduct](#-code-of-conduct)\n- [🧭 Roadmap](#-roadmap)\n- [❔ FAQ](#-faq)\n  - [_Can I change the units of the sensor?_](#can-i-change-the-units-of-the-sensor)\n  - [_Can I disable some sensors?_](#can-i-disable-some-sensors)\n  - [_What is the resource (CPU, memory) usage of the agent?_](#what-is-the-resource-cpu-memory-usage-of-the-agent)\n  - [_I've updated the agent and now I've got a bunch of duplicate/removed/disabled sensors?_](#ive-updated-the-agent-and-now-ive-got-a-bunch-of-duplicateremoveddisabled-sensors)\n  - [_Can I reset the agent (start from new)?_](#can-i-reset-the-agent-start-from-new)\n  - [_Can (or does) the agent run as root or with privileges?_](#can-or-does-the-agent-run-as-root-or-with-privileges)\n  - [_Can the agent run in an MQTT-only mode?_](#can-the-agent-run-in-an-mqtt-only-mode)\n  - [_(Linux) Why do the disk rate sensors report a non-zero value while the IO operations in progress sensor is zero?_](#linux-why-do-the-disk-rate-sensors-report-a-non-zero-value-while-the-io-operations-in-progress-sensor-is-zero)\n  - [_(Linux) What does the value of the Firmware Security sensor mean?_](#linux-what-does-the-value-of-the-firmware-security-sensor-mean)\n  - [_(Linux) Some of the hardware sensors are reporting incorrect values?_](#linux-some-of-the-hardware-sensors-are-reporting-incorrect-values)\n- [🤝 Acknowledgements](#-acknowledgements)\n- [🧑‍⚖️ License](#️-license)\n\n## 🌟 About the Project\n\nGo Hass Agent is an application to expose sensors, controls, and events from a\ndevice to Home Assistant. You can think of it as something similar to the\n[Home Assistant companion app](https://companion.home-assistant.io/) for mobile\ndevices, but for your desktop, server, Raspberry Pi, Arduino, toaster, whatever.\nIf it can run Go and Linux, it can run Go Hass Agent!\n\nOut of the box, Go Hass Agent will report lots of details about the system it is\nrunning on. You can extend it with additional sensors and controls by hooking it\nup to MQTT. You can extend it **even further** with your own custom sensors and\ncontrols with scripts/programs.\n\nYou can then use these sensors, controls, or events in any automations and\ndashboards, just like the companion app or any other “thing” you've added into\nHome Assistant.\n\n## 🎯 Features\n\n- **Sensors:** Expose a number of sensor entities to Home Assistant, for\n  displaying in dashboards, using in automations or any other aspects your Home\n  Assistant platform.\n- **Custom Sensors via Scripts:** All platforms can also utilize\n  scripts/executables to create custom sensors. See\n  [Script Sensors](#-script-sensors).\n- **Controls and additional sensors via MQTT:** Where Home Assistant is\n  connected to MQTT, Go Hass Agent can add some additional sensors/controls for\n  various system features. A selection of device controls are provided by\n  default, and you can configure additional controls to execute D-Bus commands\n  or scripts/executables. See [Control via MQTT](#-mqtt-sensors-and-controls).\n- **Events:** Go Hass Agent will send a few events when certain things happen on\n  the device running the agent (for example, user logins/logouts). You can\n  listen for these events and react on them in Home Assistant automations.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n## 🤔 Use-cases\n\nAs examples of some of the things that can be done with the data published by\nthis app:\n\n- Change your lighting depending on:\n  - What active/running apps are on your laptop/desktop. For example, you could\n    set your lights dim or activate a scene when you are gaming.\n  - Whether your screen is locked or the device is shutdown/suspended.\n- Set up automations to run when you log in or out of your machine.\n- With your laptop plugged into a smart plug that is also controlled by Home\n  Assistant, turn the smart plug on/off based on the battery charge. This can\n  force a full charge/discharge cycle of the battery, extending its life over\n  leaving it constantly charged.\n- Like on mobile devices, create automations based on the location of your\n  laptop running this app.\n- Monitor network the data transfer amount from the device, useful where network\n  data might be capped.\n- Monitor CPU load, disk usage and any temperature sensors emitted from the\n  device.\n- Receive notifications from Home Assistant on your desktop/laptop. Potentially\n  based on or utilizing any of the data above.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n## 📈🕹️📢 List of Sensors/Controls/Events (by Operating System)\n\n\u003e [!NOTE]\n\u003e\n\u003e The following list shows all **potential** sensors the agent can report. In\n\u003e some cases, the **actual** sensors reported may be less due to lack of support\n\u003e in the system configuration or missing hardware.\n\n### 🐧 Linux\n\n#### 📈 Sensors\n\n##### Active App and Total Running Apps\n\n- Currently active (focused) application and **Running Apps** (count of all running applications). Updated when active\napp or number of apps changes.\n- Via D-Bus (requires [XDG Desktop Portal Support](https://flatpak.github.io/xdg-desktop-portal/docs/) support).\n- [_Preferences_](#️-preferences): `[sensors.desktop.app]`.\n\n##### Desktop Settings\n\n- **Accent Color** (the hex code representing the accent color of the desktop environment in use).\n- **Theme Type** (whether a dark or light desktop theme is detected).\n- Updated when (theme or color) changes.\n- Via D-Bus (requires [XDG Desktop Portal Support](https://flatpak.github.io/xdg-desktop-portal/docs/) support).\n- [_Preferences_](#️-preferences): `[sensors.desktop.preferences]`.\n\n##### Global MPRIS State\n\n- **MPRIS Player State** Show the current state of any MPRIS compatible player.\n- Requires a player with MPRIS support.\n\n##### Webcam and Microphone In Use\n\n- Show when either a webcam or microphone is one and recording/streaming video/audio.\n- Requires Pipewire.\n- [_Preferences_](#️-preferences): All under `[sensors.media]`.\n\n##### Battery Details\n\n- Connected Battery Details:\n  - **Battery Type** (the type of battery, e.g., UPS, line power). Updated on\n    battery add/remove.\n  - **Battery Temp** (battery temperature). Updated when the temperature\n    changes.\n  - **Battery Power** (the battery current power draw, in W). Attributes:\n    Voltage (V), Energy consumption (kWh). Updated when power draw changes.\n  - **Battery Level/Percentage** (either a textual representation of the level\n    or a percentage, depending on battery support). Updated when level changes.\n  - **Battery State** (the current battery state, e.g., charging/discharging).\n    Updated When state changes.\n- All battery sensors require D-Bus and [UPower](https://upower.freedesktop.org/) support.\n- [_Preferences_](#️-preferences): `[sensors.batteries]`.\n\n##### Memory Stats\n\n- **Memory Total** (total memory on the system, in B).\n- **Memory Available** (current memory available/free, in B).\n- **Memory Used** (current memory usage, both in B and %).\n- If swap is enabled, there will be similar sensors for swap.\n- Sourced via ProcFS. Updated ~every minute.\n- [_Preferences_](#️-preferences): `[sensors.memory.usage]`.\n\n##### Disk Usage and Activity Monitoring\n\n- **Disk Usage** (in %) per disk/mount.\n  - Attributes: File system type, bytes/inode total/free/used.\n  - Can be filtered, see `ignored_mounts` in preferences (string prefix match).\n  - Sourced via ProcFS. Updated ~every minute.\n- **Total Read/Writes** (count) per disk.\n  - Attributes include total milliseconds/sectors spent.\n- **Read/Write Rate** (in KB/s) per disk.\n  - Both sourced via SysFS. Updated ~every 5 seconds.\n- **IO Operations in Progress** per disk.\n  - Sourced via SysFS. Updated ~every 5 seconds.\n\n##### Disk SMART Monitoring\n- **S.M.A.R.T status and attributes** per disk.\n  - Requires the following capabilities on the Go Hass Agent binary (already applied for containers and rpm/deb/arch\n    packages): `cap_sys_rawio,cap_sys_admin,cap_mknod,cap_dac_override=+ep`.\n- [_Preferences_](#️-preferences): `[sensors.disk.*rates*]` (`usage` for usage or `rates` for all others).\n\n##### Network Connection and Activity Monitoring\n\n- **Connection State** (connected/disconnected/activating/deactivating) per connection. Updated when state changes.\n    Requires D-Bus and NetworkManager.\n  - Attributes: IP addresses and networks.\n  - [_Preferences_](#️-preferences): `[sensors.network.connections]`.\n\n- Connected Wi-Fi Network Details (requires D-Bus and NetworkManager.):\n  - **SSID** (the SSID of the Wi-Fi network). Updated when SSID changes.\n  - **Frequency** (the frequency band of the Wi-Fi network, in Hz). Updated when frequency changes.\n  - **Speed** (the network speed of the Wi-Fi network, in Mbps). Updated when speed changes.\n  - **Strength** (the strength of the signal of the Wi-Fi network, in dB). Updated when strength changes.\n  - **BSSID** (the BSSID of the Wi-Fi network). Updated when BSSID changes.\n  - [_Preferences_](#️-preferences): `[sensors.network.connections]`.\n- **Device/Link State**\n  - Via Netlink.\n  - [_Preferences_](#️-preferences): `[sensors.network.links]`.\n- **Bytes Received/Sent** (in B). Updated ~every 5s.\n  - Per network device/link and total.\n  - Via Netlink.\n  - [_Preferences_](#️-preferences): `[sensors.network.rates]`.\n- **Bytes Received/Sent Rate** (transfer rate, in B/s). Updated ~every 5 seconds. Via ProcFS.\n  - Per network device/link and total.\n  - Via Netlink.\n  - [_Preferences_](#️-preferences): `[sensors.network.rates]`.\n  - You can ignore some devices from generating sensors, see the individual preferences sections above.\n\n##### CPU Stats\n\n- **Load Average (1/5/15 min)**. Updated ~every 1 minute. Via ProcFS.\n  - [_Preferences_](#️-preferences): `[sensors.cpu.load_averages]`.\n- **CPU Usage** (in %). Both total (all-cores) and per-core. Updated ~every 10 seconds. Via ProcFS.\n  - Attributes include breakdown of CPU time per state (i.e., user, idle, servicing interrupts, etc.).\n  - [_Preferences_](#️-preferences): `[sensors.cpu.usage]`.\n- **CPU Core Frequency** (in Hz). Per-core. Updated ~every 10 seconds. Via ProcFS.\n  - Attributes include current driver and governor in use.\n  - [_Preferences_](#️-preferences): `[sensors.cpu.frequencies]`.\n\n##### Power State Monitoring\n\n- **Power Profile** (the current power profile as set by the power-profiles-daemon). Updated when profile changes.\n  - Via D-Bus (requires\n      [power-profiles-daemon](https://hadess.fedorapeople.org/power-profiles-daemon-docs/gdbus-net.hadess.PowerProfiles.html)).\n  - [_Preferences_](#️-preferences): `[sensors.power.profile]`.\n- **Power State** (power state of device, e.g., suspended, powered on/off). Updated when power state changes.\n  - Via D-Bus. Requires `systemd-logind`.\n  - [_Preferences_](#️-preferences): `[sensors.power.state]`.\n\n##### Screen Lock\n\n- **Screen Lock State** (current state of screen lock). Updated when screen lock changes.\n  - Via D-Bus. Requires `xscreensaver` or `systemd-logind` support.\n  - [_Preferences_](#️-preferences): `[sensors.power.screen_lock]`.\n\n##### User Monitoring\n\n- **Current Users** (count of users with active sessions on the system). Updated when any session changes.\n  - Attributes: List of usernames | When user count changes.\n  - Via D-Bus. Requires `systemd-logind`.\n  - [_Preferences_](#️-preferences): `[sensors.system.users]`.\n- **User Activity** (whether a user is currently using the device).\n  - Relies on evdev to detect input events (keyboard, mouse).\n  - Requires the following capabilities on the Go Hass Agent binary (already applied for containers and rpm/deb/arch\n    packages): `cap_setgid,cap_setuid=+ep`.\n  - Requires user running Go Hass Agent is in the `input` group.\n\n##### System Information\n\n- **Boot Time** (date/Time of last system boot). Via ProcFS.\n- \\*_Uptime_. Updated ~every 15 minutes. Via ProcFS.\n- **Kernel Version** (version of the currently running kernel). Updated on agent start. Via ProcFS.\n- Vulnerabilities:\n  - **Firmware Security** the [Host Security ID](https://fwupd.github.io/libfwupdplugin/hsi.html) of the device running\n    Go Hass Agent.\n    - Attributes show details for each HSI attribute.\n    - Via D-Bus. Requires `fwupd` running on the system.\n  - **CPU Vulnerabilities** whether any CPU vulnerabilities have been detected by the kernel and\n    exploitable/unmitigated.\n    - Attributes show the status of each vulnerability detected.\n    - Via ProcFS.\n- Distribution Details:\n  - **Distribution Name** (name of the running distribution, e.g., Fedora, Ubuntu).\n  - **Distribution Version** (version of the running distribution).\n  - Both updated on agent start. Via ProcFS.\n- [_Preferences_](#️-preferences) (for all the above system details sensors): `[sensors.system.info]`.\n- **ABRT Problems** (count of any problems logged to the ABRT daemon). Updated ~every 15 minutes.\n  - Attributes: extracted problem details.\n  - Requires ABRT.\n  - [_Preferences_](#️-preferences): `[sensors.system.abrt_problems]`.\n\n##### Hardware Monitoring\n- Any **temp**, **fan**, **power** and other hardware sensors, including associated **alarms**. Updated ~every 1 minute.\n- Extracted from the `/sys/class/hwmon` file system.\n- [_Preferences_](#️-preferences): `[sensors.system.hardware_sensors]`.\n\n##### Location\n\n- On some devices such as laptops, exposes a\n  [device_tracker](https://www.home-assistant.io/integrations/device_tracker/) entity with the device's location.\n- Requires working [geoclue service](https://github.com/erfanoabdi/geoclue) (most popular distributions will have this\n  by default).\n\n#### 🕹️ Controls\n\n\u003e [!NOTE]\n\u003e\n\u003e Only available when [configured with MQTT](#-mqtt-sensors-and-controls)\n\n##### Volume Control\n\n- **Volume Control/Mute**: Adjust the volume on the default audio output device.\n  - Requires Pipwire and Wireplumber both configured and command-line utilities installed and available (most\n    distributions will use Pipewire, command-line utilities might need to be installed manually).\n\n##### Webcam Control\n\n- **Webcam Control**: Start/stop a webcam and view the video in Home Assistant.\n  - Requires a webcam that is exposed via V4L2 (VideoForLinux2).\n- [_Preferences_](#️-preferences) : `[controls.media.*]` (`audio` or `video`).\n\n##### Power Control\n\n- **Lock/Unlock Screen/Screensaver**: Locks/unlocks the session for the user running Go Hass Agent.\n  - [_Preferences_](#️-preferences) : `[controls.power.screen_lock_controls]`.\n- **Suspend**: (instantly) suspend (the system state saved to RAM and the CPU turned off) the device running Go Hass\n  Agent.\n- **Hibernate**: (instantly) hibernate (the system state saved to disk and the machine powered down) the device running\n  Go Hass Agent.\n- **Power Off**: (instantly) power off the device running Go Hass Agent.\n- **Reboot**: (instantly) reboot the device running Go Hass Agent.\n- Power controls require a system configured with `systemd-logind` (and D-Bus) support.\n- [_Preferences_](#️-preferences) (for suspend/hibernate/power off/reboot\n  controls): `[controls.power.power_controls]`.\n- **Inhibit Lock**: stop the system from being able to shutdown or suspend.\n  - [_Preferences_](#️-preferences): `[controls.power.inhibit_controls]`.\n\n##### D-Bus Integration\n\n- Run arbitrary D-Bus commands: see [Custom D-Bus Controls](#custom-d-bus-controls).\n  - [_Preferences_](#️-preferences): `[controls.system.dbus_commands]`.\n\n#### 📢 Events\n\n##### User Sessions\n\n- **User sessions (login/logout) events**.\n  - Requires a system configured with `systemd-logind`.\n  - Event structures:\n\n    ```yaml\n    event_type: session_started # or session_stopped\n    data:\n      desktop: \"\" # blank or a desktop name, like KDE.\n      remote: true # true if remote (i.e., ssh) login.\n      remote_host: \"::1\" # remote host or blank.\n      remote_user: \"\" # remote user or blank.\n      service: \"\" # blank or the service that handled the action (e.g., ssh).\n      type: \"tty\" # blank or type of session.\n      user: myuser # username.\n    ```\n\n  - [_Preferences_](#️-preferences): `[sensors.system.users]`.\n\n##### Out Of Memory (OOM) Events\n\n- **Out Of Memory (OOM) events**.\n  - Requires a system configured with `systemd-oomd` enabled.\n  - Event structure:\n\n    ```yaml\n    event_type: oom_event\n    data:\n      process: systoomd_swap_test # process that was killed by systemd-oomd.\n      pid: 909764 # pid of process.\n    ```\n\n  - [_Preferences_](#️-preferences): `[sensors.memory.oom]`.\n\n### All Operating Systems\n\n**Sensors:**\n\n- **Go Hass Agent Version**: Updated on agent start.\n  - [_Preferences_](#️-preferences): `[sensors.agent.version]`.\n- **External IP Addresses**: All external IP addresses (IPv4/6) of the device\n  running the agent.\n  - [_Preferences_](#️-preferences): `[sensors.agent.external_ip]`.\n- **Connection Latency**: Total connection time (in milliseconds) to connect to\n  Home Assistant from the device running Go Hass Agent. Additional times shown\n  as attributes.\n  - [_Preferences_](#️-preferences): `[sensors.agent.connection_latency]`.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n## 🧰 Getting Started\n\n### 🤝 Compatibility\n\n**Currently, only Linux is supported**. Though the code is designed to be\nextensible to other operating systems. See development information in the\n[docs](docs/README.md) for details on how to extend for other operating systems.\n\n### 🔽 Installation\n\n#### 📦 Packages\n\nHead over to the [releases](https://github.com/joshuar/go-hass-agent/releases)\npage and download the appropriate package for your operating system and/or\ndistribution:\n\n- **Fedora**: use the `.rpm`.\n- **Ubuntu/Debian**: use the `.deb`.\n- **Arch**: use the `.tar.zst`.\n\nPackages (and binaries) are available for **amd64**, **arm (v6 and v7)** and\n**arm64** architectures.\n\nFor distributions not listed above, you can try the binary, or build it yourself\nfrom source (see development [docs](#%EF%B8%8F-buildingcompiling-manually)).\n\nPackage signatures can be verified with\n[cosign](https://github.com/sigstore/cosign). To verify a package, you'll need\nto download [cosign.pub](cosign.pub) public key and the `.sig` file (downloaded\nfrom [releases](https://github.com/joshuar/go-hass-agent/releases)) that matches\nthe package you want to verify. To verify a package, a command similar to the\nfollowing for the `rpm` package can be used:\n\n```shell\ncosign verify-blob --key cosign.pub --bundle go-hass-agent-*.rpm.sig go-hass-agent-*.rpm\n```\n\n[⬆️ Back to Top](#-table-of-contents)\n\n#### 🚢 Container\n\nContainer images are available on\n[ghcr.io](https://github.com/joshuar/go-hass-agent/pkgs/container/go-hass-agent).\nThe container image is multi-platform and supports **amd64**, **arm (v6 and\nv7)** and **arm64** architectures. Note that it is recommended to use an image\ntagged with the latest release version over the latest container image, which\nmight be unstable.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n#### 🗒️ Versioning\n\nThis project follows [semantic versioning](https://semver.org/). Given a version\nnumber `MAJOR.MINOR.PATCH`, the gist of it is:\n\n- A `MAJOR` number change means there\n  [breaking changes](docs/BREAKING_CHANGES.md) from the previous release that\n  may require manual intervention before/after upgrading.\n- A `MINOR` number change means significant changes and new features have been\n  added, but not breaking changes.\n- A `PATCH` number change indicate minor changes and bug fixes.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n## 👐🏻 Usage\n\nGo Hass Agent is distribution, and desktop-environment agnostic. It runs in the\nbackground gathering and submitting sensor/event/command data to Home Assistant.\nIt exposes a limited web UI (accessible via\n[http://localhost:8223](http://localhost:8223)) used for some initial setup and\noptional configuration options.\n\n### 🚩 First-run\n\nOn first-run, Go Hass Agent attempts to open a browser tab to a page for registering the agent with Home Assistant. If\nthis does not happen (or you are running the agent remotely on a server), open a browser tab and navigate to\n[http://localhost:8223](http://localhost:8223) (or the address of the device running the agent). You should be\nredirected to the registration form where you will need to enter details to allow Go Hass Agent to register with Home\nAssistant:\n\n![Registration Window](assets/screenshots/registration-form.png)\n\n**You will need:**\n\n- A long-lived access token. You can generate one on your\n  [account profile page](https://www.home-assistant.io/docs/authentication/#your-account-profile).\n- The web address (URL) on which a Home Assistant instance can be found.\n  - Go Hass Agent will try to auto-detect this for you, and you can select it in\n    the _Detected servers_ list. Otherwise, you will need to select _Use Custom\n    Server_, and enter the details manually in _Custom Server_.\n\nWhen you have entered all the details, click **Register** and the agent should\nstart running and reporting sensors to the Home Assistant instance.\n\nAlternatively, you can register Go Hass Agent on the command-line by running:\n\n```shell\ngo-hass-agent register --token _TOKEN_ --server _URL_\n```\n\nOnce registered, Go Hass Agent should start sending sensor/event data to Home\nAssistant.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### 🔄 Subsequent runs and running automatically\n\n#### On a desktop using autostart functionality\n\nGo Hass Agent packages install a `.desktop` file exposes Go Hass Agent in your\ndesktop's application menu that can be used to start the agent. Use your\ndesktop's autostart functionality to set this desktop entry to autostart\n(consult your desktop documentation for details, or consult the links\n[here](https://wiki.archlinux.org/title/Autostarting#On_desktop_environment_startup)\nor\n[here](https://wiki.archlinux.org/title/Autostarting#On_window_manager_startup)).\n\n#### On a server using systemd\n\nGo Hass Agent packages install a systemd service file that can be enabled and\nused to run the agent as a service. You will still need to register the agent\nmanually before starting as a service (see above, in particular registering on\nthe command-line).\n\nYou will also need to ensure your user has “lingering” enabled. Run\n`loginctl list-users` and check that your user has `LINGER` set to “yes”. If\nnot, run `loginctl enable-linger`.\n\nOnce you have registered the agent and enabled lingering for your user. Enable\nthe service and start it with the command:\n`systemctl --user enable go-hass-agent \u0026\u0026 systemctl --user start go-hass-agent`.\n\nYou can check the status with `systemctl --user status go-hass-agent`. The agent\nshould start with every boot.\n\nFor other init systems, consult their documentation on how to enable and run\nuser services.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### 🐳 Running in a container\n\nThere is rough support for running Go Hass Agent within a container. Pre-built\nimages\n[are available](https://github.com/joshuar/go-hass-agent/pkgs/container/go-hass-agent)\nfor _armv6/v7_, _arm64_ and _amd64_ architectures. The image is based on the\nlatest stable Alpine Linux release.\n\nTo register the agent running in a container, run the following:\n\n```shell\n    podman run --rm --network host \\\n      --volume go-hass-agent:/home/go-hass-agent:U \\\n      ghcr.io/joshuar/go-hass-agent:_VERSION_ register \\\n      --server https://some.server:port \\\n      --token 'longlivedtoken'\n```\n\n- Change `_VERSION_` to a release version. **Do not use latest, which is\n  unstable and likely to break.**\n- Change the value of `--server` to your Home Assistant server.\n- Change the value of `--token` to a long-lived token retrieved from Home\n  Assistant.\n  - **_Be sure to quote the token to avoid shell escape errors._**\n- We are running the container in a “one-shot” mode (specifying `--rm`) as we\n  just want to register and generate the configuration file. We will use a\n  different command below to actually run Go Hass Agent.\n\nOnce registered, run the agent with:\n\n```shell\npodman run --hostname _HOSTNAME_ --name go-hass-agent \\\n  --network host \\\n  --volume go-hass-agent:/home/go-hass-agent:U \\\n  --volume /proc:/host/proc:ro --volume /sys:/host/sys:ro \\\n  --env PROCFS_ROOT=/host/proc --env SYSFS_ROOT=/host/sys \\\n  --volume /run/dbus:/run/dbus:ro \\\n  --volume /run/user/1000/bus:/run/user/1000/bus:ro \\\n  --device /dev/video0:/dev/video0 \\\n  --cap-add SYS_ADMIN --cap-add SYS_RAWIO --cap-add MKNOD \\\n  ghcr.io/joshuar/go-hass-agent:VERSION # add any Go Hass Agent options here.\n```\n\nChange the value passed to `--name` to a unique name for your running container\nand `--hostname` for the hostname that will be presented to Home Assistant\nduring registration.\n\nAll the other volume mounts are optional, but functionality and the sensors\nreported will be severely limited without them:\n\n- `--volume /proc:/host/proc:ro --volume /sys:/host/sys:ro`\n- `--env PROCFS_ROOT=/host/proc --env SYSFS_ROOT=/host/sys`\n  - Enables various hardware and system monitoring sensors.\n- `--volume /run/dbus:/run/dbus:ro`\n- `--volume /run/user/1000/bus:/run/user/1000/bus:ro`\n  - Enables sensors that are gathered via D-Bus. Adjust `1000` to the uid of\n    your user.\n- `--cap-add SYS_ADMIN --cap-add SYS_RAWIO --cap-add MKNOD`\n  - Assigns capabilities to allow fetching some sensor data (see\n    [sensor list](#-sensors) for which sensors require what capabilities).\n- `--device /dev/video0:/dev/video0`\n  - Allows webcam control (when configured with MQTT).\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### 🔧 Alternative System Mount Points\n\nGo Hass Agent supports alternative system mount points, which can be especially\nuseful when [running in a container](#-running-in-a-container). You can set the\nfollowing environment variables to specify the location Go Hass Agent will use\nfor various mounts:\n\n- `PROCFS_ROOT`: alternative mount point for `/proc`.\n- `DEVFS_ROOT`: alternative mount point for `/dev`.\n- `SYSFS_ROOT`: alternative mount point for `/sys`.\n\nWhen these are set, any sensors that would normally source their data from a\nfile in one of the canonical system mount points, will use the alternative mount\npoint location specified.\n\nFor running in a container, example usage would be to add the following\ncommand-line arguments to the container run command:\n\n```shell\npodman run \\\n  ...other options... \\\n  --volume /proc:/host/proc:ro --volume /sys:/host/sys:ro --volume /dev:/host/dev:ro \\\n  --env PROCFS_ROOT=/host/proc --env SYSFS_ROOT=/host/sys --env DEVFS_ROOT=/host/dev \\\n  ...other options...\n```\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### 🔧 Web server configuration Options\n\nThe web server starts by default on `localhost:8223`, without TLS. You can configure a key/cert for TLS and change the hostname/port combination with the following options:\n\n- `--server-hostname=machine.lan`\n- `--server-port=1234`\n- `--server-https-cert=path/to/cert.file`\n- `--server-https-key=path/to/key.file`\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### 🤖 Home Assistant Integration\n\nWhen running, Go Hass Agent will appear as a device under the Mobile App\nintegration in your Home Assistant instance. It should also report a list of\nsensors/entities you can use in any automations, scripts, dashboards and other\nparts of Home Assistant.\n\n[![Open your Home Assistant instance to the mobile_app integration.](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration/?domain=mobile_app)\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### 🗒️ Preferences\n\nThe preference file (`preferences.toml`) is located in\n`CONFIG_HOME/go-hass-agent/` where `CONFIG_HOME` will OS-dependent:\n\n- Linux: `~/.config`.\n- OSX: `~/Library/Application Support`.\n- Windows: `LocalAppData`.\n\nPreferences under `[sensors]` or `[controls]` can be used to adjust various\naspects of those sensors/controls, or disable them entirely. See\n[sensors](README.md#-sensors) and [controls](README.md#️-controls) for mapping\nthe preferences to individual sensors/controls.\n\n\u003e [!WARNING]\n\u003e\n\u003e **Preferences in the other sections should not be edited manually**. Editing\n\u003e preferences outside the above two groups may cause Go Hass Agent to stop\n\u003e functioning or produce errors.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### 🐚 Script Sensors\n\nGo Hass Agent supports utilizing scripts to create sensors. In this way, you can\nextend the sensors presented to Home Assistant by the agent. Note that as the\nagent is a “mobile app” in Home Assistant, any script sensors will be associated\nwith the Go Hass Agent device in Home Assistant.\n\nEach script run by the agent can create one or more sensors and each script can\nrun on its own schedule, specified using a Cron syntax.\n\n#### Requirements\n\n- Scripts need to be put in a `scripts` folder under the configuration directory\n  (see [Preferences Location](#️-preferences) for the full path).\n- You can use symlinks, if supported by your Operating System.\n- Script files need to be executable by the user running Go Hass Agent.\n- Scripts need to run without any user interaction.\n- Scripts need to output either valid JSON, YAML or TOML. See\n  [Output Format](#output-format) for details.\n- Commands do not invoke the system shell and does not support expansion/glob\n  patterns or handle other expansions, pipelines, or redirections typically done\n  by shells.\n\n#### Supported Scripting Languages\n\nAny typical scripting language that can be invoked with a shebang can be used\nfor scripts. All scripts do not need to be written in the same language. So or\nthe typical shells can be used such as `bash`, `sh`, `zsh`, `fish`, etc.\nScripting languages such as Python, Perl, and Ruby can also be used.\n\n#### Output Format\n\nAll scripts should produce output that is either valid JSON, YAML or TOML.\nScripts do not need to use the same format; you can have one script that\nproduces JSON and another that produces TOML. All scripts will need to output\nthe following fields:\n\n- A `schedule` field containing a [cron-formatted schedule](#schedule).\n- A `sensors` field containing a list of sensors.\n\nSensors themselves need to be represented by the following fields:\n\n- `sensor_name`: the _friendly_ name of the sensor in Home Assistant (e.g., _My\n  Script Sensor_).\n- `sensor_icon`: a\n  [Material Design Icon](https://pictogrammers.github.io/@mdi/font/2.0.46/)\n  representing the current state. It can be changed dynamically based on the\n  current state or remain constant. Format is `mdi:icon_name`.\n- `sensor_state`: the current value of the sensor. For numerical states, without\n  the units. Otherwise, a _string_ or _boolean_ (for binary sensors).\n  - **Note:** for a binary sensor, do not enclose the `true`/`false` in quotes.\n\nThe following optional fields can also be specified, which help control the\ndisplay in Home Assistant.\n\n- `sensor_units`: the units for the state value.\n- `sensor_type`: the _type_ of sensor. If this is a binary sensor with a boolean\n  value, set this to _“binary”_. Else, do not set this field.\n- `sensor_device_class`: a Home Assistant\n  [Device Class](https://developers.home-assistant.io/docs/core/entity/sensor/#available-device-classes)\n  for the sensor, which will dictate how it will be displayed in Home Assistant.\n  There are many, pick an appropriate one (see\n  [`internal/hass/sensor/deviceClass.go`](../internal/hass/sensor/deviceClass.go)).\n  If setting `sensor_device_class`, it is likely required to set an appropriate\n  unit in `sensor_units` as well.\n- `sensor_state_class`: the Home Assistant\n  [State Class](https://developers.home-assistant.io/docs/core/entity/sensor/#available-state-classes).\n  Either _measurement_, _total_ or _total_increasing_.\n- `sensor_attributes`: any additional attributes to be displayed with the\n  sensor.\n\n##### Examples\n\nThe following examples show a script that produces two sensors, in different\noutput formats.\n\n###### JSON\n\nJSON output can be either compressed:\n\n```json\n{\n  \"schedule\": \"@every 5s\",\n  \"sensors\": [\n    {\n      \"sensor_name\": \"random 1\",\n      \"sensor_icon\": \"mdi:dice-1\",\n      \"sensor_state\": 1\n    },\n    {\n      \"sensor_name\": \"random 2\",\n      \"sensor_icon\": \"mdi:dice-2\",\n      \"sensor_state_class\": \"measurement\",\n      \"sensor_state\": 6,\n      \"sensor_attributes\": { \"foo\": \"bar\", \"baz\": 1 }\n    }\n  ]\n}\n```\n\nOr pretty-printed:\n\n```json\n{\n  \"schedule\": \"@every 5s\",\n  \"sensors\": [\n    {\n      \"sensor_name\": \"random 1\",\n      \"sensor_icon\": \"mdi:dice-1\",\n      \"sensor_state\": 2\n    },\n    {\n      \"sensor_name\": \"random 2\",\n      \"sensor_icon\": \"mdi:dice-2\",\n      \"sensor_state_class\": \"measurement\",\n      \"sensor_state\": 6,\n      \"sensor_attributes\": {\n        \"foo\": \"bar\",\n        \"baz\": 1\n      }\n    }\n  ]\n}\n```\n\n###### YAML\n\n```yaml\nschedule: \"@every 5s\"\nsensors:\n  - sensor_name: random 1\n    sensor_icon: mdi:dice-1\n    sensor_state: 8\n  - sensor_name: random 2\n    sensor_icon: mdi:dice-2\n    sensor_state_class: measurement\n    sensor_state: 9\n    sensor_attributes:\n      foo: \"bar\"\n      baz: 1\n```\n\n###### TOML\n\n```toml\nschedule = '@every 5s'\n\n[[sensors]]\nsensor_icon = 'mdi:dice-1'\nsensor_name = 'random 1'\nsensor_state = 3\n\n[[sensors]]\nsensor_icon = 'mdi:dice-2'\nsensor_name = 'random 2'\nsensor_state = 3\nsensor_state_class = 'measurement'\nsensor_attributes = { foo = \"bar\", baz = 1 }\n```\n\nFor a binary sensor, the output should have `sensor_type` set to “binary” and\nthe `sensor_state` as `true` or `false` (without quotes). As an example in\ncompressed JSON format:\n\n```json\n{\n  \"schedule\": \"@every 10s\",\n  \"sensors\": [\n    {\n      \"sensor_name\": \"random 4\",\n      \"sensor_type\": \"binary\",\n      \"sensor_icon\": \"mdi:dice-3\",\n      \"sensor_state\": false\n    }\n  ]\n}\n```\n\n#### Schedule\n\nThe `schedule` field is used to specify the schedule or interval on which the\nscript will be run by the agent. Each script is run on its own schedule. All\nsensors and their values should be returned each time the script is run. The\nfollowing formats are supported.\n\n##### Cron Expressions\n\nRegular Cron expressions as per the\n[Quartz format](https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/tutorial-lesson-06.html).\n\n##### Pre-defined Intervals\n\nYou may use one of several pre-defined schedules in place of a Cron expression.\n\n| Entry                      | Description                                | Equivalent To |\n| -------------------------- | ------------------------------------------ | ------------- |\n| `@yearly` (or `@annually`) | Run once a year, midnight, Jan. 1st        | `0 0 1 1 *`   |\n| `@monthly`                 | Run once a month, midnight, first of month | `0 0 1 * *`   |\n| `@weekly`                  | Run once a week, midnight between Sat/Sun  | `0 0 * * 0`   |\n| `@daily` (or `@midnight`)  | Run once a day, midnight                   | `0 0 * * *`   |\n| `@hourly`                  | Run once an hour, beginning of hour        | `0 * * * *`   |\n\n##### Arbitrary Intervals\n\nArbitrary intervals are supported with the format:\n\n`@every \u003cduration\u003e`\n\n`\u003cduration\u003e` must be a string accepted by\n[time.ParseDuration](http://golang.org/pkg/time/#ParseDuration).\n\n#### Security Implications\n\nRunning scripts can be dangerous, especially if the script does not have robust\nerror-handling or whose origin is untrusted or unknown. Go Hass Agent makes no\nattempt to do any analysis or sanitization of script output, other than ensuring\nthe output is a [supported format](#output-format). As such, ensure you trust\nand understand what the script does and all possible outputs that the script can\nproduce. Scripts are run by the agent and have the permissions of the user\nrunning the agent. Script output is sent to your Home Assistant instance.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### 💬 MQTT Sensors and Controls\n\n\u003e [!NOTE]\n\u003e\n\u003e - MQTT Sensors and Controls are not enabled by default.\n\u003e - Go Hass Agent requires MQTT v5 support on your MQTT broker.\n\nIf Home Assistant is connected to\n[MQTT](https://www.home-assistant.io/integrations/mqtt/), you can also configure\nGo Hass Agent to connect to MQTT, which will then expose some sensors and\ncontrols in Home Assistant to control the device running the agent.\nAdditionally, you can configure your own custom controls to run either\n[D-Bus commands](#custom-d-bus-controls) or\n[scripts and executables](#other-custom-commands).\n\n#### Configuration\n\nTo configure the agent to connect to MQTT:\n\n1. Open your browser and navigate to the Go Hass Agent preferences page:\n   [http://localhost:8223/preferences](http://localhost:8223/preferences):\n2. Toggle **_Use MQTT_** and then enter the details for your MQTT server (not\n   your Home Assistant server).\n\n   ![MQTT Preferences](assets/screenshots/preferences.png)\n\n3. Click **_Save_**.\n4. Restart Go Hass Agent.\n\nYou can also set MQTT preferences on the command-line:\n\n1. Stop Go Hass Agent if running.\n2. Use the `config` command option to specify your MQTT server parameters:\n\n   ```shell\n   go-hass-agent config --mqtt-server=tcp://localhost:1883 --mqtt-user=some-user --mqtt-password=superseret\n   ```\n\n   - Only `--mqtt-server` is required.\n\n3. Restart Go Hass Agent.\n\nAfter the above steps, Go Hass Agent will appear as a device under the MQTT\nintegration in your Home Assistant.\n\n[![Open your Home Assistant instance and show the MQTT\nintegration.](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration/?domain=mqtt)\n\n\u003e [!NOTE]\n\u003e\n\u003e Go Hass Agent will appear in two places in your Home Assistant. Firstly, under\n\u003e the Mobile App integration, which will show all the _sensors_ that Go Hass\n\u003e Agent is reporting. Secondly, under the MQTT integration, which will show the\n\u003e _controls and sensors_ exposed over MQTT for Go Hass Agent. Unfortunately, due\n\u003e to limitations with the Home Assistant architecture, these cannot be combined\n\u003e in a single place.\n\nTo disable MQTT features again, navigate back to the preferences URL above and\ntoggle **_Use MQTT_** off, or, run the command\n`go-hass-agent config --no-mqtt-enabled`.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n#### Custom D-Bus Controls\n\nWhen MQTT is configured, Go Hass Agent will also listen on MQTT and run\narbitrary D-Bus commands.\n\nThe agent will subscribe to the MQTT topic `gohassagent/HOSTNAME/dbuscommand`\n(where `HOSTNAME` is the short hostname of the device running Go Hass Agent). It\nlistens for messages with a JSON payload (shown below) that contains details of\nthe D-Bus method to call. When a message is received, the method will be\nexecuted. The easiest way to use this feature is with the `mqtt.publish` service\nin Home Assistant.\n\nAs an example, the following will create a notification on the device running Go\nHass Agent (YAML format used for readability):\n\n```yaml\nservice: mqtt.publish\ndata:\n  qos: 0\n  topic: gohassagent/HOSTNAME/dbuscommand\n  payload: |\n    {\n      \"bus\": \"session\",\n      \"path\": \"/org/freedesktop/Notifications\",\n      \"method\": \"org.freedesktop.Notifications.Notify\",\n      \"destination\": \"org.freedesktop.Notifications\",\n      \"args\": [\n          \"my-app-name\",\n          0,\n          \"my-icon\",\n          \"summary\",\n          \"body\",\n          [],\n          {},\n          5000\n      ],\n      \"use_session_path\": false\n    }\n```\n\n[⬆️ Back to Top](#-table-of-contents)\n\n#### Other Custom Commands\n\nYou can optionally create a `commands.toml` file under the configuration\ndirectory (see [preferences](#️-preferences) with custom commands to be exposed\nin Home Assistant.\n\nSupported control types and expected input/output:\n\n- [Button](https://www.home-assistant.io/integrations/button.mqtt/).\n  - Output is discarded. Return value is used to indicate success/failure.\n- [Switch](https://www.home-assistant.io/integrations/switch.mqtt/).\n  - Return value is used to indicate success/failure.\n  - When the switch is toggled in Home Assistant, Go Hass Agent will run the\n    configured command with an “ON” or “OFF” appended to the end of its\n    command-line.\n  - When the configured command is run, it should output the current state as\n    “ON” or “OFF”. Any additional output is ignored and any output that doesn't\n    match these strings will indicate an error to the agent.\n- [Number](https://www.home-assistant.io/integrations/number.mqtt/).\n  - `display` can be optionally set in the control configuration to specify how\n    the number control will be displayed in Home Assistant:\n    - Either `auto`, `box` or `slider`. The default if `display` is not set is\n      `auto`, where Home Assistant will decide how the control will be\n      displayed.\n  - `type` can be optionally set in the control configuration to specify whether\n    the number control has `int` or `float` values. The default will be `int` if\n    omitted.\n  - Return value is used to indicate success/failure.\n  - When the number is changed in Home Assistant, Go Hass Agent will run the\n    configured command passing the value appended to the end of its\n    command-line.\n  - When the configured command is run, it should output a number as the current\n    state. Any additional output is ignored.\n\n\u003e [!NOTE]\n\u003e\n\u003e Commands run as the user running the agent. Commands do not invoke the system\n\u003e shell and does not support expansion/glob patterns or handle other expansions,\n\u003e pipelines, or redirections typically done by shells.\n\u003e\n\u003e States are not kept in sync. This is most important for all controls besides\n\u003e buttons. For example, if you configure a switch, any changes to the state you\n\u003e make outside of Home Assistant will not be reflected in Home Assistant\n\u003e automatically.\n\nEach command needs the following definition in the file:\n\n```toml\n# \"control\" should be replaced with one of the control types above.\n[[control]]\n# name is required.\n# The pretty name of the command that will be the label in Home Assistant.\nname = \"my command name\"\n# exec is required.\n# The path to the command to execute.\n# Arguments can be given as required, and should be quoted if they contain spaces.\nexec = '/path/to/command arg1 \"arg with space\"'\n# icon is optional.\n# The material design icon to use to represent the control in Home Assistant.\n# See https://pictogrammers.com/library/mdi/ for icons you can use.\nicon = \"mdi:something\"\n# display is optional and only relevant for certain controls.\n# How the control will be shown in Home Assistant. Refer to the control type for valid values.\ndisplay = \"displayValue\"\n```\n\nFor number controls, additional configuration may be specified (default values\nshown):\n\n```toml\n# type is optional.\n# Whether this number control has int or float values. Default is \"int\".\ntype = \"int\"\n# min is optional.\n# The minimum value of the number. Default is 0.\nmin = 0\n# max is optional.\n# The maximum value of the number. Default is 100.\nmax = 100\n# step is optional.\n# The amount to change the value by (i.e., increment/decrement), if applicable. Default is 1.\nstep = 1\n```\n\nThe following shows an example that configures various controls in Home\nAssistant:\n\n```toml\n[[button]]\nname = \"My Command With an Icon\"\nexec = 'command arg1 arg2 \"arg3\"'\nicon = \"mdi:chat\"\n\n[[button]]\nname = \"My Command\"\nexec = \"command\"\n\n[[switch]]\nname = \"Toggle a Thing\"\nexec = \"command arg1 arg2\"\n\n[[number]]\nname = \"My number slider\"\nexec = \"command\"\ndisplay = \"slider\"\nmin = 1\nmax = 500\nstep = 5\n```\n\n#### Security Implications\n\nThere is a significant discrepancy in permissions between the device running Go\nHass Agent and Home Assistant.\n\nGo Hass Agent runs under a user account on a device. So the above controls will\nonly work where that user has permissions to run the underlying actions on that\ndevice. Home Assistant does not currently offer any fine-grained access control\nfor controls like the above. So any Home Assistant user will be able to run any\nof the controls. This means that a Home Assistant user not associated with the\ndevice user running the agent can use the exposed controls to issue potentially\ndisruptive actions on a device that another user is accessing.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n## ⚙️ Building/Compiling Manually\n\n### Build Requirements\n\nBesides Go, Go Hass Agent requires a javascript runtime/toolkit to bundle/build some assets required for the web UI.\n[Nodejs](https://nodejs.org/en) works just fine, is packaged in nearly all distributions and has good cross-platform\nsupport.\n\n\u003e [!NOTE]\n\u003e\n\u003e The devcontainer has all the necessary tooling installed for building Go Hass Agent.\n\n### Compiling\n\nFrom the root of the Go Hass Agent repository, use the following commands will\nbuild/bundle everything needed:\n\n```shell\nnpm install\nnpm run build:js\nnpm run build:css\n# the -X ... linker option is *required*\nCGO_ENABLED=0 go build -ldflags=\"-w -s -X github.com/joshuar/go-hass-agent/config.AppVersion=$(git describe --tags --always --long --dirty)\" -o dist/go-hass-agent\n```\n\nThis will build a binary and place it in `dist/go-hass-agent`.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### Cross Compilation\n\nGo Hass Agent can also be built for **arm (v6/v7)** and **arm64** with cross-compilation. Just change the `go build` in\nthe commands above as appropriate. For e.g.:\n\n```shell\nRUN GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -ldflags=\"-s -w -X github.com/joshuar/go-hass-agent/config.AppVersion=$(git describe --tags --always --long --dirty)\" -o dist/go-hass-agent\n```\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### Packages\n\nGo Hass Agent uses [nfpm](https://nfpm.goreleaser.com/) to create packages for Fedora, Arch, and Ubuntu/Debian.\n\nTo build packages, use the following invocations:\n\n```shell\nfor format in rpm deb archlinux; do\n  go run github.com/goreleaser/nfpm/v2/cmd/nfpm@latest package --packager ${format} --config .nfpm.yaml --target dist\ndone\n```\n\nThis will build packages for all possible formats and they will be available under the `dist/` folder.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### Container Images\n\nA Dockerfile that you can use to build an image can be found [here](../../Dockerfile).\n\nYou can build an image with a command like the following (using Podman):\n\n```shell\npodman build --file ./Dockerfile --tag go-hass-agent\n```\n\nAs with building a binary,\n[cross-compliation](https://docs.docker.com/build/building/multi-platform/#cross-compilation)\nis supported:\n\n```shell\n# use either linux/arm64, linux/arm/v7 or linux/arm/v6\npodman build --file ./Dockerfile --platform linux/arm/v7 --tag go-hass-agent\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e By default, the container will run as a user with UID/GID 1000/1000. You can pick a different UID/GID when building by\n\u003e adding `--build-arg UID=999` and `--build-arg GID=999` (adjusting the values as appropriate).\n\n[⬆️ Back to Top](#-table-of-contents)\n\n## 👋 Contributing\n\n\u003ca href=\"https://github.com/joshuar/go-hass-agent/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=joshuar/go-hass-agent\" /\u003e\n\u003c/a\u003e\n\n- Found an issue? Please\n  [report it](https://github.com/joshuar/go-hass-agent/issues/new?assignees=joshuar\u0026labels=\u0026template=bug_report.md\u0026title=%5BBUG%5D)!\n- Have a suggestion for a feature? Want a particular sensor/measurement added?\n  Submit a\n  [feature request](https://github.com/joshuar/go-hass-agent/issues/new?assignees=joshuar\u0026labels=\u0026template=feature_request.md\u0026title=)!\n- Want to help develop Go Hass Agent? See the\n  [contributing guidelines](CONTRIBUTING.md).\n\n\u003e [!NOTE]\n\u003e\n\u003e Please note, as an open-source and hobby project, the Go Hass Agent developers cannot commit to a response within any\n\u003e given time-frame. However, we do endeavor to try to provide an initial response, and ongoing cadence of 1 week.\n\n### 💾 Committing Code\n\nThis repository is using [conventional commit messages](https://www.conventionalcommits.org/en/v1.0.0/#summary). This\nprovides the ability to automatically include relevant notes in the [changelog](../CHANGELOG.md). The\n[TL;DR](https://en.wikipedia.org/wiki/TL;DR) is when writing commit messages, add a prefix:\n\n- `feat:` for a new feature, like a new sensor.\n- `fix:` when fixing an issue.\n- `refactor:` when making non-visible but useful code changes.\n- …and so on. See the link above or see the existing commit messages for\n  examples.\n\n### 📜 Code of Conduct\n\nPlease read the [Code of Conduct](https://github.com/joshuar/go-hass-agent/blob/master/CODE_OF_CONDUCT.md)\n\n[⬆️ Back to Top](#-table-of-contents)\n\n## 🧭 Roadmap\n\nCheck out [what I'm working on](https://github.com/joshuar/go-hass-agent/discussions/150) for future releases.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n## ❔ FAQ\n\n### _Can I change the units of the sensor?_\n\n- Yes! In the [customization options](https://www.home-assistant.io/docs/configuration/customizing-devices/) for a\n  sensor/entity, you can change the _unit of measurement_ (and _display precision_ if desired). This is useful for\n  sensors whose native unit is not very human-friendly. For example the memory sensors report values in bytes (B),\n  whereas you may wish to change the unit of measurement to gigabytes (GB).\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### _Can I disable some sensors?_\n\n- There is currently some limited support for disabling certain _groups_ of sensors. In the\n  [preferences](#️-preferences), under the `worker` sections, you can find some controls to disable some sensor groups.\n- Alternatively, you can disable the corresponding sensor entity in Home Assistant, and the agent will stop sending\n  updates for it.\n  - To disable a sensor entity, In the [customisation\n    options](https://www.home-assistant.io/docs/configuration/customizing-devices/) for a sensor/entity, toggle the\n    _Enabled_ switch. The agent will automatically detect the disabled state and send/not send updates as appropriate.\n  - Note that disabling a sensor in Home Assistant will **not** stop Go Hass Agent from gathering the raw data for the\n    sensor. Only disabling it via the Agent preferences file will stop any data gathering.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### _What is the resource (CPU, memory) usage of the agent?_\n\n- Very little in most cases. On Linux, the agent with all sensors working, should consume well less than 50 MB of memory\n  with very little CPU usage.\n- On Linux, many sensors rely on D-Bus signals for publishing their data, so CPU usage may be affected by the “business”\n  of the bus. For sensors that are polled on an interval, the agent makes use of some jitter in the polling intervals to\n  avoid a “thundering herd” problem.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### _I've updated the agent and now I've got a bunch of duplicate/removed/disabled sensors?_\n\n- Generally, Go Hass Agent will try to reserve sensor renames to [major version upgrades](#️-versioning), which may\n  contain breaking changes.\n- Unfortunately, sometimes sensor names may inadvertently get changed in non-major releases.\n- Regrettably, there is no way to rename the sensors in Home Assistant such that long-term statistics and existing automations and\n  dashboards continue to work uninterrupted.\n- For long-term statistics, you can remove the old sensors manually, under Developer Tools→Statistics in Home Assistant, for example. The\n  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\n  statistics database automatically.\n- For automations and dashboards the [repairs integration](https://www.home-assistant.io/integrations/repairs/), will direct you to any\n  broken items and how to fix them.\n\n  [![Open your Home Assistant instance to the repairs\nintegration.](https://my.home-assistant.io/badges/repairs.svg)](https://my.home-assistant.io/redirect/repairs)\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### _Can I reset the agent (start from new)?_\n\n- Yes. You can reset the agent so that it will re-register with Home Assistant and act as a new device. To do this:\n\n1. Stop Go Hass Agent if already running.\n2. Open your Home Assistant **_mobile_app_** integrations page:\n\n   [![Open your Home Assistant instance to the mobile_app\nintegration.](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration/?domain=mobile_app)\n\n3. 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.\n4. Click on the menu (three vertical dots) at the right of the entry:\n\n   ![Delete Agent Example](assets/screenshots/delete-from-mobile-app-integrations.png)\n\n5. Choose **Delete**.\n6. From a terminal, run the agent with the command: `go-hass-agent register --force` (add `--server someserver --token sometoken` for\n   non-graphical registration).\n7. The agent will go through the initial registration steps. It should report that registration was successful.\n8. Restart the agent.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### _Can (or does) the agent run as root or with privileges?_\n\n- You cannot run Go Hass Agent with root privileges or as the root user. The agent will refuse to run.\n- Some sensors do require additional\n  [capabilities](https://www.man7.org/linux/man-pages/man7/capabilities.7.html)\n  in order to access the required data.\n  - When you install via a package (rpm, deb, etc.), the agent binary will have the required capabilities.\n  - If you build yourself, you need to set the capabilities on your binary manually. Consult the [sensors list](#-sensors) for which sensors\n    require what capabilities.\n- If you have [script sensors](#-script-sensors) or [custom commands](#other-custom-commands) that need privileges, there are most likely\n  ways for the script/command to elevate to the privileges it needs as part of its execution.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### _Can the agent run in an MQTT-only mode?_\n\n- Unfortunately no, Go Hass Agent cannot run in an MQTT-only credentials. It makes use of the [Native App Integration\n  API](https://developers.home-assistant.io/docs/api/native-app-integration/) that is **not** MQTT only.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### _(Linux) Why do the disk rate sensors report a non-zero value while the IO operations in progress sensor is zero?_\n\n- The rate sensors are a derived value, taken by looking at the change in total IO operations since the sensor was last polled. The IO\n  operations in progress sensor is a point-in-time measurement taken at the time of polling. So short-lived IO operations, that generate\n  reads/writes but happen between polling intervals, won't be visible in the IO operations sensor but will contribute to the derived IO rate\n  sensors.\n- If you are wanting to track IO operations, I would recommend focusing on the IO operations value being at a certain value over a period of\n  time. Certainly however, for exact measurements, a dedicated monitoring solution is recommended.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### _(Linux) What does the value of the Firmware Security sensor mean?_\n\n- This is a **Host Security ID** value. More information can be found [here](https://fwupd.github.io/libfwupdplugin/hsi.html).\n\n[⬆️ Back to Top](#-table-of-contents)\n\n### _(Linux) Some of the hardware sensors are reporting incorrect values?_\n\n- Go Hass Agent sends the raw hardware sensor data without any chip-dependent scaling/transformation. If you are comparing the values to,\n  say, the output of sensors from the `sensors` command (part of _lm-sensors_), there will be discrepancies; _lm-sensors_ has a database of\n  chips with scaling/transformation information for their values and applies those as required before displaying the values.\n- Future versions of Go Hass Agent will hopefully use similar logic to scale/transform the hardware sensor values. As a workaround, you can\n  create a template sensor that scales/transforms values as appropriate.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n## 🤝 Acknowledgements\n\n- [Home Assistant](https://home-assistant.io), for providing a platform to watch and act on sensors and stuff.\n- This [Awesome README Template](https://github.com/Louis3797/awesome-readme-template), to create this awesome README.\n- [Prometheus Node Exporter](https://github.com/prometheus/node_exporter) code, for inspiration on some sensors.\n\n[⬆️ Back to Top](#-table-of-contents)\n\n## 🧑‍⚖️ License\n\n[MIT](LICENSE)\n\n[⬆️ Back to Top](#-table-of-contents)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshuar%2Fgo-hass-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoshuar%2Fgo-hass-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshuar%2Fgo-hass-agent/lists"}