Home Assistant Add-On Development

Expert guidance for building, configuring, and publishing Home Assistant add-ons with Docker, Supervisor integration, and multi-architecture support.

Before You Start

This skill prevents common Home Assistant add-on development errors:

Issue	Symptom	Solution
Permission errors	Permission denied on supervisor API calls	Use correct SUPERVISOR_TOKEN and API endpoints
Configuration validation	Add-on won't load	Validate config.yaml schema before publishing
Docker base image errors	Missing dependencies in runtime	Use official Home Assistant base images (ghcr.io/home-assistant)
Ingress misconfiguration	Web UI not accessible through HA	Configure nginx reverse proxy correctly
Multi-arch build failures	Add-on only works on one architecture	Set up build.yaml with architecture matrix

Quick Start: Create an Add-On from Scratch

Step 1: Create the Add-On Directory Structure

mkdir -p my-addon/{rootfs,rootfs/etc/s6-overlay/s6-rc.d/service-name}
cd my-addon

Why this matters: Home Assistant expects specific directory layouts. The rootfs/ contains your actual application files that get packaged into the Docker image.

Step 2: Create config.yaml

---
name: My Custom Add-On
description: My awesome Home Assistant add-on
version: 1.0.0
slug: my-addon
image: ghcr.io/home-assistant/{arch}-addon-my-addon
arch:
  - amd64
  - armv7
  - aarch64
ports:
  8080/tcp: null
options:
  debug: false
schema:
  debug: bool
permissions:
  - homeassistant  # Read/write Home Assistant core data

Why this matters: This is your add-on's manifest. The slug becomes the internal identifier and determines where configuration is stored.

Step 3: Create the Dockerfile

FROM ghcr.io/home-assistant/amd64-base:latest

# Install dependencies
RUN apk add --no-cache python3 py3-pip

# Copy application
COPY rootfs /

# Set working directory
WORKDIR /app

# Install Python packages if needed
RUN if [ -f requirements.txt ]; then pip install -r requirements.txt; fi

# Run using S6 overlay
CMD ["/init"]

Why this matters: Using Home Assistant base images includes critical runtime components (S6 overlay, bashio helpers, supervisor integration).

Step 4: Create S6 Service Script

Create rootfs/etc/s6-overlay/s6-rc.d/service-name/run:

#!/command/execlineb -P
foreground { echo "Starting my add-on..." }
/app/my-service

Make it executable:

chmod +x rootfs/etc/s6-overlay/s6-rc.d/service-name/run

Why this matters: S6 overlay is Home Assistant's init system. It manages service startup, logging, and graceful shutdown.

Critical Rules

✅ Always Do

• ✅ Use official Home Assistant base images (ghcr.io/home-assistant/{arch}-base)
• ✅ Include all supported architectures in config.yaml (amd64, armv7, aarch64)
• ✅ Use bashio helper functions for common operations (bashio::log::info, bashio::addon::option)
• ✅ Validate config.yaml schema before releasing
• ✅ Document configuration options in the schema section
• ✅ Include addon_uuid in logs for debugging

❌ Never Do

• ❌ Don't hardcode paths - use bashio to get configuration directory (/data/)
• ❌ Don't run services as root unless absolutely necessary (set USER in Dockerfile)
• ❌ Don't call supervisor API without SUPERVISOR_TOKEN
• ❌ Don't ignore SIGTERM signals - implement graceful shutdown
• ❌ Don't assume one architecture - use {arch} placeholder in image names
• ❌ Don't store data outside /data/ - Home Assistant won't persist it

Common Mistakes

❌ Wrong: Hardcoded paths

#!/bin/bash
CONFIG_PATH="/config/my-addon"

✅ Correct: Using bashio for configuration

#!/command/execlineb -P
CONFIG_PATH=${"$(bashio::addon::config_path)"}

Why: bashio handles path resolution and ensures your add-on works in any Home Assistant installation.

Configuration Reference

config.yaml Structure

---
name: String                          # Display name
description: String                   # Short description
version: String                       # Semantic version (1.0.0)
slug: String                          # URL-safe identifier
image: String                         # Docker image URL with {arch} placeholder
arch:
  - amd64|armv7|aarch64|armhf|i386    # Supported architectures
