TouchKio for Home Assistant Touchscreen Kiosks

TouchKio's dedicated Home Assistant panel role

TouchKio addresses a narrow device problem: running a Home Assistant dashboard as the primary interface on a Linux touchscreen that has no normal desktop workflow. The target is commonly a Raspberry Pi with a DSI or HDMI Touch Display, although the packaged application supports arm64 and x64 Debian-based hardware. The application is intended for a visible control panel rather than a general-purpose desktop browser.

The README says TouchKio addresses problems encountered with a browser's built-in fullscreen mode on Linux touch displays. It does not describe TouchKio as a browser replacement or a Home Assistant frontend. Instead, it embeds a web view in an Electron window, presents the selected dashboard fullscreen, and adds controls around that web content. The web address does not have to point to Home Assistant. The README states that any website can be shown in kiosk mode, although the MQTT features require a running Home Assistant instance.

This makes TouchKio relevant to installers, home automation operators, and kiosk builders who want the Home Assistant login retained on a panel. The documentation recommends a dedicated Home Assistant user with local access only. A physical keyboard or VNC access may be needed for the initial credential entry unless the supported hardware permits use of the side widget to activate the on-screen keyboard.

Electron, web view, and MQTT control paths

The repository identifies `index.js` as the application entry point and the `html/` and `js/` directories as its principal application areas. The `package.json` starts the project with Electron, so the runtime is a desktop application window rather than a server-rendered Home Assistant add-on. `electron-log` supports application logging, while the declared `axios`, `mqtt`, and `bonjour-service` packages indicate separate concerns around HTTP requests, MQTT communication, and local service discovery. The README does not provide a complete internal architecture, so those package roles should not be mistaken for a documented control protocol.

The primary content path begins with `--web-url`. TouchKio passes the configured address into its Electron kiosk window, where the Home Assistant dashboard receives touch input. The side panel exposes kiosk-specific controls, while the navigation bar can switch between configured pages. Browser zoom is adjustable, and theme support is listed as a feature. Login details entered during setup are stored under `~/.config/touchkio/`, according to the README.

The optional second path is MQTT. When an MQTT endpoint and the corresponding `--mqtt-*` arguments are configured, the device can publish Home Assistant sensors and accept remote commands. Documented capabilities include toggling the on-screen keyboard, controlling display power and brightness, changing window status and zoom, requesting a screenshot of the kiosk web view, showing network interfaces and addresses, and listing package upgrades. Commands also cover page switching, URL navigation, audio volume, reboot, shutdown, and monitoring for battery, temperature, processor, and memory. Reboot and shutdown move beyond dashboard presentation into operating-system control.

Home Assistant must have an MQTT broker available and its MQTT integration installed for this integration path. TouchKio is therefore split between a local Electron viewing layer and a device-automation layer with greater administrative consequences.

Installing TouchKio on Raspberry Pi OS

The documented Raspberry Pi configuration uses the latest Raspberry Pi OS 64-bit with a desktop environment, preferably `labwc`. The same `.deb` installation route is also documented for other Debian-based 64-bit systems. Before installation, the device and touch display should be checked against the repository's `HARDWARE.md`.

The README's simple installation path downloads the latest `.deb`, creates a systemd user service, and starts setup. It must run as the standard desktop user rather than with `sudo`:

