Skip to main content

Add-On Configuration

Each add-on is stored in a folder. The file structure looks like this:

addon_name/
translations/
en.yaml
apparmor.txt
build.yaml
CHANGELOG.md
config.yaml
DOCS.md
Dockerfile
icon.png
logo.png
README.md
run.sh
note

Translation files, config and build all support .json, .yml and .yaml as the file type.

To keep it simple all examples are using .yaml

Add-on script

As with every Docker container, you will need a script to run when the container is started. A user might run many add-ons, so it is encouraged to try to stick to Bash scripts if you're doing simple things.

All our images have also bashio installed. It contains a set of commonly used operations and can be used to be included in add-ons to reduce code duplication across add-ons and therefore making it easier to develop and maintain add-ons.

When developing your script:

  • /data is a volume for persistent storage.
  • /data/options.json contains the user configuration. You can use Bashio to parse this data.
CONFIG_PATH=/data/options.json

TARGET="$(bashio::config 'target')"

So if your options contain

{ "target": "beer" }

then there will be a variable TARGET containing beer in the environment of your bash file afterwards.

Add-on Dockerfile

All add-ons are based on latest Alpine Linux image. Home Assistant will automatically substitute the right base image based on the machine architecture. Add tzdata if you need run in a different timezone. tzdata Is is already added to our base images.

ARG BUILD_FROM
FROM $BUILD_FROM

# Install requirements for add-on
RUN \
apk add --no-cache \
example_alpine_package

# Copy data for add-on
COPY run.sh /
RUN chmod a+x /run.sh

CMD [ "/run.sh" ]

If you don't use local build on device or our build script, make sure that the Dockerfile have also a set of labels include:

LABEL \
io.hass.version="VERSION" \
io.hass.type="addon" \
io.hass.arch="armhf|aarch64|i386|amd64"

It is possible to use own base image with build.yaml or if you do not need support for automatic multi-arch building you can also use a simple docker FROM.

Build Args

We support the following build arguments by default:

ARGDescription
BUILD_FROMHolds the image for dynamic builds or buildings over our systems.
BUILD_VERSIONAdd-on version (read from config.yaml).
BUILD_ARCHHolds the current build arch inside.

Add-on configuration

The configuration for an add-on is stored in config.yaml.

name: "Hello world"
version: "1.1.0"
slug: folder
description: >-
"Long description"
arch:
- amd64
url: "website with more information about add-on (e.g., a forum thread for support)"
ports:
123/tcp: 123
map:
- config:rw
- ssl
image: repo/{arch}-my-custom-addon

Note: Avoid the use of this filename for anything other than add-on configuration, as the Supervisor does a recursive lookup.

Required configuration options

KeyTypeDescription
namestringThe name of the add-on.
versionstringVersion of the add-on. If you are using a docker image with the image option, this needs to match the tag of the image that will be used.
slugstringSlug of the add-on. This needs to be unique in the scope of the repository that the add-on is published in and URI friendly.
descriptionstringDescription of the add-on.
archlistA list of supported architectures: armhf, armv7, aarch64, amd64, i386.

Optional configuration options

