# Home Assistant Core — User Guide

## 1. Quick Start

Home Assistant is an open-source home automation platform that puts local control and privacy first. It runs as a Python application on Linux, macOS, or Windows (WSL), tracking the state of every device in your home and providing a unified web interface, automation engine, and voice assistant integrations to control everything from one place.

**Key features:**

- **Local control** — all processing happens on your hardware, no cloud dependency required
- **2,000+ integrations** — supports virtually every smart home protocol and device
- **Automation engine** — trigger-condition-action rules with templates, blueprints, and tracing
- **Voice assistant support** — Alexa, Google Home, and local Assist pipeline
- **WebRTC camera streaming** — via built-in go2rtc server
- **Multi-user authentication** — JWT-based with MFA, groups, and per-entity permissions
- **Real-time dashboards** — customizable Lovelace UI with live state updates
- **Historical data** — SQLite-backed recorder with long-term statistics

**Prerequisites:** Python 3.13+, Linux/macOS/WSL

**Install and run:**

```bash
pip install homeassistant
hass
```

```text
Home Assistant is starting...
Open the frontend at http://localhost:8123
```

> [!TIP]
> The recommended installation method is Home Assistant Operating System (HAOS) on dedicated hardware or a VM. The `pip install` method above is for Home Assistant Core only — see the Installation section for all options.

**What to try next:**

- Open the web UI at `http://<your-host>:8123` and create your owner account
- Add your first integration via **Settings → Devices & Services**
- Create an automation via **Settings → Automations & Scenes**
- See the Admin Guide for architecture details and full configuration reference

---

## 2. Installation

### System Requirements

| Requirement | Minimum |
|---|---|
| **Operating System** | Linux, macOS, or Windows via WSL |
| **Python** | 3.13 or higher |
| **Architecture** | x86_64 or aarch64 |
| **RAM** | 2 GB (4 GB+ recommended) |
| **Storage** | 32 GB (SSD recommended for recorder database) |
| **Network** | Local network access for device discovery |

> [!IMPORTANT]
> Home Assistant does not support native Windows. You must use Windows Subsystem for Linux (WSL) on Windows systems. The `--ignore-os-check` flag can bypass this validation but is unsupported.

### Installation Methods

=== "Home Assistant OS (Recommended)"
    ```text
    Download the appropriate image for your hardware from the Home Assistant
    installation page. Flash it to an SD card, SSD, or VM disk. Boot and
    access the web UI at http://homeassistant.local:8123.

    Supported hardware: Raspberry Pi 3/4/5, ODROID, Intel NUC, generic x86-64,
    Home Assistant Green, Home Assistant Yellow.
    ```

=== "Docker"
    ```bash
    docker run -d \
      --name homeassistant \
      --privileged \
      --restart=unless-stopped \
      -e TZ=America/New_York \
      -v /path/to/config:/config \
      -v /run/dbus:/run/dbus:ro \
      --network=host \
      ghcr.io/home-assistant/home-assistant:stable
    ```

=== "Home Assistant Core (pip)"
    ```bash
    python3 -m venv homeassistant
    source homeassistant/bin/activate
    pip install homeassistant
    hass
    ```

=== "Home Assistant Supervised"
    ```text
    Install on a Debian 12 host with the Home Assistant Supervised installer.
    Provides the Supervisor add-on system on top of a standard Linux install.
    ```

### Post-Install Verification

```bash
hass --version
```

```text
2026.5.0
```

Access the web interface at `http://<your-host>:8123`. On first launch, you will be guided through onboarding to create the owner account, set your location, and discover devices.

### Command-Line Interface

The `hass` command is the main entry point:

| Flag | Description |
|---|---|
| `--version` | Show the installed version |
| `-c`, `--config` | Path to configuration directory (default: `~/.homeassistant`) |
| `--recovery-mode` | Start in recovery mode (minimal integrations) |
| `--debug` | Enable debug mode |
| `--open-ui` | Open the web interface in a browser on startup |
| `--skip-pip` | Skip pip install of required packages on startup |
| `--skip-pip-packages` | Comma-separated list of specific packages to skip |
| `-v`, `--verbose` | Enable verbose logging to file |
| `--log-rotate-days` | Enable daily log rotation, keep N days |
| `--log-file` | Path to log file (default: `CONFIG/home-assistant.log`) |
| `--log-no-color` | Disable colored log output |
| `--script` | Run an embedded script (e.g., `hass --script check_config`) |
| `--ignore-os-check` | Skip operating system validation |

> [!WARNING]
> The `--skip-pip` flag prevents Home Assistant from installing integration dependencies on startup. Use only in containerized environments where dependencies are pre-installed.

### Install Troubleshooting

