Installation - hwhesselink/homekit-dashboard GitHub Wiki

The README explains how to do a basic install if you already have HACS installed. This page goes into more detail.

If you're not using HACS or, for instance, want to install the recommended card-mod performance improvements then you'll need access to your Home Assistant installation. The most common ways to do this are:

  • Studio Code Server
  • SSH ("Advanced SSH & Web Terminal")
  • Samba ("Samba share")
  • File editor

They can all be installed via Settings->Add-ons.

Installing HACS (recommended)

If you want to install HACS follow the instructions here. The requirement to have access to the Home Assistant file system can be ignored if you're just doing a basic install. You must have a valid Github account to link with HACS.

Dependencies

These can all be installed via HACS or manually, see their Github pages.

Mushroom cards

Most of the cards Homekit Dashboard uses are mushroom cards. Install manually via Github or via HACS:

Open in HACS at your Home Assistant instance.

Card-mod 3

Used by Homekit Dashboard to style and tune various elements using CSS. Install manually via Github or via HACS:

Open in HACS at your Home Assistant instance.

Once installed follow the steps under Performance improvements.

Kiosk mode

This is optional. It allows extra control of the layout of the dashboard. If installed it will by default remove the unused overflow button (top right) and the sidebar and menu button (top left) for non-admin users and on mobile devices. You can define a boolean helper to toggle visibility of the menu button, see here.

[!IMPORTANT] See here for information about version compatibility. If you're running a version of Home Assistant earlier than 2025.5.0 then you need to install Kiosk Mode v6.7.0 or earlier. If you install the pre-release version (v8) of Kiosk Mode you need to manually set the configuration.

Install manually via Github or via HACS:

Open in HACS at your Home Assistant instance.

Installing Homekit Dashboard

Via HACS

This is the easiest way:

Open in HACS at your Home Assistant instance.

Manual Install

If installing manually then on your Home Assistant instance:

  1. If it does not exist create the directory /config/www and restart Home Assistant
  2. Download the latest release and unpack it
  3. Copy the contents of the unpacked dist directory to /config/www
  4. Rename /config/www/homekit-dashboard.js to /config/www/homekit-dashboard.js?v=x.y.z where x.y.z is the version number of the release - this allows the front-end to recognize updates and flush its cache
  5. Add the file as a resource:

If using storage mode (the default)

  1. Go to Settings->Dashboards, click the 3 vertical dots at the top-right corner and select Resources (Note: if you do not see Resources you need to enable Advanced Mode in your User Profile)
  2. Click on ADD RESOURCE
  3. In the URL field enter /local/homekit-dashboard.js?v=x.y.z where the x.y.z matches the filename from above
  4. Make sure the Resource type is set to Javascript module
  5. Click CREATE

If using YAML mode

  1. Edit your configuration.yaml file and add the module as an extra_module_url:

    frontend:
      extra_module_url:
        - /local/homekit-dashboard.js?v=x.y.z
    
  2. Go to Developer tools and select the YAML tab

  3. Under Check and restart click on CHECK CONFIGURATION to verify the configuration

  4. Under YAML configuration reloading click on ALL YAML CONFIGURATION

After the resource has been added continue with Configuring Homekit Dashboard at the step beginning with "Restart Home Assistant: ".