ha-addon

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: ha-addon
description: "Develop Home Assistant add-ons with Docker, Supervisor API, and multi-arch builds. Use when creating add-ons, configuring Dockerfiles, setting up ingress, or publishing to repositories. Activates on keywords: add-on, addon, supervisor, hassio, ingress, bashio, docker."
---

# 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

```bash
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

```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

```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`:

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

Make it executable:
```bash
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**
```bash
#!/bin/bash
CON