### Error: `Home Assistant only supports Linux, OSX and Windows using WSL`

**Cause:** Running on native Windows without WSL.

**Solution:**
1. Install WSL 2 on Windows
2. Install a Linux distribution (Ubuntu recommended)
3. Run Home Assistant inside the WSL environment

**Prevention:** Always use WSL on Windows systems.

### Error: `Home Assistant requires at least Python 3.13.0`

**Cause:** The system Python version is too old.

**Solution:**
1. Install Python 3.13+ using your package manager or `pyenv`
2. Create a new virtual environment with the correct Python version

**Prevention:** Check `python3 --version` before installing.

### Error: `Fatal Error: Specified configuration directory does not exist`

**Cause:** The path passed to `-c` / `--config` does not exist.

**Solution:**
1. Create the directory: `mkdir -p /path/to/config`
2. Or use the default directory by omitting the `-c` flag

**Prevention:** Verify the config directory path before starting.

### Error: `Fatal Error: Unable to create library directory`

**Cause:** Insufficient permissions to create the `deps/` subdirectory inside the config directory.

**Solution:**
1. Ensure the user running `hass` has write permissions to the config directory
2. Check directory ownership: `chown -R $USER:$USER /path/to/config`

**Prevention:** Run Home Assistant as a user with appropriate permissions.

### Error: `Another instance of Home Assistant is already running`

**Cause:** A lock file indicates another `hass` process is using this config directory.

**Solution:**
1. Check for running processes: `ps aux | grep hass`
2. Stop the existing instance before starting a new one

**Prevention:** Use a single instance per configuration directory.

### Error: `ModuleNotFoundError: No module named 'homeassistant'`

**Cause:** The virtual environment is not activated or Home Assistant is not installed.

**Solution:**
1. Activate your virtual environment: `source homeassistant/bin/activate`
2. Reinstall: `pip install homeassistant`

**Prevention:** Always activate the virtual environment before running `hass`.

### Error: `Could not install required packages`

**Cause:** pip cannot resolve or download integration dependencies.

**Solution:**
1. Check your internet connection
2. Update pip: `pip install --upgrade pip`
3. If behind a proxy, configure pip proxy settings
4. Use `--skip-pip-packages` for problematic packages and install them manually

**Prevention:** Ensure network access and up-to-date pip before starting.

### Error: `Permission denied: '/config/home-assistant.log'`

**Cause:** The user running Home Assistant does not have write access to the log file.

**Solution:**
1. Fix permissions: `chmod 664 /config/home-assistant.log`
2. Or specify a different log file: `--log-file /tmp/hass.log`

**Prevention:** Run Home Assistant as a user with write access to the config directory.

### Error: Process exits with non-zero code immediately

**Cause:** Configuration file has syntax errors or a critical integration fails during bootstrap.

**Solution:**
1. Check the configuration: `hass --script check_config`
2. Start in recovery mode: `hass --recovery-mode`
3. Review the log file for detailed error messages

**Prevention:** Validate configuration before restarting.

### Error: Web interface not accessible

**Cause:** Home Assistant is still starting up, or the HTTP integration failed to bind.

**Solution:**
1. Wait for the startup to complete (check logs for "Home Assistant initialized")
2. Verify the port is not in use: `ss -tlnp | grep 8123`
3. Check firewall rules allow port 8123

**Prevention:** Monitor startup logs and ensure no port conflicts.

---

## 3. Configuration

Home Assistant uses YAML configuration files stored in the configuration directory (default: `~/.homeassistant` or `/config` in containers).

### Core Configuration File

The primary configuration file is `configuration.yaml`. A minimal configuration:

```yaml
homeassistant:
  name: Home
  latitude: 32.87
  longitude: -117.22
  elevation: 430
  unit_system: metric
  currency: USD
  country: US
  time_zone: America/Los_Angeles

default_config:
```

> [!TIP]
> The `default_config:` line enables a curated set of default integrations including the frontend, automation, recorder, history, and device discovery. Most users should keep this enabled.

### Core Configuration Options

| Key | Type | Description |
|---|---|---|
| `name` | string | Name of your Home Assistant instance |
| `latitude` | float | Latitude of your home location |
| `longitude` | float | Longitude of your home location |
| `elevation` | integer | Elevation above sea level in meters |
| `unit_system` | string | `metric` or `us_customary` |
| `currency` | string | ISO 4217 currency code |
| `country` | string | ISO 3166 country code |
| `time_zone` | string | IANA timezone identifier |
| `internal_url` | string | URL for internal network access |
| `external_url` | string | URL for external (internet) access |
| `allowlist_external_dirs` | list | Directories accessible to integrations |
| `allowlist_external_urls` | list | URLs accessible to integrations |
| `packages` | dict | Configuration packages for modular config |