KeyTypeDefaultDescription
machinelistDefault it support any machine type. You can select that this add-on run only on specific machines. You can use ! before a machine type to negate it. By default all machines are allowed.
urlurlHomepage of the add-on. Here you can explain the add-ons and options.
startupstringapplicationinitialize will start add-on on setup of Home Assistant. system is for things like databases and not dependent on other things. services will start before Home Assistant, while application is started afterwards. Finally once is for applications that don't run as a daemon.
webuistringAn URL for the web interface of this add-on. Like http://[HOST]:[PORT:2839]/dashboard, the port needs the internal port, which will be replaced with the effective port. It is also possible to bind the protocol part to a configuration options with: [PROTO:option_name]://[HOST]:[PORT:2839]/dashboard and it's looked up if it is true and it's going to https.
bootstringautoauto start at boot is controlled by the system. manual for only manual starting.
portsdictNetwork ports to expose from the container. Format is "container-port/type": host-port. If the host port is null then the mapping is disabled.
ports_descriptiondictNetwork ports description mapping. Format is "container-port/type": "description of this port". Alternatively use Port description translations.
host_networkboolfalseIf true, the add-on runs on host network.
host_ipcboolfalseAllow to share the IPC namespace with others.
host_dbusboolfalseMap the host D-Bus service into the add-on.
host_pidboolfalseAllow to run container on host PID namespace. Works only for not protected add-ons. Warning: Does not work with S6 Overlay. If need this to be true and you use the normal add-on base image you disable S6 by overriding /init. Or use an alternate base image.
deviceslistDevice list to map into the add-on. Format is: <path_on_host>. E.g., /dev/ttyAMA0
homeassistantstringPin a minimum required Home Assistant Core version for the add-on. Value is a version string like 0.91.2.
hassio_rolestrdefaultRole-based access to Supervisor API. Available: default, homeassistant, backup, manager or admin
hassio_apiboolfalseThis add-on can access the Supervisor's REST API. Use http://supervisor.
homeassistant_apiboolfalseThis add-on can access to the Home Assistant REST API proxy. Use http://supervisor/core/api.
docker_apiboolfalseAllow read-only access to Docker API for add-on. Works only for not protected add-ons.
privilegedlistPrivilege for access to hardware/system. Available access: NET_ADMIN, SYS_ADMIN, SYS_RAWIO, SYS_TIME, SYS_NICE, SYS_RESOURCE, SYS_PTRACE, SYS_MODULE or DAC_READ_SEARCH
full_accessboolfalseGive full access to hardware like the privileged mode in Docker. Works only for not protected add-ons. Consider using other add-on options instead of this, like devices. If you enable this option, don't add devices, uart, usb or gpio this is not needed.
apparmorbool/stringfalseEnable or disable AppArmor support. If it is enable, you can also use custom profiles with the name of the profile.
maplistList of Home Assistant directories to bind mount into your container. Possible values: config, ssl, addons, backup, share or media. Defaults to ro, which you can change by adding :rw to the end of the name.
environmentdictA dictionary of environment variable to run add-on.
audioboolfalseMark this add-on to use internal audio system. We map a working PulseAudio setup into container. If your application does not support PulseAudio, you may need to install: Alpine Linux alsa-plugins-pulse or Debian/Ubuntu libasound2-plugins.
videoboolfalseMark this add-on to use the internal video system. All available devices will be mapped into the add-on.
gpioboolfalseIf this is set to true, /sys/class/gpio will map into add-on for access to GPIO interface from kernel. Some libraries also need /dev/mem and SYS_RAWIO for read/write access to this device. On systems with AppArmor enabled, you need to disable AppArmor or provide you own profile for the add-on, which is better for security.
usbboolfalseIf this is set to true, it would map the raw USB access /dev/bus/usb into add-on with plug&play support.
uartboolfalseDefault false. Auto mapping all UART/serial devices from the host into the add-on.
udevboolfalseDefault false. Set this true, gets the host udev database read-only mounted into the add-on.
devicetreeboolfalseIf this is set to True, /device-tree will map into add-on.
kernel_modulesboolfalseMap host kernel modules and config into add-on (readonly) and give you SYS_MODULE permission.
stdinboolfalseIf enabled, you can use the STDIN with Home Assistant API.
legacyboolfalseIf the Docker image has no hass.io labels, you can enable the legacy mode to use the config data.
optionsdictDefault options value of the add-on.
schemadictSchema for options value of the add-on. It can be false to disable schema validation and options.
imagestringFor use with Docker Hub and other container registries. This should be set to the name of the image only (E.g, ghcr.io/home-assistant/{arch}-addon-example). If you use this option, set the active docker tag using the version option.
codenotarystringFor use with Codenotary CAS. This is the E-Mail address used to verify your image with Codenotary (E.g, [email protected]). This should match the E-Mail address used as the signer in the add-on's extended build options
timeoutintegerDefault 10 (seconds). The timeout to wait until the Docker daemon is done or will be killed.
tmpfsboolfalseIf this is set to true, the containers /tmp is using tmpfs, a memory file system.
discoverylistA list of services that this add-on provides for Home Assistant. Currently supported: mqtt
serviceslistA list of services that will be provided or consumed with this add-on. Format is service:function and functions are: provide (this add-on can provide this service), want (this add-on can use this service) or need (this add-on need this service to work correctly).
auth_apiboolfalseAllow access to Home Assistant user backend.
ingressboolfalseEnable the ingress feature for the add-on.
ingress_portinteger8099For add-ons that run on the host network, you can use 0 and read the port later via API.
ingress_entrystring/Modify the URL entry point.
ingress_streamboolfalseWhen enabled requests to the add-on are streamed
panel_iconstringmdi:puzzleMDI icon for the menu panel integration.
panel_titlestringDefaults to the add-on name, but can be modified with this option.
panel_adminbooltrueMake menu entry only available with users in the admin group.
backupstringhothot or cold. If cold, the supervisor turns the add-on off before taking a backup (the pre/post options are ignored when cold is used).
backup_prestringCommand to execute in the context of the add-on before the backup is taken.
backup_poststringCommand to execute in the context of the add-on after the backup was taken.
backup_excludelistList of file/path (with glob support) that are excluded from backups.
codenotaryemailEmail address of the signer of this image used by Codenotary CAS.
advancedboolfalseSet this to true to require the user to have enabled "Advanced" mode for it to show.
stagestringstableFlag add-on with follow attribute: stable, experimental or deprecated. Add-ons set to experimental or deprecated will not show up in the store unless the user enables advanced mode.
initbooltrueSet this to false to disable the Docker default system init. Use this if the image has its own init system (Like s6-overlay). Note: Starting in V3 of S6 setting this to false is required or the addon won't start, see here for more information.
watchdogstringAn URL for monitor an application this add-on. Like http://[HOST]:[PORT:2839]/dashboard, the port needs the internal port, which will be replaced with the effective port. It is also possible to bind the protocol part to a configuration options with: [PROTO:option_name]://[HOST]:[PORT:2839]/dashboard and it's looked up if it is true and it's going to https. For simple TCP port monitoring you can use tcp://[HOST]:[PORT:80]. It work for add-ons on host or internal network.
realtimeboolfalseGive add-on access to host schedule including SYS_NICE for change execution time/priority.
journaldboolfalseIf set to true, the host's system journal will be mapped read-only into the add-on. Most of the time the journal will be in /var/log/journal however on some hosts you will find it in /run/log/journal. Add-ons relying on this capability should check if the directory /var/log/journal is populated and fallback on /run/log/journal if not.