ports:
  8080/tcp: null                      # TCP port (null=internal only, number=external)
  53/udp: 53                          # UDP with external port mapping
devices:
  - /dev/ttyACM0                      # Device access
services:
  - mysql                             # Depends on other service
options:
  debug: false                        # User configuration options
  log_level: info
schema:
  debug: bool                         # Configuration validation schema
  log_level:
    - debug
    - info
    - warning
    - error
permissions:
  - homeassistant                     # Read/write HA config
  - hassio                            # Full supervisor API access
  - admin                             # Broad system access
  - backup                            # Backup/restore operations
environment:
  NODE_ENV: production
webui: http://[HOST]:[PORT:8080]     # Web UI URL pattern
ingress: true                         # Enable ingress proxy
ingress_port: 8080                    # Internal port for ingress
ingress_entry: /                      # URL path for ingress entry

Key settings:

• slug: Used internally and in supervisor API calls
• arch: List all supported architectures or builds fail
• image: Must use {arch} placeholder for dynamic builds
• options: User-configurable settings
• permissions: Controls supervisor API access level
• ingress: Enables reverse proxy for web UIs

Common Patterns

Using bashio for Logging

#!/command/execlineb -P
foreground { bashio::log::info "Add-on started" }
foreground { bashio::log::warning "Low disk space" }
foreground { bashio::log::error "Failed to connect" }

Accessing Configuration Options

#!/command/execlineb -P
define DEBUG "$(bashio::addon::option 'debug')"
define LOG_LEVEL "$(bashio::addon::option 'log_level')"
if { test "${DEBUG}" = "true" }
  bashio::log::debug "Debug mode enabled"

Supervisor API Communication

#!/bin/bash
# Get addon info
curl -X GET \
  -H "Authorization: Bearer $SUPERVISOR_TOKEN" \
  http://supervisor/addons/self/info | jq .

# Send notification
curl -X POST \
  -H "Authorization: Bearer $SUPERVISOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Warning message"}' \
  http://supervisor/notifications/create

Multi-Arch Docker Build

Create build.yaml:

build_from:
  amd64: ghcr.io/home-assistant/amd64-base:latest
  armv7: ghcr.io/home-assistant/armv7-base:latest
  aarch64: ghcr.io/home-assistant/aarch64-base:latest
  armhf: ghcr.io/home-assistant/armhf-base:latest
codenotary: your-notary-id  # Optional code signing

Ingress Configuration for Web UIs

ingress: true
ingress_port: 8080
ingress_entry: /
# Optional ingress_stream for streaming endpoints

Inside your app, use correct reverse proxy headers:

# nginx configuration in your app
location / {
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header Host $host;
  proxy_pass http://localhost:8080;
}

Known Issues Prevention

Issue	Root Cause	Solution
Add-on fails to start	Missing S6 service files	Create /etc/s6-overlay/s6-rc.d/service-name/ with run executable
Supervisor API returns 401	Invalid SUPERVISOR_TOKEN	Verify token is set by Home Assistant (check logs with addon_uuid)
Configuration not persisting	Saving outside /data/	Always use bashio::addon::config_path or /data/ for persistence
Port already in use	Multiple services on same port	Check configuration - each service needs unique port
Architecture mismatch	{arch} placeholder not used	Use exact placeholder in image field: ghcr.io/home-assistant/{arch}-base
Build fails with "Unknown architecture"	config.yaml lists unsupported arch	Use only: amd64, armv7, aarch64, armhf, i386

Supervisor API Endpoints

# Authentication: Pass SUPERVISOR_TOKEN header
# Base URL: http://supervisor

GET /addons/self/info            # Get current add-on details
POST /addons/self/restart        # Restart this add-on
GET /addons/installed            # List installed add-ons
GET /info                        # System information
POST /notifications/create       # Send notification to user
GET /config/homeassistant        # Read Home Assistant config

# Example with bashio
bashio::addon::self_info         # Helper function for self info

Dependencies

Required

Package	Version	Purpose
Home Assistant	2024.1+	Add-on platform and supervisor
Docker	Latest	Container runtime
S6 Overlay	3.x	Init system (included in base images)