### Supporting Configuration Files

Home Assistant automatically creates and manages several YAML files:

| File | Purpose |
|---|---|
| `configuration.yaml` | Primary configuration |
| `automations.yaml` | Automation definitions (UI-managed) |
| `scripts.yaml` | Script definitions (UI-managed) |
| `scenes.yaml` | Scene definitions (UI-managed) |
| `secrets.yaml` | Secret values (passwords, tokens, keys) |
| `customize.yaml` | Entity customization overrides |

### Using Secrets

Store sensitive values in `secrets.yaml` and reference them with `!secret`:

```yaml
# secrets.yaml
mqtt_password: my_secure_password

# configuration.yaml
mqtt:
  broker: 192.168.1.100
  password: !secret mqtt_password
```

> [!IMPORTANT]
> Never commit `secrets.yaml` to version control. Add it to your `.gitignore` file.

### Configuration Packages

Split large configurations into separate files using packages:

```yaml
# configuration.yaml
homeassistant:
  packages:
    lighting: !include packages/lighting.yaml
    security: !include packages/security.yaml
```

Each package file can contain configuration for multiple domains, making it easy to organize by function rather than by integration.

### Environment Variables

| Variable | Purpose |
|---|---|
| `SUPERVISOR_TOKEN` | Authentication token for Supervisor API (set automatically in HAOS/Supervised) |
| `SOFT_FILE_LIMIT` | Override the soft file descriptor limit |

### Validating Configuration

Before restarting, validate your configuration:

```bash
hass --script check_config
```

```text
Testing configuration at /config
Successful config (no errors)
```

> [!WARNING]
> Always validate configuration before restarting Home Assistant. Invalid YAML or missing required fields will prevent startup or trigger recovery mode.

For the complete configuration reference including all integration options, see the Admin Guide.

---

## 4. Core Usage

### Managing Integrations

Integrations connect Home Assistant to devices, services, and platforms. Most integrations are configured through the web UI.

**Adding an integration:**

1. Navigate to **Settings → Devices & Services**
2. Click **Add Integration**
3. Search for the integration name
4. Follow the setup wizard (config flow)

Many integrations are discovered automatically via SSDP, Bluetooth, mDNS/Zeroconf, DHCP, and USB protocols. When a compatible device is detected on your network, Home Assistant will prompt you to set it up.

**YAML-configured integrations** are added directly to `configuration.yaml`:

```yaml
sensor:
  - platform: time_date
    display_options:
      - time
      - date
```

### Automations

Automations are the core of home automation — they define rules that trigger actions based on conditions.

**Structure:** Every automation has three parts:

| Component | Purpose | Example |
|---|---|---|
| **Trigger** | What starts the automation | State change, time, event, device trigger |
| **Condition** | Optional filters that must be true | Time of day, entity state, zone |
| **Action** | What happens when triggered | Call service, send notification, delay |

**Creating an automation via the UI:**

1. Go to **Settings → Automations & Scenes → Create Automation**
2. Add triggers (what starts it)
3. Add conditions (optional filters)
4. Add actions (what to do)
5. Save and enable

**YAML automation example:**

```yaml
# automations.yaml
- id: "turn_on_porch_light_at_sunset"
  alias: "Turn on porch light at sunset"
  trigger:
    - trigger: sun
      event: sunset
      offset: "-00:30:00"
  condition:
    - condition: state
      entity_id: binary_sensor.someone_home
      state: "on"
  action:
    - action: light.turn_on
      target:
        entity_id: light.porch
      data:
        brightness_pct: 80
  mode: single
```

**Execution modes** control behavior when an automation triggers while already running:

| Mode | Behavior |
|---|---|
| `single` | Ignore new triggers while running (default) |
| `restart` | Stop current run and start fresh |
| `queued` | Queue new triggers (configurable `max` queue size) |
| `parallel` | Run multiple instances simultaneously (configurable `max`) |

> [!NOTE]
> Automations fire an `automation_triggered` event each time they run. Use **Settings → Automations → Traces** to debug execution history, including which conditions passed or failed.

### Scripts

Scripts are reusable sequences of actions that can be called as services. Unlike automations, scripts have no triggers or conditions — they run on demand.

```yaml
# scripts.yaml
good_morning:
  alias: "Good Morning"
  icon: mdi:weather-sunny
  description: "Morning routine: lights, music, coffee"
  mode: single
  sequence:
    - action: light.turn_on
      target:
        area_id: kitchen
      data:
        brightness_pct: 100
        color_temp_kelvin: 4000
    - action: media_player.play_media
      target:
        entity_id: media_player.kitchen_speaker
      data:
        media_content_id: "morning_playlist"
        media_content_type: "playlist"
    - delay: "00:00:05"
    - action: switch.turn_on
      target:
        entity_id: switch.coffee_maker
```

