Home Assistant Nabu Casa Cloud Integration

2.2.0 · active · verified Wed Apr 15

hass-nabucasa is the official Python library that powers the Nabu Casa Cloud integration within Home Assistant Core. It provides functionality for remote access, voice assistant integrations (Alexa, Google Assistant), and other cloud services for Home Assistant instances. The current version is 2.2.0, requiring Python >=3.14. Its release cadence is tightly coupled with Home Assistant Core releases, generally receiving frequent updates.

Warnings

gotcha `hass-nabucasa` is an internal dependency of Home Assistant Core, not intended for direct standalone scripting by end-users. Attempting to import and use it outside a fully functional Home Assistant environment is generally unsupported and will likely lead to errors or unexpected behavior.
Fix: Interact with Nabu Casa Cloud services through Home Assistant's built-in `cloud:` integration configuration and its exposed services, rather than directly using this library.
breaking This library is tightly coupled with Home Assistant Core versions. Installing or upgrading `hass-nabucasa` independently of `homeassistant` can introduce breaking changes, compatibility issues, or lead to a non-functional cloud integration. Always ensure `hass-nabucasa` matches the expected version for your Home Assistant release, which typically means letting Home Assistant manage its dependencies.
Fix: Do not manually manage `hass-nabucasa` versions. Rely on Home Assistant's dependency management, or if running in a custom environment, ensure the `hass-nabucasa` version is compatible with your `homeassistant` version.
gotcha All configuration, including Nabu Casa Cloud subscription management and authentication for integrations like Alexa or Google Assistant, is handled entirely within Home Assistant's `cloud:` configuration. Direct programmatic access to cloud credentials or services via `hass-nabucasa`'s API is not exposed for external use.
Fix: Manage Nabu Casa Cloud settings and linked voice assistants through the Home Assistant UI or `configuration.yaml` file, not through direct interaction with this library's code.

Install

pip install hass-nabucasa Install hass-nabucasa

Imports

Cloud
```
from hass_nabucasa import Cloud
```
Primary class for Nabu Casa Cloud integration. Typically used internally by Home Assistant.
Alexa
```
from hass_nabucasa import Alexa
```
Class for Alexa integration. Typically used internally by Home Assistant.
GoogleAssistant
```
from hass_nabucasa import GoogleAssistant
```
Class for Google Assistant integration. Typically used internally by Home Assistant.

Quickstart

This quickstart demonstrates how the `Cloud` class from `hass-nabucasa` is instantiated, primarily to illustrate its internal nature. **This library is an internal dependency of Home Assistant Core and is not designed for direct standalone use.** The provided code uses mocks to simulate a Home Assistant environment for basic instantiation, but it will not provide any functional cloud connectivity or services. Users interact with Nabu Casa Cloud by configuring the `cloud:` component directly within their Home Assistant `configuration.yaml` or via the UI, which then internally utilizes this library.

import os
import asyncio
from unittest.mock import MagicMock
from hass_nabucasa import Cloud

# WARNING: This library is an internal dependency of Home Assistant Core.
# It is NOT designed for direct standalone use by end-user applications.
# The code below is HIGHLY conceptual and uses mocks to illustrate basic instantiation.
# It will NOT connect to Nabu Casa Cloud or provide any meaningful functionality
# outside of a fully operational Home Assistant environment.
# All configuration, authentication, and service interactions are managed by Home Assistant itself.

async def main():
    print("--- Conceptual hass-nabucasa usage demonstration ---")
    # In a real Home Assistant setup, 'hass' is the Home Assistant instance object.
    # We're mocking it here to make the code 'runnable' without a full HA environment.
    hass_mock = MagicMock()
    hass_mock.config.time_zone = 'UTC'
    hass_mock.config.latitude = 0.0
    hass_mock.config.longitude = 0.0
    hass_mock.config.internal_url = 'http://localhost:8123'
    hass_mock.config.external_url = os.environ.get('HA_EXTERNAL_URL', 'http://localhost:8123')
    hass_mock.data = {}
    hass_mock.loop = asyncio.get_running_loop()
    hass_mock.bus.async_listen = MagicMock()
    hass_mock.helpers.network.get_url = MagicMock(return_value=hass_mock.config.internal_url)
    hass_mock.helpers.aiohttp_client.async_get_clientsession = MagicMock()
    hass_mock.components.websocket_api.async_register_command = MagicMock()
    hass_mock.data.setdefault = MagicMock()

    print("Attempting to instantiate hass_nabucasa.Cloud with a mocked Home Assistant instance...")
    try:
        # Instantiating the Cloud class requires a 'hass' (Home Assistant) object.
        cloud_instance = Cloud(hass_mock)
        print(f"Successfully created a conceptual Cloud instance: {cloud_instance}")
        print("Remember: This instance is non-functional without a full HA context.")
        print("To use Nabu Casa Cloud, configure the 'cloud:' component in Home Assistant.")
    except Exception as e:
        print(f"Failed to instantiate Cloud: {e}")
        print("This often happens if essential Home Assistant dependencies/context are missing.")

if __name__ == "__main__":
    asyncio.run(main())

view raw JSON →