name: home-assistant description: "Set up, manage, and troubleshoot Home Assistant Container running in Docker on a Linux server. Use when: (1) installing Home Assistant for the first time, (2) starting/stopping/restarting the HA service, (3) updating HA to latest version, (4) checking logs or service status, (5) validating HA configuration, (6) controlling smart home devices (climate, switches, sensors) via the REST API, (7) adding or troubleshooting integrations like SmartThings or LG ThinQ. NOT for: Home Assistant OS (HAOS), Supervised mode, or modifying integration-specific YAML beyond configuration.yaml."

Home Assistant Skill

Setup

One-shot install (installs Docker + starts HA):

sudo bash skills/home-assistant/scripts/setup.sh

What it does:

1. Installs Docker CE via official APT repo (skips if already present)
2. Creates /opt/homeassistant/config/
3. Copies assets/docker-compose.yml → /opt/homeassistant/
4. Copies assets/configuration.yaml → /opt/homeassistant/config/ (only if not already present)
5. Pulls HA image + starts container
6. Waits up to 90s and confirms HA is reachable on port 8123

After setup, open http://<server-ip>:8123 to complete onboarding and create your admin account.

API Token Setup

Required for device control commands. Generate a long-lived token once after onboarding:

bash skills/home-assistant/scripts/ha-ctl.sh gen-token <refresh_token>

Tokens are stored at /opt/homeassistant/botler.token (chmod 600). Never commit this file.

To find a refresh token: inspect .storage/auth on the HA host, or create one via the HA UI (Profile → Long-Lived Access Tokens) and save it manually to the token file.

Control

bash skills/home-assistant/scripts/ha-ctl.sh <command>

Container Management

| Command | Action | |----------------|-----------------------------------------------| | status | Container state + HA version + API reachability | | start | Start the container | | stop | Stop the container | | restart | Restart the container | | update | Pull latest image + recreate container | | logs | Last 100 log lines | | follow | Live log stream | | shell | Interactive bash inside the container | | config-check | Run HA's built-in config validator |

Device Queries (require API token)

| Command | Action | |----------------------|---------------------------------------------| | devices [filter] | List all entities, optional substring filter | | state <entity_id> | Full state + attributes for one entity | | ac | Quick AC status (climate.ar_sala) in °C |

Climate Control (require API token)

| Command | Action | |-------------------------------|------------------------------------------------| | on [entity_id] | Turn on (default: climate.ar_sala) | | off [entity_id] | Turn off (default: climate.ar_sala) | | set-temp <°C> [entity_id] | Set target temperature (auto-converts C→F for SmartThings) |

Key Paths

| Path | Purpose | |-----------------------------------------|--------------------------------| | /opt/homeassistant/docker-compose.yml | Container definition | | /opt/homeassistant/config/ | HA config dir (persisted) | | /opt/homeassistant/config/configuration.yaml | Main HA config | | /opt/homeassistant/botler.token | Long-lived API token (secret) |

HA web UI: http://<server-ip>:8123

Adding Integrations

All integrations are configured via the HA UI — no YAML needed:

Settings → Devices & Services → Add Integration

Notable integrations:

• SmartThings — Samsung ACs, presence sensors, SmartTags. Requires a PAT from account.smartthings.com/tokens.
• LG ThinQ — LG appliances via the ThinQ Connect API (v2 devices only; v1 hardware not supported). PAT from connect-pat.lgthinq.com.
• Met.no / OpenWeatherMap — local weather forecast (Met.no is built-in, no key needed).

SmartThings Temperature Note

SmartThings reports temperatures in °F regardless of HA locale settings. The set-temp and ac commands handle C↔F conversion automatically. If you see raw °F values in the UI, set the unit in the device's entity settings to °C.

Config Tips

• configuration.yaml uses default_config: which enables UI-based setup — don't remove it
• After editing configuration.yaml, always run config-check before restarting
• HA logs: /opt/homeassistant/config/home-assistant.log
• For YAML-only integrations (e.g., template:, input_boolean:), append to configuration.yaml and reload via UI (Settings → System → Restart → Quick reload)

Updating

bash skills/home-assistant/scripts/ha-ctl.sh update

Pulls ghcr.io/home-assistant/home-assistant:stable, recreates the container, preserves all config in /opt/homeassistant/config/.