Scripts support the same execution modes as automations (single, restart, queued, parallel) and can accept input variables via the `fields` definition for service call parameters.

> [!TIP]
> Each script is automatically registered as a service (`script.turn_on`, `script.<script_name>`), making it callable from automations, other scripts, or the REST API.

### Template Entities

Template entities derive their state from Jinja2 template expressions, allowing you to create virtual sensors, switches, and other entities that combine data from multiple sources.

```yaml
template:
  - sensor:
      - name: "Average Indoor Temperature"
        unit_of_measurement: "°F"
        state: >
          {{ (states('sensor.living_room_temp') | float +
              states('sensor.bedroom_temp') | float) / 2 | round(1) }}
      - name: "Daylight Hours"
        unit_of_measurement: "hours"
        state: >
          {{ ((as_timestamp(state_attr('sun.sun', 'next_setting')) -
               as_timestamp(state_attr('sun.sun', 'next_rising'))) / 3600)
             | round(1) }}
  - binary_sensor:
      - name: "House Occupied"
        state: >
          {{ states.person | selectattr('state', 'eq', 'home') | list | count > 0 }}
```

Template entities support all major entity platforms: sensor, binary_sensor, switch, light, cover, fan, lock, number, select, alarm_control_panel, and weather.

### Scenes

Scenes capture a snapshot of entity states that can be restored on demand:

```yaml
# scenes.yaml
- name: "Movie Time"
  entities:
    light.living_room:
      state: "on"
      brightness: 50
      color_temp_kelvin: 2700
    light.ceiling:
      state: "off"
    media_player.tv:
      state: "on"
```

### Dashboards

Home Assistant uses Lovelace as its dashboard system. Dashboards are fully customizable through the UI or YAML and support cards for displaying entity states, controlling devices, and visualizing data.

Common card types include entities, gauge, history-graph, thermostat, media-control, map, weather-forecast, and button cards.

### Voice Assistants

Home Assistant integrates with voice assistants for hands-free control:

- **Alexa** — via the Alexa Smart Home Skill integration (cloud or local emulated Hue)
- **Google Home** — via Google Assistant integration or emulated Hue
- **Assist** — Home Assistant's built-in voice assistant pipeline with local speech-to-text and text-to-speech

> [!NOTE]
> The **Emulated Hue** integration (`emulated_hue`) lets Alexa and Google Home discover and control entities without cloud services. It emulates a Philips Hue bridge on your network (default port 8300) with support for lights, climate, covers, fans, media players, scenes, and scripts.

### MQTT

MQTT is a lightweight messaging protocol widely used in IoT. Home Assistant's MQTT integration provides:

- **Publish/subscribe** to MQTT topics
- **Auto-discovery** of MQTT devices (prefix: `homeassistant`)
- **Entity platforms** for all major domains (sensor, switch, light, climate, etc.)

```yaml
mqtt:
  broker: 192.168.1.100
  port: 1883
  username: mqtt_user
  password: !secret mqtt_password
  discovery: true
  discovery_prefix: homeassistant
```

**Publishing from an automation:**

```yaml
action:
  - action: mqtt.publish
    data:
      topic: "home/garage/door/set"
      payload: "OPEN"
      qos: 1
      retain: false
```

> [!WARNING]
> The `mqtt.dump` service subscribes to a topic and writes all messages to `mqtt_dump.txt` in the config directory. Use this for debugging only — it can generate large files quickly.

### REST API

Home Assistant exposes a REST API for external integrations and scripts. All API calls require a long-lived access token (create one at **Profile → Long-Lived Access Tokens**).

**Check API status:**

```bash
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8123/api/
```

```json
{"message": "API running."}
```

**Get all entity states:**

```bash
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8123/api/states
```

**Set an entity state:**

```bash
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state": "on", "attributes": {"brightness": 200}}' \
  http://localhost:8123/api/states/light.living_room
```

**Call a service:**

```bash
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "light.living_room"}' \
  http://localhost:8123/api/services/light/turn_on
```

**Render a template:**

```bash
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "The sun is {{ states(\"sun.sun\") }}"}' \
  http://localhost:8123/api/template
```

