# Project pack: Home Assistant @ 8a75c7d

Facts about **Home Assistant** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Home Assistant brings all your smart devices together in one app: lights, plugs, heating, door sensors, speakers and thousands more brands. Set up routines such as "turn the porch light on at sunset" or "tell me if the freezer door is left open". It runs on a small computer in your home, so it keeps working without the internet and your data stays with you. There is a phone app, a voice assistant and optional AI helpers.

## Version and source
- Repository: https://github.com/home-assistant/core
- Pinned commit: `8a75c7d26dee678983db83ae50782c25f0a56637`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/home-assistant/core/archive/8a75c7d26dee678983db83ae50782c25f0a56637.zip
- Official docs: https://www.home-assistant.io/docs/
- Live demo: https://demo.home-assistant.io. Official demo with pretend devices. Nothing you do there affects a real home.
- Licence: **Apache-2.0**. Permissive. Use, change and share it for anything, including commercially. Keep the copyright and licence notices and say which files you changed. No obligation to publish your changes.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/home-assistant/core bespoke-home-assistant
  cd bespoke-home-assistant
  git checkout --detach 8a75c7d26dee678983db83ae50782c25f0a56637
  # Prepare development requirements and local configuration first.
  # Setup notes: opens on http://localhost:8123
  script/setup && python3 -m homeassistant -c ./config
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --name homeassistant --privileged --restart=unless-stopped -e TZ=Europe/London -v /PATH_TO_YOUR_CONFIG:/config -v /run/dbus:/run/dbus:ro --network=host ghcr.io/home-assistant/home-assistant:stable
  # then open http://localhost:8123 and create your owner account.
  # Beginners: Home Assistant OS on a Raspberry Pi or Home Assistant Green is easier and adds one-click apps (add-ons).
  ```

- Needs: A computer that stays on (Raspberry Pi 4/5, mini PC, NAS or Home Assistant Green), Docker on Linux for the container install, or Home Assistant OS, For development, Python 3.14 and uv (script/setup installs the rest)
- Develop: `script/setup && python3 -m homeassistant -c ./config   # opens on http://localhost:8123`
- Test: `uv run --no-sync pytest tests/components/<integration>`
- Check/lint: `uv run --no-sync prek run --all-files`
- Stack: python, yaml, typescript (asyncio, aiohttp, voluptuous, Jinja2 templates, Lit (frontend, separate repo home-assistant/frontend)). Difficulty for a non-developer with an AI: **moderate**. Almost all personal adaptation is configuration: automations, scripts, scenes, dashboards and YAML files in your config folder, all of which an AI can write for you. New device support is a custom integration in your config folder. Changing core itself is advanced: a very large Python codebase (1,500+ integrations) with strict tests and reviews, and the web interface lives in a separate repository (home-assistant/frontend).

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`, `AI_POLICY.md`.

## Customisation points (settings → extend → code)
- **automations-scripts-scenes** [settings]: Routines with a trigger, conditions and actions, such as lights at sunset or a reminder when the washing is done. Built in the visual editor or written in YAML. → `Settings → Automations & scenes; saved to automations.yaml, scripts.yaml and scenes.yaml in your config folder (homeassistant/components/automation/, script/, scene/)`
- **dashboards-and-themes** [settings]: Arrange cards per room or person, a tablet wall panel, and your own colours and fonts. → `Settings → Dashboards (homeassistant/components/lovelace/); themes under frontend in configuration.yaml (homeassistant/components/frontend/__init__.py)`
- **helpers-and-templates** [settings]: Build your own switches and sensors, e.g. "bins go out tonight" or "is anyone home". → `Settings → Devices & services → Helpers (toggles, timers, counters, template sensors; homeassistant/components/template/)`
- **voice-and-ai** [settings]: Talk to your home, choose a local or cloud AI, and decide which devices it can control. → `Settings → Voice assistants (homeassistant/components/assist_pipeline/, conversation/); AI integrations such as ollama/, openai_conversation/, anthropic/, google_generative_ai_conversation/`
- **blueprints** [extend]: Ready-made automation recipes you import from the community and fill in with your own devices. → `Settings → Automations & scenes → Blueprints; examples in homeassistant/components/automation/blueprints/ and homeassistant/components/script/blueprints/`
- **notifications-and-phone** [extend]: Send alerts with buttons to your phone, or trigger automations from other apps and services. → `Companion app (homeassistant/components/mobile_app/), notify actions (homeassistant/components/notify/), webhooks (homeassistant/components/webhook/)`
- **api-and-mcp** [extend]: Let scripts, other apps or an AI assistant such as Claude read and control your home. → `REST and WebSocket APIs with long-lived access tokens from your profile (homeassistant/components/api/, websocket_api/); Model Context Protocol server (homeassistant/components/mcp_server/)`
- **custom-integrations** [extend]: Add support for a device or service that isn't built in, without changing core. → `A custom_components folder inside your config folder (loaded by homeassistant/loader.py); HACS is a popular community add-on for installing them`
- **core-integrations** [code]: Change or add a built-in integration. Advanced; usually better as a custom integration in your own config. → `homeassistant/components/<integration>/ (manifest.json, __init__.py, config_flow.py, strings.json); new ones scaffolded with python3 -m script.scaffold integration (script/scaffold/)`

## Must keep working
- The config folder, especially .storage and secrets.yaml. Make a backup before changing anything by hand.
- Automations that keep people safe or comfortable (heating, smoke and water alarms, door locks). Test changes before relying on them.
- YAML must stay valid. Use Developer tools → YAML → Check configuration before restarting.
- Admin-only actions and user permissions. Don't give non-admin users or outside scripts more access than they need.
- Changes to core need tests and must follow AGENTS.md; strings live in strings.json and English translations are generated from them.

## Staying updatable
Keep personal changes in your config folder (YAML, blueprints, dashboards, custom_components) so updates never clash with them. Home Assistant follows the Open Home Foundation AI policy: AI help is fine, but autonomous agents may not open issues or pull requests, and you must understand and be able to explain every change you submit. New integrations must meet the integration quality scale.

## Data, costs and safety
- Personal data: **yes**. Stored in: Everything lives in your config folder (/config in Docker): configuration.yaml and the automation, script and scene files, secrets.yaml, a hidden .storage folder with settings made in the app, and the history database home-assistant_v2.db (SQLite by default). Use Settings → System → Backups (automatic, encrypted backups, optionally off-site). A backup is the whole config folder. Test a restore before big upgrades or adding custom code.
- Service: Home Assistant Cloud (Nabu Casa) (optional, paid monthly subscription): Secure remote access without opening your router, Alexa and Google Assistant links, cloud voice and encrypted off-site backups. Funds the project.
- Service: AI conversation providers (OpenAI, Anthropic, Google Gemini and others) (optional, pay-per-use API): Let an AI understand free-form requests, describe camera pictures or write summaries. Configured as an integration with your own API key.
- Service: Ollama or another local model (optional, free (uses your own hardware)): The same AI conversation features without sending anything outside your home.
- Service: Home Assistant Companion app (iOS and Android) (optional, free): Phone notifications, location for "arriving home" automations, and phone sensors such as battery level.
- Service: Device makers' cloud services (optional, varies): Some brands only work through their own cloud account. Local options (Zigbee, Z-Wave, Matter, ESPHome) avoid this.
- Setting `TZ`: Your time zone (e.g. Europe/London) for the Docker container. Location, units and language are set in the app.
- Home Assistant can unlock doors and switch off heating. Never expose port 8123 to the internet directly; use Home Assistant Cloud, a VPN or a reverse proxy with HTTPS, and turn on two-factor login.
- Keep passwords and API keys in secrets.yaml and never paste secrets.yaml, .storage files or access tokens into an AI chat.
- With a cloud AI provider, your request and the names and states of the devices you expose to Assist are sent to that provider. Use Ollama for fully local processing, and expose only the devices the AI needs.
- Custom integrations and HACS add-ons run with full access to your home. Install only ones you trust.

---

# Customising Home Assistant

Home Assistant is built to be customised **without touching its code**. Nearly every family request is an
automation, a dashboard or a few lines of YAML in your config folder. Keep it that way: your changes then survive
every monthly update.

## Level 1: Settings (no code)
- **Automations, scripts and scenes:** Settings → Automations & scenes. The visual editor saves to `automations.yaml`, `scripts.yaml` and `scenes.yaml` in your config folder. An AI can write the YAML; paste it with *Edit in YAML*.
- **Dashboards:** Settings → Dashboards. One per person or device (a kitchen tablet, Grandma's phone). Cards per room, big buttons, pictures.
- **Themes:** add a `frontend:` section with `themes:` to `configuration.yaml`, then pick the theme in your profile.
- **Helpers:** Settings → Devices & services → Helpers for toggles ("guest mode"), timers, counters, schedules and template sensors.
- **People and zones:** Settings → People and Settings → Areas, labels & zones, for "when I get home" routines.
- **Voice and AI:** Settings → Voice assistants. Choose the built-in local assistant, a local model through Ollama, or a cloud AI integration. Choose which devices are exposed to it.

## Level 2: Extend (no fork)
- **Blueprints:** import community automation recipes and fill in your own devices. Examples ship in `homeassistant/components/automation/blueprints/`.
- **Companion app and notifications:** actionable phone notifications (`homeassistant/components/mobile_app/`), webhooks from other services (`homeassistant/components/webhook/`).
- **APIs:** REST and WebSocket APIs with a long-lived token from your profile; the MCP server integration (`homeassistant/components/mcp_server/`) lets an AI assistant like Claude see and control exposed devices.
- **Custom integrations:** put a folder in `custom_components` inside your config folder for a device that isn't supported. HACS (a community project) installs these for you. They run with full access, so trust the source.
- **Add-ons (apps):** on Home Assistant OS only, one-click extras such as a file editor, Mosquitto MQTT or Zigbee2MQTT.

## Level 3: Code
Read upstream `AGENTS.md` and `AI_POLICY.md` first. The web interface is a separate repository (`home-assistant/frontend`).

| Change | Where |
|---|---|
| Change an existing integration | `homeassistant/components/<name>/` (`__init__.py`, `config_flow.py`, platform files such as `sensor.py`) |
| UI text for an integration | `homeassistant/components/<name>/strings.json`, then `python3 -m script.translations develop --integration <name>` |
| New integration | `python3 -m script.scaffold integration` (templates in `script/scaffold/`) |
| AI and LLM tools | `homeassistant/helpers/llm.py`, `homeassistant/components/conversation/`, `homeassistant/components/ai_task/` |
| Loading of custom integrations | `homeassistant/loader.py` |
| Tests | `tests/components/<name>/` |

## Running locally
- **Just use it:** the Docker command in `bespoke.yaml`, then open http://localhost:8123. For a first home server, Home Assistant OS on a Raspberry Pi or Home Assistant Green is simpler.
- **Develop:**
  1. Install Python 3.14 and uv.
  2. Run `script/setup`.
  3. Run `python3 -m homeassistant -c ./config` and open http://localhost:8123.
- **Check:** `uv run --no-sync pytest tests/components/<name>` and `uv run --no-sync prek run --all-files`.

## Pitfalls
- Back up first (Settings → System → Backups). A broken YAML file can stop Home Assistant from starting.
- Check configuration (Developer tools → YAML) before every restart.
- Never edit files in `.storage` by hand while Home Assistant is running.
- Don't paste `secrets.yaml`, tokens or `.storage` files into an AI chat.
- Upstream does not accept pull requests or issues opened by autonomous agents. Keep personal code in `custom_components`.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/home-assistant/8a75c7d/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/home-assistant/8a75c7d/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/home-assistant/8a75c7d/r2/SKILL.md)