Asynchronous Home Assistant Supervisor Client

0.4.3 · active · verified Thu Apr 16

aiohasupervisor is an asynchronous Python client designed for interfacing with the Home Assistant Supervisor's REST API. It is currently at version 0.4.3 and is actively maintained, with a release cadence tied to the development and releases of Home Assistant itself, as it's primarily used within the Home Assistant ecosystem, particularly by its Supervisor integration and add-ons.

Common errors

```
aiohasupervisor.exceptions.SupervisorTimeoutError: Timeout connecting to Supervisor
```
cause The client could not establish a connection or receive a response from the Home Assistant Supervisor within the allotted time. This can be due to network issues, an overloaded Supervisor, incorrect `SUPERVISOR_API_URL`, or an unavailable Supervisor instance.

fix Verify network connectivity to the Home Assistant Supervisor. Check the `SUPERVISOR_API_URL` environment variable if configured. Ensure the Home Assistant Supervisor is running and responsive. Increase the client's timeout if necessary, though this typically points to an underlying connectivity or performance issue.
```
AttributeError: module 'aiohasupervisor.models' has no attribute 'IngressPanel'
```
cause Attempting to import `IngressPanel` from `aiohasupervisor.models` in newer versions of the library, especially when Home Assistant Core is run in a venv without Supervisor, as the `hassio` integration might still attempt this import.

fix If developing a custom component or modifying Home Assistant Core in a venv, consider adding a try-except block around the `IngressPanel` import. Alternatively, creating an empty `custom_component/hassio/__init__.py` can prevent the problematic `hassio` integration bootstrap.
```
aiohasupervisor.exceptions.SupervisorBadRequestError: Update of Supervisor failed: Can't install ghcr.io/home-assistant/...: 500 Server Error for http+docker://localhost/v1.47/images/create?tag=...: Internal Server Error
```
cause This error often occurs during Supervisor updates and can be related to issues with the Docker daemon, image pulls from `ghcr.io` (e.g., rate limits), or an internal Supervisor error during the update process.

fix Reboot the host machine or at least the Home Assistant Supervisor. Check Supervisor logs for more specific errors. If related to `ghcr.io` rate limits, waiting and retrying may resolve the issue.

Warnings

breaking The `IngressPanel` class was removed from `aiohasupervisor.models`. Home Assistant Core installations (especially venv) starting from 2026.4 might fail to start if they incorrectly try to import this class via the `hassio` integration.
Fix: For Home Assistant Core venv installations, either modify `addon_panel.py` to handle the `IngressPanel` import gracefully (e.g., with a try-except block) or create an empty `custom_component/hassio/__init__.py` to prevent the `hassio` integration from loading.
gotcha The library heavily relies on `SUPERVISOR_TOKEN` and optionally `SUPERVISOR_API_URL` environment variables for authentication and endpoint discovery. Without these, the client cannot connect to the Home Assistant Supervisor.
Fix: Ensure `SUPERVISOR_TOKEN` is set (automatically in add-ons, manually from `remote_api` for development). For remote access, set `SUPERVISOR_API_URL` to your Home Assistant instance's IP.
deprecated Older versions of `aiohasupervisor` (e.g., 0.2.2b5) were sometimes included as pre-release dependencies in Home Assistant Core, causing issues with dependency resolvers like `uv`.
Fix: Ensure `aiohasupervisor` is updated to a stable release version. If encountering resolution issues with Home Assistant Core, try using `--prerelease=allow` with your package manager as a temporary workaround, though a proper fix involves stable dependency versions.

Install

pip install aiohasupervisor Install with pip

Imports

Client
```
from aiohasupervisor.client import Client
```
Main client class for interacting with the Supervisor API.
SupervisorTimeoutError
```
from aiohasupervisor.exceptions import SupervisorTimeoutError
```
Specific exception for Supervisor API timeouts.
SupervisorBadRequestError
```
from aiohasupervisor.exceptions import SupervisorBadRequestError
```
Specific exception for Supervisor API bad requests.
IngressPanel
wrong:
```
from aiohasupervisor.models import IngressPanel (if running HA Core 2026.4+ in venv without Supervisor)
```
correct:
```
from aiohasupervisor.models import IngressPanel
```
The `IngressPanel` class was removed in recent versions of `aiohasupervisor`. Importing it can cause `AttributeError` or `ImportError` if the environment is Home Assistant Core 2026.4+ in a venv without Supervisor, as the `hassio` integration incorrectly tries to load it.

Quickstart

This quickstart demonstrates how to initialize the `aiohasupervisor` client and fetch basic supervisor information. It expects the `SUPERVISOR_TOKEN` environment variable to be set, which is automatically handled when running as a Home Assistant add-on. For external development, the `SUPERVISOR_API_URL` should also be set, and a token obtained from the `remote_api` add-on.

import asyncio
import os
from aiohasupervisor.client import Client

async def get_supervisor_info():
    # The SUPERVISOR_TOKEN environment variable is automatically set for Home Assistant add-ons.
    # For remote development/testing, use the remote_api add-on to get a token and set SUPERVISOR_API_URL.
    supervisor_token = os.environ.get('SUPERVISOR_TOKEN', 'YOUR_SUPERVISOR_TOKEN')
    supervisor_api_url = os.environ.get('SUPERVISOR_API_URL', 'http://supervisor/core') # Default for add-ons

    if supervisor_token == 'YOUR_SUPERVISOR_TOKEN':
        print("Warning: SUPERVISOR_TOKEN not set. This example may not work without a valid token.")
        print("Please refer to the aiohasupervisor GitHub for development setup with remote_api add-on.")
        return

    async with Client(supervisor_api_url, supervisor_token) as client:
        try:
            info = await client.info()
            print("Supervisor Info:", info)
        except Exception as e:
            print(f"Error fetching Supervisor info: {e}")

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

view raw JSON →