Home Assistant Core is the state engine inside a much larger home platform

01Read the repository at the correct layer

The home-assistant/core repository contains the Python application at the center of Home Assistant. Core communicates with devices and services, maintains entity state, exposes services, fires events, and evaluates automation-related behavior. It is not the whole product. The frontend, operating system, Supervisor, apps (formerly called add-ons), companion apps, and other parts of the experience are developed in separate repositories or services.

That boundary matters when evaluating an issue or license. A dashboard bug may live in the frontend. An app, formerly called an add-on, is another application managed by the surrounding system. A radio problem can involve firmware and hardware outside Core. Home Assistant's contributor architecture overview describes a stack in which, on Home Assistant OS, the Supervisor runs Core in a container next to apps, while users reach Core through the frontend, companion apps, voice, and other software. Trace a behavior through the actual component instead of assigning every visible result to this repository.

02State, events, and services are the basic grammar

An entity has a state and attributes at a point in time. State changes can produce events on the event bus. Services are callable actions exposed by integrations, such as turning on a light or setting a climate target. This grammar lets devices from different vendors participate in common interfaces even when their underlying protocols differ.

State is an observation, not always authoritative device truth. A cloud integration can be stale, a battery device can sleep, and an optimistic command may appear successful before physical confirmation. Automations should handle unknown and unavailable values and avoid assuming every state transition represents a human action. Attributes are not a stable dumping ground for arbitrary history. Use the recorder and long-term statistics according to supported data models rather than building logic around incidental internal event fields.

03Integrations translate messy devices into a shared model

Integrations connect Home Assistant to protocols, vendor APIs, hardware, and software services. A config entry stores an integration instance created through the user interface, while devices and entities represent discovered or configured objects. Entity platforms map domain behavior such as light, sensor, switch, media player, or climate into common properties and services. The integration quality scale documents expectations for maintainers.

No abstraction can make every device equally capable. One light may expose color temperature locally, another only cloud power control, and a third may poll slowly. Read integration documentation for prerequisites, supported features, known limitations, and whether communication is local or cloud-based. Keep entity IDs stable after naming because dashboards and automations reference them. Disable noisy or unused entities rather than collecting every diagnostic value forever, but retain the ones needed to explain device failure.

• Prefer documented local integrations when they meet the device requirement.
• Record which entities and services are guaranteed by each critical device path.
• Treat entity renaming and integration reload as changes that can break automations.

04The asynchronous core makes blocking code a system concern

Home Assistant Core uses Python's asynchronous model to coordinate many integrations and I/O operations. Async code can wait for network or device activity without dedicating one thread per integration. Work that blocks the event loop can delay unrelated state updates and automation reactions, so developer guidance distinguishes async libraries, executor work, and safe callbacks.

Integration authors must also manage setup, unload, retries, rate limits, and coordinator updates without creating polling storms. A library that appears harmless in a standalone script can block DNS, file access, or device calls inside Core. Users feel the combined result as a slow interface or missed timing. Profiling and official repair diagnostics are preferable to increasing hardware blindly. Custom components need the same async discipline as built-in integrations but may not receive equivalent review.

05Automations are event-driven programs in a physical environment

An automation combines triggers, optional conditions, and actions. Scripts package action sequences, scenes describe desired entity states, and helpers provide user-managed state for coordination. Execution modes determine what happens when a new trigger arrives while an earlier run is active. These tools can express useful behavior without a separate application service, and traces help explain why a run took a branch.

Physical systems add ambiguity. Motion can chatter, a door sensor can become unavailable, and a light can be changed manually while an automation waits. Add debounce or time conditions where justified, choose restart or queued modes from the intended behavior, and make destructive actions require stronger evidence. Avoid circular automations that react to one another's state changes. Every critical automation needs a manual override and a safe outcome after restart, network loss, or a device that never confirms the command.

06Local control improves privacy only when the full path is local

Home Assistant emphasizes local control, and many integrations communicate directly with devices on the home network. Local execution can keep automations working during an internet outage and reduce data sent to vendor clouds. Core's source is inspectable, and self-hosting gives the household direct custody of configuration, history, and credentials.

A local server can still call cloud APIs, load remote media, expose a remote endpoint, or send notifications through external services. Device firmware may contact its manufacturer independently. Review each integration's data path and create network rules that match the expected behavior. Secure remote access with TLS and strong authentication, enable multi-factor protection where supported, and do not forward the raw service port casually from a home router. Privacy is a property of every dependency, not the location of one process.

07The supported installation story changed

The phrase Home Assistant Core previously also named an installation method that ran the Python application in a manually managed environment. Home Assistant deprecated that Core method and the Supervised method in release 2025.6, then ended support after release 2025.12. The project said those methods would remain technically possible for development but would no longer receive end-user support. Old virtual-environment tutorials are therefore poor production guidance.

Current official choices are Home Assistant OS and Home Assistant Container. OS provides the appliance-like full stack, including Supervisor-managed capabilities and apps (formerly called add-ons). Container runs Core in a container and gives the operator more host responsibility without the Supervisor and its app management. Choose through the current installation documentation, not the repository README alone. A developer checkout of home-assistant/core is appropriate for contribution and testing; it is not evidence that a household deployment follows a supported method.

08Custom integrations expand capability and trusted code

Built-in integrations pass project contribution and review processes, although defects remain possible. Custom integrations installed from outside Core can access Home Assistant data, credentials available to them, local networks, and the Python process. They may lag releases or use internal APIs that change. The convenience of solving one unsupported device can create a permanent upgrade dependency.

Inventory custom components, read their source and issue history, pin or stage updates, and remove those without an active owner. Back up before Core upgrades and use safe mode or logs to distinguish a custom failure from a core regression. Apply the same caution to blueprints, apps, and copied YAML, while remembering they execute in different layers. Never paste long-lived tokens into forum posts or public diagnostics. Redaction should be verified, not assumed from a friendly export button.

09Household reliability is an operations practice

A home platform becomes infrastructure when heating, access, alerts, or accessibility depend on it. Keep automatic and manual backups, copy them off the device, and test restoration onto spare or virtual hardware. Watch storage wear, recorder database growth, integration errors, radio coordinator health, and network dependencies. Update regularly but preserve a rollback window and read breaking changes for critical integrations.

The Core repository is Apache-2.0 licensed. That license does not automatically cover device firmware, vendor APIs, apps, custom components, frontend assets, companion apps, or Home Assistant Cloud terms. Review adjacent components separately. The strongest deployment keeps essential physical controls usable without the server, documents recovery for another household member, and favors boring supported hardware. A clever automation is not resilient if nobody can turn on the light during a failed restore.