# Home Assistant

Self-hosted home automation platform. The primary reason this Pi exists.

## Access
- **Tailscale:** [homeassistant.bunny-wyvern.ts.net](https://homeassistant.bunny-wyvern.ts.net)
- **LAN:** `http://[pi-ip]:8123` (port exposed but access via Tailscale preferred)

## Containers

| Container | Image | Role |
|---|---|---|
| `homeassistant` | `lscr.io/linuxserver/homeassistant:latest` | Home automation hub |
| `homeassistant-tailscale-sidecar` | `tailscale/tailscale:latest` | Tailscale node |

## Compose File
**Path:** `/home/artanis/Desktop/HomeAssistant/docker-compose.yaml` (on the Pi)

> Note: Dockhand reports the stack dir as `/DockerFiles/home_assistant/` — this is the path as seen from inside the Hawser agent context. The actual host path is via `~/Desktop/HomeAssistant/`.

```yaml
services:
  homeassistant:
    image: lscr.io/linuxserver/homeassistant:latest
    container_name: homeassistant
    network_mode: host
    environment:
      - PUID=1000
      - PGID=1000
      - TZ: America/Chicago
    cap_add:
      - NET_ADMIN
      - NET_RAW
    volumes:
      - /home/artanis/Desktop/HomeAssistant/config:/config
      - /run/dbus:/run/dbus:ro
      - /home/artanis/Desktop/HomeAssistant/media:/media
    ports:
      - 8123:8123
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    restart: unless-stopped

  homeassistant-tailscale-sidecar:
    image: tailscale/tailscale:latest
    container_name: homeassistant-tailscale-sidecar
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    volumes:
      - homeassistant_tailscale_state:/var/lib/tailscale
    environment:
      - TS_AUTHKEY=<redacted>
      - TS_HOSTNAME=homeassistant
      - TS_STATE_DIR=/var/lib/tailscale
    network_mode: "service:homeassistant"

volumes:
  homeassistant_tailscale_state:

# matter-server is defined but commented out
```

## Data Layout

| Path | Contents |
|---|---|
| `/home/artanis/Desktop/HomeAssistant/config` | HA configuration, automations, integrations |
| `/home/artanis/Desktop/HomeAssistant/media` | Media files for HA |
| `/run/dbus` | Host D-Bus socket (read-only, for Bluetooth) |

## Hardware Devices

| Device | Purpose |
|---|---|
| `/dev/ttyUSB0` | USB serial device — likely a Zigbee or Z-Wave stick |

## Notes
- `network_mode: host` — Home Assistant runs on the Pi's full host network. This is required for mDNS/Bonjour device discovery, Bluetooth, and multicast protocols that don't work through Docker's bridge NAT
- `cap_add: NET_ADMIN, NET_RAW` — required for network-level features (e.g. ping, ARP for device tracking)
- `/run/dbus` is mounted read-only for Bluetooth integration via D-Bus
- **Matter server** is fully defined in the compose file but commented out — can be enabled when needed
- There is an orphaned volume `homeassistant_homeassistant_tailscale_state` from an earlier stack iteration (project was named `homeassistant` instead of `home_assistant`)