| Endpoint | Method | Auth | Description |
|---|---|---|---|
| `/api/` | GET | Token | API status check |
| `/api/config` | GET | Token | Full configuration |
| `/api/states` | GET | Token | All entity states |
| `/api/states/{entity_id}` | GET/POST/DELETE | Token | CRUD for entity state |
| `/api/events/{event_type}` | POST | Admin | Fire an event |
| `/api/services` | GET | Token | List all services |
| `/api/services/{domain}/{service}` | POST | Token | Call a service |
| `/api/template` | POST | Admin | Render a Jinja2 template |
| `/api/components` | GET | Token | List loaded components |
| `/api/error_log` | GET | Token | View error log |
| `/api/stream` | GET | Admin | Server-sent event stream |
| `/api/core/state` | GET | Token | Core state + recorder status |

---

## 5. Common Tasks

### Set Up Automatic Device Discovery

**Goal:** Let Home Assistant automatically find devices on your network.

**Prerequisites:** `default_config:` in your `configuration.yaml` (enables SSDP, Zeroconf, DHCP, USB, and Bluetooth discovery).

**Steps:**

1. Ensure your Home Assistant host is on the same network/VLAN as your devices
2. Navigate to **Settings → Devices & Services**
3. Check the **Discovered** section for automatically detected devices
4. Click **Configure** on a discovered device to set it up

**Verify:** Discovered devices appear in the **Discovered** card.

**If it fails:** Check that multicast traffic (mDNS, SSDP) is not blocked by your router or firewall. Some devices require UPnP to be enabled.

### Create a Blueprint-Based Automation

**Goal:** Use a community-shared automation blueprint to quickly create an automation.

**Steps:**

1. Go to **Settings → Automations & Scenes → Blueprints**
2. Click **Import Blueprint**
3. Paste the blueprint URL
4. Click **Preview** then **Import**
5. Click **Create Automation** on the imported blueprint
6. Fill in the required inputs (entities, values)
7. Save

**Verify:** The automation appears in your automation list and can be enabled/triggered.

**If it fails:** Check that all entities referenced in the blueprint inputs exist in your system.

### Set Up MQTT Discovery

**Goal:** Automatically create entities from MQTT devices that publish discovery messages.

**Prerequisites:** MQTT broker configured and connected.

**Steps:**

1. Ensure `discovery: true` in your MQTT config (this is the default)
2. Configure your MQTT device to publish discovery messages to `homeassistant/<component>/<node_id>/<object_id>/config`
3. The device will appear automatically in **Settings → Devices & Services → MQTT**

**Verify:** Entities appear under the MQTT integration and update their state.

**If it fails:** Use the `mqtt.dump` service to subscribe to `homeassistant/#` and verify discovery messages are being received.

### Integrate Alexa via Emulated Hue

**Goal:** Control Home Assistant devices with Alexa without a cloud account.

**Steps:**

1. Add to `configuration.yaml`:
   ```yaml
   emulated_hue:
     host_ip: 192.168.1.50
     listen_port: 80
     expose_by_default: true
     exposed_domains:
       - switch
       - light
       - media_player
       - fan
     type: alexa
   ```
2. Restart Home Assistant
3. On your Alexa device, say "Alexa, discover devices"
4. Wait for discovery to complete

**Verify:** Say "Alexa, turn on [device name]" to test control.

**If it fails:** Ensure port 80 is available (Alexa requires port 80 for local discovery). Check that the host IP is reachable from the Alexa device.

> [!WARNING]
> Emulated Hue for Alexa requires port 80. If another service is using port 80, you must reconfigure it or use the cloud-based Alexa Smart Home Skill instead.

### Back Up and Restore Configuration

**Goal:** Create a backup of your Home Assistant configuration and restore it if needed.

**Steps (backup):**

1. Go to **Settings → System → Backups**
2. Click **Create Backup**
3. Choose full or partial backup
4. Download the backup file for offsite storage

**Steps (restore):**

1. Place the backup file (`.tar`) in the config directory
2. Create a `.HA_RESTORE` JSON file with:
   ```json
   {"path": "/config/backup.tar", "password": null, "remove_after_restore": true, "restore_database": true, "restore_homeassistant": true}
   ```
3. Restart Home Assistant — it will detect the restore instruction and process it before boot

**Verify:** Home Assistant starts with the restored configuration.

**If it fails:** Check `.HA_RESTORE_RESULT` for error details. The restore instruction file is always removed after processing to prevent boot loops.

### Set Up Camera Streaming with go2rtc

**Goal:** Enable WebRTC streaming for camera entities.

**Prerequisites:** go2rtc integration (included by default with `default_config:`).

**Steps:**

1. The go2rtc server starts automatically when Home Assistant boots
2. Camera integrations that support streaming will automatically register their streams with go2rtc
3. Open a camera entity card in your dashboard — it will use WebRTC streaming by default

**Verify:** Camera feeds show low-latency video in the dashboard.

**If it fails:** Check that the go2rtc server is running (look for `go2rtc` in the logs). Ensure your browser supports WebRTC.