Options / Schema

The options dictionary contains all available options and their default value. Set the default value to null if the value is required to be given by the user before the add-on can start, and it show it inside default values. Only nested arrays and dictionaries are supported with a deep of two size. If you want make an option optional, put ? to the end of data type, otherwise it will be a required value.

message: "custom things"
logins:
- username: beer
password: "123456"
- username: cheep
password: "654321"
random:
- haha
- hihi
link: "http://example.com/"
size: 15
count: 1.2

The schema looks like options but describes how we should validate the user input. For example:

message: str
logins:
- username: str
password: str
random:
- "match(^\\w*$)"
link: url
size: "int(5, 20)"
count: float
not_need: "str?"

We support:

  • str / str(min,) / str(,max) / str(min,max)
  • bool
  • int / int(min,) / int(,max) / int(min,max)
  • float / float(min,) / float(,max) / float(min,max)
  • email
  • url
  • password
  • port
  • match(REGEX)
  • list(val1|val2|...)
  • device / device(filter): Device filter can be following format: subsystem=TYPE i.e. subsystem=tty for serial devices.

Add-on extended build

Additional build options for an add-on is stored in build.yaml. This file will be read from our build systems. You need this only, if you not use the default images or need additional things.

build_from:
armhf: mycustom/base-image:latest
squash: false
args:
my_build_arg: xy
KeyRequiredDescription
build_fromnoA dictionary with the hardware architecture as the key and the base Docker image as value.
squashnoDefault False. Be careful with this option, as you can not use the image for caching stuff after that!
argsnoAllow to set additional Docker build arguments as a dictionary.
labelsnoAllow to set additional Docker labels as a dictionary.
codenotarynoAllows to enable container signature with codenotary CAS.
codenotary.signernoOwner signer E-Mail address for this image.
codenotary.base_imagenoVerify the base container image. If you use our official images, use [email protected]

We provide a set of base images which should cover a lot of needs. If you don't want use the Alpine based version or need a specific image tag, feel free to pin this requirements for you build with build_from option.

Add-on translations

Add-ons can provide translation files for configuration options that are used in the UI.

Example path to translation file: addon/translations/{language_code}.yaml

For {language_code} use a valid language code, like en, for a full list have a look here, en.yaml would be a valid filename.

This file support 2 main keys configuration and network.

Configuration translations

configuration:
ssl:
name: Enable SSL
description: Enable usage of SSL on the webserver inside the add-on

The key under configuration (ssl) in this case, needs to match a key in your schema configuration (in config.yaml).

Port description translations

network:
80/TCP: The webserver port (Not used for Ingress)

The key under network (80/TCP) in this case, needs to match a key in your ports configuration (in config.yaml).