2025.3.4
Home ▸ Documentation ▸

Configuration.yaml

While you can configure most of KS Assistant from the user interface, for some integrations, you need to edit the configuration.yaml file.

This file contains integrationsIntegrations connect and integrate KS Assistant with your devices, services, and more. [Learn more] to be loaded along with their configurations. Throughout the documentation, you will find snippets that you can add to your configuration file to enable specific functionality.

Screenshot of an example of a configuration.yaml file, accessed using the File editor add-on on a KS Assistant Operating System installation. Example of a configuration.yaml file, accessed using the File editor add-on on a KS Assistant Operating System installation.

Editing configuration.yaml

How you edit your configuration.yaml file depends on your editor preferences and the installation method you used to set up KS Assistant. Follow these steps:

  1. Set up file access.
  2. Locate the config directory.
  3. Edit your configuration.yaml file.
  4. Save your changes and reload the configuration to apply the changes.

To set up access to the files and prepare an editor

Before you can edit a file, you need to know how to access files in KS Assistant and setup an editor. File access depends on your installation method. If you use KS Assistant Operating SystemKS Assistant OS, the KS Assistant Operating System, is an embedded, minimalistic, operating system designed to run the KS Assistant ecosystem. It is the recommended installation method for most users. [Learn more] or KS Assistant SupervisedKS Assistant Supervised is the full KS Assistant ecosystem, without the KS Assistant Operating System. [Learn more], you can use editor add-ons, for example, but not if you use KS Assistant CoreKS Assistant Core is the heart of KS Assistant itself. It is a Python program that powers every installation type, but can be installed standalone. [Learn more] or KS Assistant ContainerKS Assistant Container is a standalone container-based installation of KS Assistant Core. Any OCI compatible runtime can be used, but the documentation focus is on Docker. [Learn more].

To set up file access, follow the steps for your installation method:

To find the configuration directory

  1. To look up the path to your configuration directory, go to Settings > System > Repairs.

    • Select the three dots menu and select System information.

    Show system information option

  2. Find out the location of the Configuration directory.

    Screenshot showing the top of the system information panel

    • Unless you changed the file structure, the default is as follows: -
      • KS Assistant Operating SystemKS Assistant OS, the KS Assistant Operating System, is an embedded, minimalistic, operating system designed to run the KS Assistant ecosystem. It is the recommended installation method for most users. [Learn more]: the configuration.yaml is in the /config folder of the installation.
      • KS Assistant ContainerKS Assistant Container is a standalone container-based installation of KS Assistant Core. Any OCI compatible runtime can be used, but the documentation focus is on Docker. [Learn more]: the configuration.yaml is in the config folder that you mounted in your container.
      • KS Assistant CoreKS Assistant Core is the heart of KS Assistant itself. It is a Python program that powers every installation type, but can be installed standalone. [Learn more]: the configuration.yaml is in the config folder passed to the hass command (default is ~/.homeassistant).

  3. Once you located the config folder, you can edit your configuration.yaml file.

Note

If you have watched any videos about setting up KS Assistant using configuration.yaml (particularly ones that are old), you might notice your default configuration file is much smaller than what the videos show. Don’t be concerned, you haven’t done anything wrong. Many items in the default configuration files shown in those old videos are now included in the default_config: line that you see in your configuration file. Refer to the default config integration for more information on what’s included in that line.

Validating the configuration

After changing configuration or automation files, you can check if the configuration is valid. A configuration check is also applied automatically when you reload the configuration or when you restart KS Assistant.

The method for running a configuration check depends on your installation type. Check the common tasks for your installation type:

Reloading the configuration to apply changes

For configuration changes to become effective, the configuration must be reloaded. Most integrations in KS Assistant (that do not interact with devicesA device is a model representing a physical or logical unit that contains entities. or servicesThe term “service” in KS Assistant is used in the sense of an information service. For example, the municipal waste management service that provides entities for organic, paper, and packaging waste. In terms of functionality, the information service is like a device. It is called service to avoid confusion, as it does not come with a piece of hardware.) can reload changes made to their configuration in configuration.yaml without needing to restart KS Assistant.

  1. Under Settings, select the three dots menu (top right) , select Restart KS Assistant > Quick reload.

    Settings, three dot menu, restart KS Assistant

  2. If you find that your changes were not applied, you need to restart.

    • Select Restart KS Assistant.
    • Note: This interrupts automations and scripts.

    Reload and restart buttons

Troubleshooting the configuration

If you run into trouble while configuring KS Assistant, refer to the configuration troubleshooting page.

Related topics