### Set Up Multi-Factor Authentication

**Goal:** Add an extra layer of security to user accounts.

**Steps:**

1. Go to **Profile** (click your user icon in the sidebar)
2. Under **Multi-factor Authentication Modules**, enable a module
3. Follow the setup wizard to configure your MFA device (e.g., TOTP authenticator app)
4. Scan the QR code with your authenticator app
5. Enter the verification code to confirm

**Verify:** On next login, you will be prompted for both password and MFA code.

> [!IMPORTANT]
> MFA sessions expire after 5 minutes. System-generated users (like the Supervisor user) cannot enable MFA.

### Set Up the MCP Server for AI Integration

**Goal:** Expose Home Assistant to AI/LLM tools via the Model Context Protocol.

**Steps:**

1. Go to **Settings → Devices & Services → Add Integration**
2. Search for **Model Context Protocol Server**
3. Select which LLM APIs to expose (default: Assist)
4. The MCP server endpoints become available at:
   - Streamable HTTP: `POST /api/mcp`
   - SSE (legacy): `GET /mcp_server/sse`

**Verify:** Connect an MCP-compatible AI tool to the endpoint with a valid access token.

### Monitor Startup Performance

**Goal:** Identify slow integrations that delay startup.

**Steps:**

1. Start Home Assistant with verbose logging: `hass --verbose`
2. Watch the logs for the startup watchdog messages (logged every 60 seconds during slow startups)
3. Check **Settings → System → Logs** after startup completes

Startup is divided into stages:
- **Stage 0:** Core infrastructure (logging, HTTP, frontend, recorder) — immediate
- **Stage 1:** Discovery services (Bluetooth, DHCP, SSDP, USB, cloud) — 120s timeout
- **Stage 2:** All user integrations — 300s timeout

**If it fails:** Integrations that exceed their stage timeout are loaded in the background. Check logs for `Setup of integration X is taking over X seconds`.

### Create a Configuration Package

**Goal:** Organize related configuration into a single file.

**Steps:**

1. Create a `packages/` directory in your config folder
2. Create a package file, e.g., `packages/garage.yaml`:
   ```yaml
   sensor:
     - platform: template
       sensors:
         garage_status:
           friendly_name: "Garage Status"
           value_template: "{{ states('cover.garage_door') }}"

   automation:
     - alias: "Close garage at night"
       trigger:
         - trigger: time
           at: "22:00:00"
       action:
         - action: cover.close_cover
           target:
             entity_id: cover.garage_door
   ```
3. Reference it in `configuration.yaml`:
   ```yaml
   homeassistant:
     packages:
       garage: !include packages/garage.yaml
   ```
4. Validate and restart

**Verify:** Entities and automations from the package appear in the UI.

### Set Up External Access

**Goal:** Access Home Assistant securely from outside your local network.

**Steps:**

1. Set your internal and external URLs in `configuration.yaml`:
   ```yaml
   homeassistant:
     internal_url: "http://homeassistant.local:8123"
     external_url: "https://home.example.com"
   ```
2. Configure port forwarding on your router (port 8123) or use a reverse proxy (Nginx, Traefik)
3. Set up SSL/TLS certificates for HTTPS
4. Restart Home Assistant

**Verify:** Access your instance from outside your network using the external URL.

> [!CAUTION]
> Never expose Home Assistant over the internet without HTTPS. Use strong passwords, enable MFA, and consider using Home Assistant Cloud (Nabu Casa) for a secure, zero-configuration remote access solution.

---

## 6. Troubleshooting

### Diagnostic Decision Tree

```text
Problem?
├── Can't access web UI
│   ├── Check if HA is running: ps aux | grep hass
│   ├── Check port: ss -tlnp | grep 8123
│   └── Check logs: tail -f CONFIG/home-assistant.log
├── Integration not loading
│   ├── Check Settings → System → Logs for errors
│   ├── Validate config: hass --script check_config
│   └── Try recovery mode: hass --recovery-mode
├── Automation not triggering
│   ├── Check automation is enabled
│   ├── Check automation traces for condition failures
│   └── Verify entity states match trigger conditions
├── Device not discovered
│   ├── Verify device is on the same network/VLAN
│   ├── Check that mDNS/SSDP/UPnP is not blocked
│   └── Try manual integration setup
└── Performance issues
    ├── Check recorder database size
    ├── Review integration count and polling intervals
    └── Check CPU/memory: Settings → System → Hardware
```

### Error: `ConfigEntryError: Invalid credentials`

**Cause:** Integration credentials (username, password, API key) are incorrect or expired.

**Solution:**
1. Go to **Settings → Devices & Services**
2. Find the affected integration
3. Click **Reconfigure** or **Re-authenticate**
4. Enter the correct credentials

