Each add-on is stored in a folder. The file structure looks like this:
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:
/datais a volume for persistent storage.
/data/options.jsoncontains the user configuration. You can use Bashio to parse this data.
So if your
then there will be a variable
beer in the environment of your bash file afterwards.
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.
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:
It is possible to use own base image with
build.json or if you do not need support for automatic multi-arch building you can also use a simple docker
We support the following build arguments by default:
|BUILD_FROM||Hold image for dynamic builds or buildings over our systems.|
|BUILD_VERSION||Add-on version (read from |
|BUILD_ARCH||Hold current build arch inside.|
The configuration for an add-on is stored in
|name||string||yes||Name of the add-on.|
|version||string||yes||Version of the add-on.|
|slug||string||yes||Slug 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.|
|description||string||yes||Description of the add-on.|
|arch||list||yes||List of supported arch: |
|machine||list||no||Default it support any machine type. You can select that this add-on run only on specific machines. You can use |
|url||url||no||Homepage of the add-on. Here you can explain the add-ons and options.|
|webui||string||no||An URL for the web interface of this add-on. Like |
|ports||dict||no||Network ports to expose from the container. Format is |
|ports_description||dict||no||Network ports description mapping. Format is |
|devices||list||no||Device list to map into the add-on. Format is: |
|homeassistant||string||no||Pin a minimum required Home Assistant Core version for the add-on. Value is a version string like |
|hassio_api||bool||no||This add-on can access the Supervisor's REST API. Use |
|homeassistant_api||bool||no||This add-on can access to the Home Assistant REST API proxy. Use |
|docker_api||bool||no||Allow read-only access to Docker API for add-on. Works only for not protected add-ons.|
|privileged||list||no||Privilege for access to hardware/system. Available access: |
|full_access||bool||no||Give full access to hardware like the privileged mode in Docker. Works only for not protected add-ons.|
|apparmor||bool/string||no||Enable or disable AppArmor support. If it is enable, you can also use custom profiles with the name of the profile.|
|map||list||no||List of maps for additional Home Assistant folders. Possible values: |
|environment||dict||no||A dictionary of environment variable to run add-on.|
|audio||bool||no||Mark 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 |
|video||bool||no||Mark this add-on to use the internal video system. All available devices will be mapped into the add-on.|
|gpio||bool||no||If this is set to |
|usb||bool||no||If this is set to |
|devicetree||bool||no||Boolean. If this is set to True, |
|kernel_modules||bool||no||Map host kernel modules and config into add-on (readonly).|
|stdin||bool||no||Boolean. If enabled, you can use the STDIN with Home Assistant API.|
|legacy||bool||no||Boolean. If the Docker image has no |
|options||dict||yes||Default options value of the add-on.|
|schema||dict||yes||Schema for options value of the add-on. It can be |
|image||string||no||For use with Docker Hub and other container registries.|
|timeout||integer||no||Default 10 (seconds). The timeout to wait until the Docker daemon is done or will be killed.|
|tmpfs||string||no||Mount a tmpfs filesystem in |
|discovery||list||no||A list of services that this add-on provides for Home Assistant. Currently supported: |
|services||list||no||A list of services that will be provided or consumed with this add-on. Format is |
|auth_api||bool||no||Allow access to Home Assistant user backend.|
|ingress||bool||no||Enable the ingress feature for the add-on.|
|ingress_entry||string||no||Modify the URL entry point from |
|panel_title||string||no||Default is the add-on name, but can be modified with this option.|
|snapshot_exclude||list||no||List of file/path (with glob support) that are excluded from snapshots.|
|watchdog||string||no||An URL for monitor an application this add-on. Like |
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.
schema looks like
options but describes how we should validate the user input. For example:
Additional build options for an add-on is stored in
build.json. 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||no||A dictionary with the hardware architecture as the key and the base Docker image as value.|
|args||no||Allow to set additional Docker build arguments as a dictionary.|
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