{"id":7909,"library":"aiohasupervisor","title":"Asynchronous Home Assistant Supervisor Client","description":"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.","status":"active","version":"0.4.3","language":"en","source_language":"en","source_url":"https://github.com/home-assistant-libs/python-supervisor-client","tags":["home-assistant","supervisor","async","client","api"],"install":[{"cmd":"pip install aiohasupervisor","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"Main client class for interacting with the Supervisor API.","symbol":"Client","correct":"from aiohasupervisor.client import Client"},{"note":"Specific exception for Supervisor API timeouts.","symbol":"SupervisorTimeoutError","correct":"from aiohasupervisor.exceptions import SupervisorTimeoutError"},{"note":"Specific exception for Supervisor API bad requests.","symbol":"SupervisorBadRequestError","correct":"from aiohasupervisor.exceptions import SupervisorBadRequestError"},{"note":"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.","wrong":"from aiohasupervisor.models import IngressPanel (if running HA Core 2026.4+ in venv without Supervisor)","symbol":"IngressPanel","correct":"from aiohasupervisor.models import IngressPanel"}],"quickstart":{"code":"import asyncio\nimport os\nfrom aiohasupervisor.client import Client\n\nasync def get_supervisor_info():\n    # The SUPERVISOR_TOKEN environment variable is automatically set for Home Assistant add-ons.\n    # For remote development/testing, use the remote_api add-on to get a token and set SUPERVISOR_API_URL.\n    supervisor_token = os.environ.get('SUPERVISOR_TOKEN', 'YOUR_SUPERVISOR_TOKEN')\n    supervisor_api_url = os.environ.get('SUPERVISOR_API_URL', 'http://supervisor/core') # Default for add-ons\n\n    if supervisor_token == 'YOUR_SUPERVISOR_TOKEN':\n        print(\"Warning: SUPERVISOR_TOKEN not set. This example may not work without a valid token.\")\n        print(\"Please refer to the aiohasupervisor GitHub for development setup with remote_api add-on.\")\n        return\n\n    async with Client(supervisor_api_url, supervisor_token) as client:\n        try:\n            info = await client.info()\n            print(\"Supervisor Info:\", info)\n        except Exception as e:\n            print(f\"Error fetching Supervisor info: {e}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(get_supervisor_info())\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"aiohasupervisor versions used by Home Assistant Core 2026.4+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"deprecated","affected_versions":"Prior to 0.3.x, specifically 0.2.2b5 and related pre-releases."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"aiohasupervisor.exceptions.SupervisorTimeoutError: Timeout connecting to Supervisor"},{"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.","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.","error":"AttributeError: module 'aiohasupervisor.models' has no attribute 'IngressPanel'"},{"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.","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.","error":"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"}]}