**Prevention:** Use `secrets.yaml` for credentials and update them when they change.

### Error: `ConfigEntryNotReady: Error during setup`

**Cause:** The device or service required by the integration is temporarily unavailable.

**Solution:**
1. Verify the device/service is online and reachable
2. Check network connectivity between Home Assistant and the device
3. Home Assistant will automatically retry setup at increasing intervals

**Prevention:** Ensure devices have static IP addresses or reliable DHCP reservations.

### Error: `The go2rtc server version is not supported`

**Cause:** An external go2rtc instance is running an incompatible version.

**Solution:**
1. Update go2rtc to the recommended version (1.9.14 or later)
2. Or remove the external URL to use the built-in go2rtc server

**Prevention:** Keep external go2rtc installations updated alongside Home Assistant.

### Error: `Camera has no stream source`

**Cause:** The camera integration does not provide a streaming URL for go2rtc.

**Solution:**
1. Check if the camera integration supports streaming
2. Verify the camera is online and accessible
3. Some cameras require RTSP to be enabled in their settings

**Prevention:** Confirm camera streaming compatibility before purchase.

### Error: `Unknown auth provider`

**Cause:** The authentication configuration references a provider that is not loaded.

**Solution:**
1. Check `configuration.yaml` for `auth_providers:` configuration
2. Ensure the referenced provider type is valid
3. Remove or correct invalid provider references

**Prevention:** Use the default auth provider configuration unless you have specific needs.

### Error: `Credential is already linked to a user`

**Cause:** Attempting to link login credentials that are already associated with another user account.

**Solution:**
1. Use different credentials for the new user
2. Or unlink the credentials from the existing user first

**Prevention:** Each set of credentials can only be linked to one user.

### Error: `Value cannot be None` (in automation/script configuration)

**Cause:** A required field in the automation or script configuration is missing.

**Solution:**
1. Check the automation/script YAML for missing required fields
2. Validate configuration: `hass --script check_config`
3. Common missing fields: trigger type, action service, entity_id

**Prevention:** Use the UI editor for automations and scripts to ensure all required fields are populated.

### Error: `Duplicate X10 device` / `Duplicate override` (Insteon)

**Cause:** The Insteon configuration contains duplicate device entries.

**Solution:**
1. Review Insteon device configuration for duplicates
2. Remove the duplicate entry
3. Restart Home Assistant

**Prevention:** Check for existing entries before adding new Insteon device overrides.

### Error: `Not a valid app slug` (Supervisor)

**Cause:** An invalid add-on identifier was passed to a Supervisor service call.

**Solution:**
1. Verify the add-on slug matches an installed add-on
2. List available add-ons via **Settings → Add-ons**
3. Use the correct slug format (e.g., `core_mosquitto`)

**Prevention:** Copy add-on slugs from the Supervisor UI rather than typing them manually.

### Error: `Cannot create a backup with database but without Home Assistant`

**Cause:** Attempting to create a backup that includes the database but excludes the Home Assistant configuration.

**Solution:**
1. Include both Home Assistant and database in the backup
2. Or exclude the database if you only need configuration

**Prevention:** The database depends on the Home Assistant configuration; always back them up together.

### Error: `Error updating Home Assistant Core/OS/Supervisor`

**Cause:** The update process failed, typically due to network issues or insufficient storage.

**Solution:**
1. Check internet connectivity
2. Ensure sufficient disk space (at least 1 GB free)
3. Check Supervisor logs for detailed error messages
4. Retry the update

**Prevention:** Maintain adequate free disk space and stable network connectivity.

### Error: Recovery mode activates on startup

**Cause:** Configuration parsing failed, core setup failed, or a critical integration (like the frontend) failed to load.

**Solution:**
1. In recovery mode, only essential integrations are loaded
2. Access the web UI and check **Settings → System → Logs** for the root cause
3. Fix the configuration issue
4. Disable safe mode via the UI or delete the `.safe_mode` file from your config directory
5. Restart normally

**Prevention:** Always validate configuration changes before restarting.

> [!WARNING]
> Recovery mode starts with minimal integrations. Your devices and automations will not be available until you fix the underlying issue and restart normally.

### Error: `Backup failed: no backup_id`

**Cause:** The backup creation process failed to generate a valid backup identifier.

**Solution:**
1. Check available disk space
2. Review Supervisor logs for the underlying error
3. Retry the backup

**Prevention:** Ensure sufficient disk space before creating backups.

### Slow Startup Debugging

**Cause:** Integrations taking too long to initialize, often due to unreachable devices or slow network responses.