bash <(wget -qO- https://raw.githubusercontent.com/leukipp/touchkio/main/install.sh)

The command executes a script fetched from the project repository. The README explicitly recommends reviewing `install.sh` before running external code. The installer enables a systemd user service by default, so TouchKio should start after the next boot.

Service management uses the following documented form. Replace the selected action with the operation you need:

systemctl --user start|stop|status|restart touchkio.service

On the first application run, TouchKio opens a CLI setup procedure and then presents the Home Assistant login screen. Enter the URL and credentials required by the setup flow. If the panel has no usable keyboard input yet, use a physical keyboard or VNC, or use the documented on-screen keyboard widget where the hardware is supported. TouchKio saves the Home Assistant credentials inside `~/.config/touchkio/` after login.

Running a minimal dashboard without MQTT

TouchKio can start as a plain kiosk without device automation. After installing a release manually, the README gives this example:

touchkio --web-url=https://demo.home-assistant.io

This starts the packaged application with a single web address. It is the simplest documented path for evaluating the fullscreen web view and entering Home Assistant credentials. The demo URL is an example in the documentation, not a project service.

The manual Debian route uses a local package and then invokes setup explicitly:

sudo apt install ./touchkio_1.x.x_arm64.deb && touchkio --setup

The `1.x.x` filename is a placeholder in the README rather than a specific downloadable release name. Users must select an actual arm64 `.deb` from the releases page. For non-Debian Linux distributions, the README documents `.zip` archives and gives this extraction and launch sequence:

unzip touchkio-linux-x64-1.x.x.zip && cd touchkio-linux-x64 && ./touchkio --setup

That archive name is likewise illustrative of the x64 package form. The `.zip` route launches the binary but does not establish the systemd startup behavior described for the easy installation path. SSH users also need the display variables described in the repository's development section before launching the graphical application. The README excerpt does not provide those variable assignments, so they should be taken from that section rather than guessed.

Touch and device constraints before deployment

TouchKio is not appropriate for a generic Linux workstation. Its premise is a persistent touchscreen panel, and the README specifically requires a compatible DSI or HDMI Touch Display. The supported release artifacts shown in the documentation cover arm64 and x64 Linux systems. The README begins an additional path for other architectures, but the visible setup section does not explain how that path works. Architecture support beyond the published packages should therefore not be assumed.

The application also depends on a working graphical session. Electron requires a display environment, which is why the README calls out exporting display variables for SSH operation. The preferred Raspberry Pi OS setup includes a desktop environment rather than a minimal headless installation. That dependency may complicate use on servers where Chromium-style kiosk applications would otherwise be useful.

MQTT setup introduces a different boundary. Without `--mqtt-*` options, TouchKio can display a URL without a local Home Assistant instance according to the README. Once MQTT control is enabled, the kiosk can expose device state and execute system actions. Operators therefore need to decide which commands Home Assistant automations can send and which credentials grant access. The README does not document command retention policies, credential-rotation procedures, or MQTT security details. It is also silent about how stored authentication data is protected beyond identifying the `~/.config/touchkio/` folder.

The hardware list is not an aesthetic preference. Display power, brightness, keyboard activation, screenshot behavior, and other features depend on the attached device. An unsupported panel may display the web view while failing to provide the intended control functions.

Alternative approaches and TouchKio maintenance

A browser launched in kiosk mode is the direct alternative for a dashboard with no device-control requirements. The browser approach asks the operating system or display environment to keep a fullscreen window open, while TouchKio supplies an Electron runtime, stored credentials, navigation controls, zoom controls, a side panel, and optional MQTT integration. TouchKio also targets the specific Linux touch-display problems cited by its README. The trade-off is more application machinery and operating-system commands in exchange for panel-specific functions.

For remote control, Home Assistant automations can target other mechanisms, but the README does not describe a supported TouchKio alternative for display brightness, volume, screenshots, package updates, or power commands. The comparison should therefore stay within documented choices: use a kiosk browser when only a web page is needed, and use TouchKio when the dedicated dashboard and device controls justify an installed Electron application.

TouchKio uses the MIT license. The repository includes a `LICENSE` file, and `package.json` also declares `"license": "MIT"`. That means the source carries an MIT license grant, but license review remains a separate step from operational validation. No legal interpretation is required for normal use.

Repository records show ongoing recent work. The repository is not archived, the last push was on 2026-09-17, and release `v1.6.0` was published on 2026-09-17. Earlier releases include `v1.5.2` on 2026-09-07 and `v1.5.1` on 2026-08-30. The package declares version `1.6.0`.

Upgrade cost depends on deployment method. The simple installer retrieves the latest package and manages startup, but the README does not document rollback. Manual users must replace the packaged application themselves and preserve or recreate the systemd service. Local credentials in `~/.config/touchkio/` should be treated as configuration state rather than assumed to be removed by a package replacement, although the README does not state an upgrade migration policy.

Editorial conclusion

TouchKio is appropriate for a dedicated Raspberry Pi or other supported Debian device with a persistent touch display and a Home Assistant dashboard. It is a poor fit for users who only need a browser shortcut or require an unsupported Linux architecture. Verify the device against HARDWARE.md, inspect install.sh before execution, and confirm that Home Assistant MQTT credentials and automation permissions match the intended controls before adoption.

Frequently asked questions

Official sources

1. leukipp/touchkio on GitHub
2. License: MIT
3. Project website
4. README
5. Releases