Skip to main content

Local add-on testing

The fastest and recommended way to develop add-ons is using a local Visual Studio Code devcontainer. We maintain a devcontainer for this purpose which is used in all our add-on repositories. This devcontainer setup for VS Code runs Supervisor and Home Assistant, with all of the add-ons mapped as local add-ons inside, making it simple for add-on developers on Windows, Mac and Linux desktop OS-es.

  • Follow the instructions to download and install the Remote Containers VS Code extension.
  • Copy the devcontainer.json file to .devcontainer/devcontainer.json in your repository.
  • Copy the tasks.json file to .vscode/tasks.json in your repository.
  • Open the root folder inside VS Code, and when prompted re-open the window inside the container (or, from the Command Palette, select 'Rebuild and Reopen in Container').
  • When VS Code has opened your folder in the container (which can take some time for the first run) you'll need to run the task (Terminal -> Run Task) 'Start Home Assistant', which will bootstrap Supervisor and Home Assistant.
  • You'll then be able to access the normal onboarding process via the Home Assistant instance at http://localhost:7123/.
  • The add-on(s) found in your root folder will automatically be found in the Local Add-ons repository.

Remote development

If you require access to physical hardware or other resources that cannot be locally emulated (for example, serial ports), the next best option to develop add-ons is by adding them to the local add-on repository on a real device running Home Assistant. To access the local add-on repository on a remote device, install either the Samba or the SSH add-ons and copy the add-on files to a subdirectory of /addons.

Right now add-ons will work with images that are stored on Docker Hub (using image from add-on config). To ensure that the add-on is built locally and not fetched from an upstream repository, ensure that the image key is commented out in your config.yaml file (You can do that by adding a # in front of it, like #image: xxx).

Local build

If you don't want to use the devcontainer environment, you can still build add-ons locally with Docker. The recommended method is to use the official build tool to create the Docker images.

Assuming that your addon is in the folder /path/to/addon and your Docker socket is at /var/run/docker.sock, you can build the addon for all supported architectures by running the following:

docker run \
--rm \
-it \
--name builder \
--privileged \
-v /path/to/addon:/data \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
ghcr.io/home-assistant/amd64-builder \
-t /data \
--all \
--test \
-i my-test-addon-{arch} \
-d local

If you don't want to use the official build tool, you can still build with standalone Docker. If you use FROM $BUILD_FROM you'll need to set a base image with build args. Normally you can use following base images:

  • armhf: homeassistant/armhf-base:latest
  • aarch64: homeassistant/aarch64-base:latest
  • amd64: homeassistant/amd64-base:latest
  • i386: homeassistant/i386-base:latest

Use docker from the directory containing the add-on files to build the test addon:

docker build \
--build-arg BUILD_FROM="homeassistant/amd64-base:latest" \
-t local/my-test-addon \
.

Local run

If you don't want to use the devcontainer environment, you can still run add-ons locally with Docker.

For that you can use the following command:

docker run \
--rm \
-v /tmp/my_test_data:/data \
-p PORT_STUFF_IF_NEEDED \
local/my-test-addon

Logs

All stdout and stderr outputs are redirected to the Docker logs. The logs can be fetched from the add-on page inside the Supervisor panel in Home Assistant.