**Solution:**
1. Start with verbose logging: `hass --verbose`
2. Watch for "Setup of integration X is taking over Y seconds" messages
3. Identify integrations with slow or failing network connections
4. Consider removing or disabling problematic integrations temporarily
5. Check that local DNS resolution is working properly

**Prevention:** Use static IP addresses for critical devices. Ensure reliable network infrastructure.

---

## 7. FAQ

### General

**Q: What is the difference between Home Assistant OS, Supervised, Container, and Core?**

Home Assistant OS is the recommended all-in-one operating system image. Supervised installs the Supervisor on Debian Linux. Container runs Home Assistant in Docker without the Supervisor. Core is a bare Python virtual environment install without Supervisor or add-on support. All four run the same Home Assistant Core code — the difference is the management layer around it.

**Q: What Python version does Home Assistant require?**

Python 3.13 or higher. The exact minimum is defined in `homeassistant.const.REQUIRED_PYTHON_VER`.

**Q: Can I run Home Assistant on Windows?**

Only via Windows Subsystem for Linux (WSL). Native Windows is not supported. You can bypass the OS check with `--ignore-os-check` but this is unsupported.

**Q: Where are my configuration files stored?**

By default in `~/.homeassistant/` (Core install) or `/config/` (container/HAOS). You can specify a custom path with the `-c` / `--config` flag.

### Configuration

**Q: What does `default_config:` do?**

It enables a curated set of ~50 default integrations that most users want, including the frontend, automation engine, history, logbook, recorder, device discovery (SSDP, Zeroconf, DHCP, USB, Bluetooth), cloud connectivity, and more.

**Q: How do I split my configuration into multiple files?**

Use `!include` directives in `configuration.yaml` or the packages system. Packages are more flexible as they allow mixing multiple domains in a single file.

**Q: How do I check my configuration for errors?**

Run `hass --script check_config` from the command line, or use **Developer Tools → YAML → Check Configuration** in the web UI.

### Automations & Scripts

**Q: What is the difference between automations and scripts?**

Automations have triggers and conditions — they run automatically when conditions are met. Scripts are just action sequences — they only run when explicitly called as a service.

**Q: What are automation execution modes?**

`single` (default) ignores new triggers while running. `restart` cancels the current run and starts over. `queued` queues new triggers. `parallel` runs multiple instances simultaneously. Set via the `mode` key.

**Q: Can I use blueprints for scripts?**

Yes. Both automations and scripts support blueprints. Import blueprint URLs via the UI at **Settings → Automations & Scenes → Blueprints**.

**Q: How do I pass variables to a script?**

Define `fields` in the script configuration for UI support, then pass variables when calling the `script.turn_on` or `script.<name>` service.

### Integrations

**Q: How does automatic device discovery work?**

Home Assistant uses multiple discovery protocols: SSDP (UPnP devices), Zeroconf/mDNS (Apple/network devices), DHCP (MAC address matching), USB (device enumeration), and Bluetooth (BLE advertisements). Each integration registers matchers for these protocols, and when a match is found, a config flow is initiated.

**Q: How do I configure MQTT discovery?**

MQTT discovery is enabled by default (prefix: `homeassistant`). Devices publish a JSON config message to `homeassistant/<component>/<node_id>/<object_id>/config`. Home Assistant automatically creates the corresponding entities.

**Q: Can I use an external MQTT broker?**

Yes. Configure the broker address, port, and credentials in the MQTT integration config entry or YAML. Home Assistant supports TCP and WebSocket transports, TLS encryption, and client certificates.

### Authentication

**Q: How do access tokens work?**

Home Assistant uses JWT (JSON Web Token) authentication. Refresh tokens last 90 days and generate short-lived access tokens (30-minute expiry). Long-lived access tokens can be created in your user profile for API access and do not expire automatically.

**Q: What are the default user groups?**

Three groups exist by default: **Administrators** (full access), **Users** (standard entity access), and **Read Only** (view-only access). The owner account is always in the Administrators group and cannot be deactivated.

**Q: What is recovery mode?**

Recovery mode starts Home Assistant with only essential integrations loaded. It activates automatically when configuration parsing fails or a critical integration (like the frontend) fails to load. You can also start it manually with `hass --recovery-mode`.

### Performance

**Q: How do I reduce startup time?**

Identify slow integrations via verbose logging. Ensure devices have static IPs. Reduce the number of polling-based integrations. Use an SSD for the config directory and recorder database.

**Q: How do I manage the recorder database size?**

Configure the `recorder` integration to exclude entities, domains, or event types you do not need. Set a `purge_keep_days` value to automatically remove old data. The recorder uses SQLite in WAL mode by default.

---

_Generated May 2026 from home-assistant/core at 277daf2. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._