ha-addon

Create a directory with config.yaml defining name, slug, version, and supported architectures, plus a Dockerfile based on ghcr.io/home-assistant/{arch}-base images. Add executable S6 service scripts under rootfs/etc/s6-overlay/s6-rc.d/ to manage your application process.

Supervisor API 401 errors occur when the SUPERVISOR_TOKEN is missing or permissions are insufficient. The token is injected automatically by Home Assistant; verify your config.yaml includes the required permissions such as homeassistant or hassio for the endpoints you call.

Use official Home Assistant base images like ghcr.io/home-assistant/{arch}-base, which include S6 overlay and bashio helpers pre-installed. Generic Alpine or Ubuntu images lack these runtime components and cause supervisor integration failures.

Data loss happens when files are saved outside the /data/ directory, which is the only persisted volume for add-ons. Use bashio::addon::config_path to resolve the correct path and store all persistent state there.

Ingress 502 errors mean your application is not listening on the configured ingress_port or reverse proxy headers are missing. Verify the service binds to the correct port and sets X-Forwarded-For and X-Forwarded-Proto headers.

Supported architectures are amd64, armv7, aarch64, armhf, and i386. List them in config.yaml and use the {arch} placeholder in the image field so builds resolve the correct base image per architecture.