Optional

Package	Version	Purpose
bashio	Latest	Helper functions (included in base images)
python3	3.9+	Python-based add-ons
nodejs	18+	Node.js-based add-ons

Official Documentation

• Home Assistant Add-On Development
• Add-On Configuration Reference
• Supervisor Development
• bashio Helper Functions
• S6 Overlay Documentation

Troubleshooting

Add-on Won't Start

Symptoms: Add-on shows as "Not running" or "Unknown"

Solution:

# Check logs
docker logs addon_name_latest  # Or use HA UI: Settings > System > Logs

# Common causes:
# 1. Invalid config.yaml syntax
# 2. Missing S6 service files
# 3. Dockerfile can't find base image
# 4. Permission denied on rootfs files

Supervisor API Returns 401

Symptoms: API calls fail with "Unauthorized"

Solution:

# Verify SUPERVISOR_TOKEN is set
echo $SUPERVISOR_TOKEN

# Check add-on logs for token errors
# Token is automatically injected by Home Assistant

# Verify permissions in config.yaml
# If calling hassio endpoints, add: permissions: [hassio]

Configuration Not Saving

Symptoms: Options are lost after restart

Solution:

# Always save to /data/ or use bashio
CONFIG_PATH="$(bashio::addon::config_path)"  # Returns /data/
echo "my_value=123" > "${CONFIG_PATH}/settings.json"

# Verify /data/ exists and is writable
ls -la /data/

Ingress Web UI Not Accessible

Symptoms: Ingress URL returns 502 or blank page

Solution:

# 1. Verify service is listening on correct port
netstat -tlnp | grep 8080

# 2. Check reverse proxy headers in app config
# X-Forwarded-For, X-Forwarded-Proto must be set

# 3. Verify ingress settings in config.yaml
ingress: true
ingress_port: 8080
ingress_entry: /

Build Fails with Architecture Error

Symptoms: "Unknown architecture" or "Image not found"

Solution:

# Check config.yaml has valid arch values
arch:
  - amd64      # x86 64-bit
  - armv7      # 32-bit ARM (Pi 2/3)
  - aarch64    # 64-bit ARM (Pi 4+)
  - armhf      # 32-bit ARM (older devices)
  - i386       # 32-bit x86 (rare)

# Dockerfile must use {arch} placeholder
FROM ghcr.io/home-assistant/{arch}-base:latest

Setup Checklist

Before publishing your add-on, verify:

• config.yaml has valid YAML syntax (use online YAML validator)
• All listed architectures are supported (amd64, armv7, aarch64, armhf, i386)
• Dockerfile uses official Home Assistant base image
• S6 service files exist and are executable (chmod +x)
• All configuration options are documented in schema
• No hardcoded paths (use bashio helpers)
• Permissions field lists required supervisor API access
• Tested on at least amd64 and ARM architecture
• Logs use bashio::log functions
• Graceful shutdown on SIGTERM implemented
• /data/ used for all persistent data
• Ingress working if web UI is provided
• README includes installation and usage instructions

Creating a Repository

To publish multiple add-ons:

1. Create Repository Structure

mkdir my-addon-repo
cd my-addon-repo

2. Create repository.yaml

---
name: My Add-On Repository
url: https://github.com/username/my-addon-repo
maintainer: Your Name <email@example.com>

3. Add Add-Ons

my-addon-repo/
├── repository.yaml
├── my-addon-1/
│   ├── config.yaml
│   ├── Dockerfile
│   └── rootfs/
└── my-addon-2/
    ├── config.yaml
    ├── Dockerfile
    └── rootfs/

4. Push to GitHub

Add the repository URL to Home Assistant to make add-ons discoverable.

Advanced: Publishing to GitHub Container Registry

For private repositories or multi-architecture builds:

# Build and push for all architectures
docker buildx build \
  --platform linux/amd64,linux/arm/v7,linux/arm64/v8 \
  -t ghcr.io/username/my-addon:1.0.0 \
  --push .

Related Skills

• docker-configs - Docker fundamentals and best practices
• esphome-config-helper - Related IoT device integration patterns
• home-assistant-automation - Home Assistant automation and scripting