Connects this Home Assistant instance to Willo — no port forwarding, no HTTPS certificate, no static IP. This integration opens one outbound connection to Willo's backend and keeps it open; the Willo app never talks to Home Assistant directly.
- Add this repository to HACS as a custom repository
(category: Integration), or copy
custom_components/willointo your Home Assistant's owncustom_components/folder. - Restart Home Assistant.
- Settings → Devices & Services → Add Integration → Willo.
- In the Willo app, create a home and generate a pairing code.
- Enter that code here. Done — no URL, no OAuth, nothing else to configure.
- Sends Willo a snapshot of your
light,fan,sensor, andcameraentities on connect, and pushes an update the moment any of them change. - Executes commands Willo sends back (turn on/off, set brightness, set fan speed) via Home Assistant's own service-call API — nothing here talks to a device directly; Home Assistant still does.
- Reconnects automatically if the connection drops (a router reboot, a brief outage) — no user action needed.
Pure Python, no relation to the Willo web app's own toolchain (that lives in
OxyHQ/Willo). See
custom_components/willo/__init__.py's module doc comment for the wire
protocol this speaks to Willo's backend
(packages/backend/src/realtime/tunnelNamespace.ts in that repo).
Run the integration's own tests (pytest-homeassistant-custom-component,
which spins up a real, minimal in-process HomeAssistant instance per test
— not a mock of HA itself):
pip install pytest-homeassistant-custom-component
pip install "python-socketio[asyncio_client]>=5.11,<6" "PyTurboJPEG==1.8.0" # this integration's own manifest requirements
pytest tests/
OxyHQ/Willo issue #9 adds a
second way to get onto a Willo home: instead of a person going through
Home Assistant's own onboarding wizard and typing a pairing code, a
factory-provisioned Home Assistant Green boots straight into a
Willo-branded status screen (willo-claim-ui/, a small Vite app) driven by
a persistent on-device process (orchestrator/) that:
- serves the built claim UI + a local
GET /status, bound to a real network interface (WILLO_HOST,0.0.0.0by default) — independent of anything below, see "Cleanup deletion" for why that independence matters - polls Core's REST API until it's up
- completes onboarding's "user" step (the only one that needs no pre-existing auth) to get an admin token
- writes
configuration.yaml's explicit integration allow-list + loopback-onlyhttp:binding if it doesn't already match, and — only if it changed — restarts Core and resumes once it's back up - drives the rest of HA's onboarding REST API (core_config/analytics/ integration steps)
- replaces the installed
frontendcomponent with an inert stub (defense-in-depth on top of the loopback binding; see "Inert frontend stub" below). It no longer deletesanalytics/cloud; see the update note at the top of "Cleanup deletion". - calls the real Willo backend's
POST /tunnel/claim/GET /tunnel/claim/status, falling back to a clearly-logged local mock if that backend isn't reachable - writes the
willoconfig entry directly into.storage/core.config_entriesand restarts Core GET /statusreflects every one of these stages live:onboarding → syncing → awaiting-pairing → paired(or, on a device that already has real, hand-authored configuration — see "Existing- install safety fix" below —existing-installinstead, with none of steps 2b-8 above ever running) — and separately, as soon as it's known (not gated behind onboarding), adeviceModelfield ("Green", "Yellow",nulloff-Supervisor) the Willo app's own auto-detect screen reads directly, without this orchestrator's own claim UI ever displaying it — seedevice_model.pyand the open items below for what's verified and what still needs real HAOS hardware
Run it locally:
cd willo-claim-ui && bun install && bun run build # produces dist/, which the orchestrator serves
cd ../orchestrator && pip install -e . && pip install -e ".[test]"
pytest tests/
WILLO_HA_BASE_URL=http://localhost:8123 \
WILLO_HA_CONFIG_DIR=/path/to/a/fresh/unonboarded/ha/config \
WILLO_STATIC_DIR=../willo-claim-ui/dist \
WILLO_PORT=8080 \
python -m willo_orchestrator.main
Everything below was tested against a real, local Home Assistant Core
2026.2.3, installed with pip install homeassistant==2026.2.3 into a
disposable Python 3.13 venv (no Docker available in the sandbox this was
built in) — never against real Home Assistant Green / HAOS hardware, and
never against the user's own home network. That distinction matters for
the two open items at the very end of this section.
Cleanup deletion — frontend is intentionally never deleted, and
configuration.yaml alone cannot hide it either. Read this before
touching orchestrator/willo_orchestrator/cleanup.py.
Update (2026-10): the
analytics/clouddeletion is gone, from both the integration and the orchestrator. Checked against HA 2026.9.4'sbootstrap.py, Core only setscloudup when the configuration or a dependency asks for it (STAGE_1_INTEGRATIONS & all_domains). Willo Local's explicit allow-list never asks for it, so it never loads.analyticsis inDEFAULT_INTEGRATIONS, so it always loads, but with the empty preferences the onboarding analytics step leaves, it sends nothing. So the deletion bought nothing, and on a normal install it is destructive:default_confighard-depends oncloud, which takes history, logbook, energy, bluetooth and stream down with it. Thewillointegration now never modifies the Home Assistant installation it runs in, because it also runs on people's own instances.tests/test_setup_leaves_ha_alone.pyguards that. The history below is kept for context.
This went through three real, tested iterations, in this order:
- Delete
frontend/analytics/cloud, every boot (the plan as originally written). Every other stock component that importsfrontend/analytics/cloudat module level was found by grepping the installed package:config,history,logbook,lovelace,hassio,mobile_app,my,panel_custom,calendar,energy,media_source,todo(all importfrontend);mobile_app,netatmo,owntracks,plaato,rachio,toon,withings,loqed,overseerrimportcloud(but onlyhttp's reference is a deferred/lazy import,# noqa: PLC0415, not a hard dependency — the rest are third-party integrations never loaded unless configured);esphome/wledimportanalytics(component-specific, not force-loaded). Far more importantly:homeassistant/bootstrap.pyitself unconditionally importsconfigat the top of the file (from .components import (... config as config_pre_import ...), a performance pre-import that runs regardless ofconfiguration.yaml), andhomeassistant/components/config/__init__.pydoesfrom homeassistant.components import frontendat ITS top level. Deletingfrontendtherefore does not just risk a "some panel doesn't register" failure inside a running Core — it makes thehassprocess itself fail to start, withImportError: cannot import name 'frontend' from 'homeassistant.components', before bootstrap's own error handling or recovery-mode logic can even run. Proven twice: by deletingfrontendand relaunchinghassdirectly, and through the real orchestrator + integration pipeline (a full onboarding → cleanup → claim → pair → restart run deletedfrontend, wrote a real config entry, called the realhomeassistant.restartservice, and the nexthasslaunch on that same config directory crashed with the identical traceback). Rejected — reverted. - Stop deleting
frontend; instead exclude it from an explicitconfiguration.yamlcomponent list (nodefault_config:, nofrontend:key). This does NOT achieve the goal either, and does not even reduce exposure:bootstrap.py's_get_domains()unconditionally doesdomains.update(DEFAULT_INTEGRATIONS)for every non-recovery-mode boot, andDEFAULT_INTEGRATIONSincludes"frontend"— so it is force-loaded and force-set-up regardless of whatconfiguration.yamlsays. Recovery mode doesn't help either:DEFAULT_INTEGRATIONS_RECOVERY_MODE = {"frontend"}force-includes it there too, andrecovery_modeisn't even aconfiguration.yamlkey — it's CLI-only (--recovery-mode) or triggered by bootstrap failure. Proven live: booted HA with an explicitconfiguration.yaml(homeassistant:,api:,config:,http:— nofrontend:anywhere, nodefault_config:) andfrontend's files fully intact on disk, thencurl -i http://localhost:8123/→HTTP/1.1 302 Found,location: /onboarding.html;curl http://localhost:8123/onboarding.htmlreturned real HA-branded HTML (<title>Home Assistant</title>,<ha-onboarding>); an authenticatedGET /api/configconfirmed"frontend" in componentsistrue. Does not work — do not rely onconfiguration.yamlalone to hidefrontend. - Stop deleting
analytics/cloudfrom being the whole story too — restrict Core's ownhttp:to loopback only. Sincefrontendcannot be deleted (crashes reboot) or hidden via config (still force-loaded), the only verified way to make it actually unreachable from outside the device is network-level:http: { server_host: 127.0.0.1 }inconfiguration.yaml. Proven live: with that key set,ss -ltnpshowed Core bound to127.0.0.1:8123only (not0.0.0.0:8123/*:8123), so no other host on the network can reach it at all — whilecurl http://127.0.0.1:8123/from the same device still worked (302), meaning the orchestrator (which runs on the same device) is unaffected. This is the mechanism actually implemented — see "Loopback binding" below for the full wiring and the real non-loopback reachability proof.
analytics is separately force-attempted on every boot regardless of
configuration.yaml, same mechanism as frontend (DEFAULT_INTEGRATIONS
includes it too, commented # Needed for onboarding in HA's own source,
and /api/onboarding/core_config's real handler does await async_setup_component(hass, "analytics", {}) as a fallback). Unlike
frontend, analytics is NOT in CRITICAL_INTEGRATIONS, so a missing
analytics directory only produces one ERROR (MainThread) [homeassistant.setup] Setup failed for 'analytics' log line and does not
crash Core or trigger recovery mode — confirmed by booting repeatedly with
analytics+cloud deleted and frontend intact, which came up
completely healthy every time (see "Re-verification" below for the exact
repeated-boot run). cloud is not in DEFAULT_INTEGRATIONS at all and is
only pulled in if explicitly configured, or (on real Supervisor) as a
dependency of hassio — checked, hassio's manifest only depends on
http/repairs, not cloud.
Net, current state (2026-10): nothing deletes analytics, cloud
or frontend any more (see the update note at the top of this section).
The willo integration never touches the Home Assistant install. Only
the orchestrator, on a fresh Willo Local device, swaps frontend for an
inert stub; every failure there is caught and logged, never raised.
Reachability is handled separately, at the network level — see below.
Loopback binding — the implemented, verified mechanism for "no HA UI ever reachable from outside this device"
orchestrator/willo_orchestrator/ha_config.py's ensure_explicit_configuration
writes a fixed configuration.yaml (explicit api:/config:/http:
allow-list, never default_config:, http: { server_port: 8123, server_host: 127.0.0.1 }) and reports whether it changed anything.
main.py's boot sequence calls it right after onboarding's "user" step
(the only step that needs no pre-existing auth — a factory-fresh device
has no admin account before it), and only restarts Core if the file
actually changed, resuming the rest of onboarding once Core is back up.
orchestrator/willo_orchestrator/server.py's own HTTP server is entirely
separate — bound to WILLO_HOST (0.0.0.0 by default), never touched by
anything in ha_config.py.
Verified for real, both halves of the claim, from a genuinely
non-loopback address — not just 127.0.0.1, which would be trivial and
prove nothing:
$ ss -ltnp | grep -E "8123|8098"
LISTEN 0 128 0.0.0.0:8098 0.0.0.0:* users:(("python3",pid=...)) # orchestrator
LISTEN 0 128 127.0.0.1:8123 0.0.0.0:* users:(("hass",pid=...)) # Core
$ curl -m5 http://192.168.8.50:8123/ # Core, via the sandbox machine's real LAN IP
curl: (7) Failed to connect to 192.168.8.50 port 8123 after 0 ms: Could not connect to server
$ curl -m5 -o /dev/null -w '%{http_code}\n' http://192.168.8.50:8098/status # orchestrator, same IP
200
$ curl -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8123/ # Core, loopback — still works
200
192.168.8.50 is this sandbox machine's own eth0 address (confirmed via
ip addr / hostname -I) — not a second physical host, since none was
available, but connecting to a box's own non-loopback interface address
exercises the identical kernel socket-accept path a genuinely remote host
would: a listen() socket bound to 127.0.0.1 refuses every inbound
connection that doesn't arrive via the loopback interface, regardless of
where the connecting process physically runs. curl: (7) ... Could not connect is a real, OS-level connection refusal, not an HTTP-level
response of any kind — there is no 404, no panel, nothing "frontend-
shaped" to see, exactly the standard the coordinator asked this be held
to.
Sequencing caveat, found and worth knowing: the mid-onboarding
restart (step 4 above) was first tested starting from a default_config:
initial file (simulating "whatever a naive auto-generated config might
look like"), and Core hung for several minutes without ever completing
that restart — no crash, no ImportError, just no progress (low but
nonzero CPU use, nothing in the log past a homeassistant.loader. IntegrationNotFound: Integration 'cloud' not found error from what looks
like a leftover discovery/flow-init task from default_config:'s much
larger component set). Re-tested starting from an already-explicit-list
file (just missing server_host) — the realistic case, since a real
Willo Local device should ship with the explicit list baked into its
image from the start, never default_config: — and the restart completed
in about 3 seconds, every time. Not chased further: it's a plausible real
robustness gap (an unbounded initial configuration.yaml state could in
principle hang a real device's first boot) but not the scenario this
orchestrator is actually designed to run into, and chasing a synthetic
default_config:-specific hang felt like solving a problem this design
doesn't actually have. Worth remembering if a future change makes this
restart path reachable from a less-controlled starting state.
Loopback binding alone satisfies "no HA UI ever reachable from outside
this device" — that's the load-bearing guarantee. But the user wanted the
actual footprint gone where practical, not merely hidden behind a network
restriction, so orchestrator/willo_orchestrator/frontend_stub.py (until
2026-10 also duplicated in custom_components/willo/; the integration no
longer touches the HA install, see the update note under "Cleanup
deletion") replaces the installed frontend component's files with an inert
stub: same importable module path, same symbols other stock code needs,
but async_setup, async_register_built_in_panel, async_remove_panel,
and async_system_store all do nothing real — no HTTP views, no static
assets, no wizard, no dashboard.
The complete, exhaustive symbol list this stub needed to reproduce,
found by grepping the entire installed homeassistant==2026.2.3 package
for every from homeassistant.components import frontend and
from homeassistant.components.frontend import X, then every
frontend. attribute access in each matching file:
DATA_PANELS(aHassKey, read/written bylovelace/__init__.py,lovelace/dashboard.py)MANIFEST_JSON(subscript-only,mobile_app/webhook.py)async_register_built_in_panel(called byconfig,hassio,history,logbook,lovelace,my,todo,panel_custom,media_source,energy,calendar— same signature reproduced exactly, including the keyword-onlyupdate/config_panel_domainparams some call sites use)async_remove_panel(hassio/addon_panel.py,lovelace/__init__.py)async_system_store(lovelace/__init__.py— only reached inside a storage-migration function that early-returns on any fresh install with no pre-existing lovelace storage; stubbed anyway, defensively)- the
"frontend.reload_themes"service (referenced by name, not import, fromhomeassistant's ownreload_allservice)
Confirmed onboarding (what this orchestrator's own automation depends
on entirely) has zero references to frontend anywhere in its source or
manifest — the stub cannot break onboarding automation because nothing
about onboarding touches frontend in the first place.
Verified for real, both in isolation and through the full pipeline:
- Manual swap into a real installed package, 5 consecutive
hassrelaunches: every boot healthy, zero crashes, zeroImportError.frontendreports as a genuinely loaded component ("frontend" in components→truevia authenticatedGET /api/config) — not missing, just inert. - With Core's
http:deliberately NOT loopback-restricted for this one check (to isolate "is frontend inert" from "is it unreachable" — two different guarantees):GET /,GET /onboarding.html,GET /manifest.json,GET /static/icons/favicon.icoall returned a plain generic404: Not Found— nothing "frontend-shaped" served at all. - Full onboarding → user step → config write+restart → remaining
onboarding → analytics/cloud deletion and frontend stub swap →
claim → headless entry write → final restart → paired, re-run through
the real orchestrator with both mechanisms wired in together, reaching
pairedcleanly (orchestrator log shows all three:deleted stock 'analytics',deleted stock 'cloud',replaced the 'frontend' component with an inert stub). - 5 more consecutive
hassrelaunches on that resulting paired, loopback-bound, stub-frontend config directory, each cycle checked independently (distinct PID per cycle, confirmed killed before the next): all healthy, and on every single cycle — bothcurl http://192.168.8.50:8123/(external) refused the connection ANDcurl http://127.0.0.1:8123/(loopback, i.e. what the stub alone controls) returned404— the two layers holding simultaneously, every time.
Fragility, flagged as plainly as asked: frontend's internals are
not a documented, stable public API — frontend is an
integration_type: system component, and nothing about DATA_PANELS's
type, async_register_built_in_panel's signature, or which symbols exist
at all is guaranteed across HA releases the way http: server_host (a
real, documented, user-facing config key) is. This symbol list is only as
correct as the HA 2026.2.3 snapshot it was derived from. The most likely
failure mode on a future HA version that adds a new stock component
importing a new frontend symbol is that ONE component logging a soft
"Setup failed for X" error — the same category of degradation already
accepted for the analytics/cloud deletion — not a repeat of the
frontend-deletion crash, since nothing about bootstrap.py's own hard
import of config (which only needs frontend to exist and expose what
config/__init__.py touches) changes. Still: this is measurably more
fragile than loopback binding, and re-deriving this symbol list (same
grep commands as above) is a real, recurring maintenance cost on every
future HA version bump this project targets — worth budgeting for, not
a one-time cost. Both stub-writing functions are wrapped in their own
try/except, entirely separate from the analytics/cloud deletion's: if
writing or swapping the stub fails for any reason, or a future HA version
makes the stub itself incompatible in some way that surfaces as an
exception, the fallback is exactly "as if this stub didn't exist" —
loopback binding remains the load-bearing, unaffected guarantee either
way.
All of the below is a second, independent pass, done after the finding above and reported precisely rather than assumed:
- Full pipeline with the corrected cleanup step: a fresh, never-
onboarded HA Core instance was driven through the real orchestrator —
onboarding →
analytics/clouddeletion (frontendnever touched) → mock claim (forced viaWILLO_CLAIM_URLpointing at an unreachable address, the same legitimate env-var override used for the real backend URL, since completing a real claim needs a live Willo-app owner) → headless entry write →homeassistant.restartservice call.GET /statuswas polled live throughout and showedonboarding → syncing → awaiting-pairing → paired, same as before the fix. The orchestrator's own log shows exactly two deletions (deleted stock 'analytics' component...,deleted stock 'cloud' component...) and no attempt atfrontendanywhere. - Repeated-boot stability — the exact test that originally caught the
crash, repeated 5 times: after the pipeline above paired the device
(so a real
willoconfig entry now exists, exercising both this integration's own cleanup copy AND the orchestrator's),hasswas relaunched on that same config directory 5 times in a row. Every single launch reached a healthy, API-responding state (curl http://localhost:8123/api/→401, the expected "unauthenticated but alive" response) in ~3 seconds, with no crash, no recovery-mode fallback, and noImportErrorin any of the 5 logs — the onlyERROR-level lines across all 5 were benign artifacts of the test harness killinghassmid-setup between cycles (a cancelled socketio connect attempt,asyncio.exceptions.CancelledError: Home Assistant is stopping), not bootstrap failures.frontend's files were still present and intact after all 5 cycles. frontendis genuinely still reachable — this is expected, and is exactly why the goal is not yet fully met. On the same instance,GET /returnedHTTP/1.1 200 OKwith 5917 bytes of real HA dashboard HTML (it was a302 → /onboarding.htmlbefore pairing, in the earlier "does configuration.yaml exclusion work" test — both arefrontendactively serving real content, just at different points in onboarding). This confirms the trade this fix makes: reboots are now safe (no crash), at the cost offrontendbeing fully reachable again unless the network-binding mitigation above is also implemented — that part of the original goal ("no HA UI ever reachable") is NOT met by this change alone, and is flagged as the next concrete step rather than papered over.
Headless config-entry creation — mechanism (b) chosen, verified working end-to-end; mechanism (a) verified NOT to work.
- Mechanism (a), HA's config-entries REST flow API: rejected.
homeassistant/components/config/config_entries.py'sConfigManagerFlowIndexView.get_context()hardcodescontext["source"] = config_entries.SOURCE_USERfor every flow initiated throughPOST /api/config/config_entries/flow— confirmed both by reading that source and by driving the real endpoint (curl -X POST .../api/config/config_entries/flow -d '{"handler": "willo"}'with a real admin bearer token) against a livewillointegration, which always landed onstep_id: "user". - Mechanism (b), a direct
.storage/core.config_entrieswrite + Core restart: chosen, and verified two different ways — a hand-written entry with the schema inorchestrator/willo_orchestrator/ha_entry.py's doc comment, AND the real orchestrator's ownwrite_willo_entry()in a full end-to-end run — both were picked up correctly by Core on restart and hadasync_setup_entrygenuinely invoked (proven by the entry landing instate: "setup_retry",reason: "Could not reach Willo's tunnel at https://api.willo.sh"— that exact string only comes fromcustom_components/willo/__init__.py's ownConfigEntryNotReadypath). custom_components/willo/config_flow.pystill gained theasync_step_claimstep the issue asked for (accepts{home_id, secret}, no HTTP call, no form) — it's real and tested (tests/test_config_flow.py), but per the above it is reachable only from code running inside HA Core's own process (hass.config_entries.flow.async_init(DOMAIN, context={"source": "claim"}, data=...)), not by the orchestrator, which is a separate process by design.
Onboarding REST automation — verified end-to-end on HA 2026.2.3. Real
endpoints and payloads, read from homeassistant/components/onboarding/views.py
and confirmed live:
GET /api/onboarding → [{"step": "user"|"core_config"|"analytics"|"integration", "done": bool}, ...];
POST /api/onboarding/users {name, username, password, client_id, language} → {auth_code};
POST /auth/token (grant_type=authorization_code, code, client_id) → {access_token, refresh_token, expires_in, ...};
POST /api/onboarding/core_config, POST /api/onboarding/analytics (bearer auth, empty body) → {};
POST /api/onboarding/integration {client_id, redirect_uri} (bearer auth) → {auth_code}.
The real Willo backend claim routes went live mid-development. At the
start of this work, https://api.willo.sh/tunnel/claim answered 404 Cannot POST /tunnel/claim (reachable host, undeployed route — the
backend for this same issue was being built in parallel). By the end,
the same call answered 201 {"claimCode", "claimToken", "expiresAt"} and
GET /tunnel/claim/status answered {"status": "pending"} — both
matching the documented contract exactly, confirmed by
orchestrator/willo_orchestrator/main.py's own real run against it (see
its log: a real POST succeeded, no mock fallback triggered). Completing
a real claimed transition needs an authenticated Willo-app owner
calling POST /homes/:id/claim-device, out of scope here — the mock in
willo_client.py (WILLO_CLAIM_URL/WILLO_CLAIM_STATUS_URL env vars
point at it when the real backend is unreachable) exists to exercise that
transition and the rest of the boot sequence without it.
Still genuinely unverified — needs real HAOS hardware, not a plain venv or Docker Core install:
- The HAOS Supervisor hostname-rename API (
willo.local) — Supervisor's own REST surface does not exist in a plainpip install homeassistantenvironment at all. - Add-on ↔ Core networking and filesystem access under actual
Supervisor management. In particular,
orchestrator/willo_orchestrator/cleanup.py's belt-and-suspenders deletion assumeshomeassistantis importable from wherever the orchestrator runs — true in every sandbox test here (orchestrator and Core share one venv), but a real HAOS add-on normally runs in its own container, isolated from Core's container filesystem by default. Nothing in this task could confirm whether the realwillo-localadd-on will have access to Core's installed package path at all — flagging this plainly rather than assuming it "just works" on real hardware. - Whether real HAOS's own Supervisor/Ingress needs Core's
http:bound to something other than loopback to keep working. Supervisor's Ingress feature (the mechanism HAOS normally uses to reach Core's UI through Supervisor's own reverse proxy) may expect to reach Core directly on its usual interface/port — binding Core to127.0.0.1only could plausibly conflict with that on real hardware in a way a plain venv Core (with no Supervisor process at all) cannot surface. This sandbox proved the binding itself works exactly as intended for a bare Core process; it cannot prove Supervisor is fine with it. A real HAOS Green is needed to confirm this one way or the other before shipping. deviceModeldetection (orchestrator/willo_orchestrator/device_model.py, for the Willo app's own "Connect Home Assistant" auto-detect screen, which readsGET /status'sdeviceModelfield to say "Found a Willo Green" instead of assuming every appliance is one). What IS verified:aiohasupervisor(Supervisor's real, typed Python client, already an installed dependency of the stockhassiointegration — inspected directly in this sandbox, not remembered from memory) exposesSupervisorClient(api_host, token).os.info()→OSInfo.board: str | NoneviaGET os/info, and this module correctly returnsNonewithout raising whenSUPERVISOR_TOKENisn't set (every sandbox test here) or whenhttp://supervisoris unreachable — both real, tested behaviors. What is NOT verified: an actual Supervisor's real response shape and whetherhttp://supervisor/SUPERVISOR_TOKENbehave exactly as HAOS's own add-on documentation describes — there is no Supervisor at all in a plain venv/Docker Core sandbox to check against. Confirm this against a real HAOS Green before trusting the Willo app's board-name copy in production.
The final phase of this work: package the orchestrator as an actual HAOS
add-on (Dockerfile, config.yaml, s6-overlay service — nothing built
before this was add-on-shaped, it was a bare Python process in a venv),
implement the willo.local hostname rename, and test as much of this as
possible against a real Supervisor, not bare Core — explicitly the
last verification gate before anyone touches real HA Green hardware.
haos-addon/config.yaml, build.yaml, Dockerfile, and the
rootfs/etc/s6-overlay/s6-rc.d/willo-local/ service definition were built
by cloning and reading home-assistant/addons (the real, first-party
add-ons collection) and home-assistant/addons-example, not by guessing
the shape:
build.yamlpinsghcr.io/home-assistant/{arch}-base:3.24-2026.06.1— the exact, current base imagehome-assistant/addons/configurator(a real, currently-published add-on) uses.config.yaml'shassio_api: true/homeassistant_api: true/hassio_role: manager/map: [{type: homeassistant_config}]are all real fields, each taken from a specific real add-on in that repo (duckdnsforhassio_api,configuratorforhomeassistant_api,sshforhassio_role: manager— the same elevated role this add-on needs for the same reasonsshdoes, OS-level Supervisor calls — andmatter_server/configuratorfor thehomeassistant_configmap type that mounts Core's config directory at/homeassistant).- The s6-overlay v3 service layout
(
s6-rc.d/willo-local/{type,run,finish,dependencies.d/base}+s6-rc.d/user/contents.d/willo-local) matchesconfigurator's real rootfs exactly;finishis copied verbatim (real add-ons share this exact boilerplate for s6 supervision teardown).
Verified for real — a genuine docker build and docker run, not just
a file that looks plausible:
$ sudo docker build -f haos-addon/Dockerfile \
--build-arg BUILD_FROM=ghcr.io/home-assistant/amd64-base:3.24-2026.06.1 \
-t willo-local-test .
# ... real base image pull, real `pip3 install /opt/orchestrator` (aiohttp,
# aiohasupervisor, ulid-transform and their transitive deps all resolved
# for real), real COPY of willo-claim-ui/dist and the s6 rootfs ...
#11 writing image sha256:8e59d0d7... done
$ sudo docker run --rm -d -p 18080:8080 willo-local-test
$ docker logs <container>
s6-rc: info: service willo-local: starting
s6-rc: info: service willo-local successfully started
[11:29:26] INFO: Starting Willo Local orchestrator...
2026-09-15 ... INFO willo_orchestrator.server: Willo orchestrator serving on http://0.0.0.0:8080 ...
2026-09-15 ... INFO willo_orchestrator.device_model: SUPERVISOR_TOKEN not set — ... deviceModel will be null
2026-09-15 ... INFO willo_orchestrator.hostname: SUPERVISOR_TOKEN not set — skipping hostname rename
2026-09-15 ... ERROR __main__: Willo orchestrator boot sequence failed
willo_orchestrator.ha_client.HAClientError: GET /api/onboarding -> 404
$ curl http://localhost:18080/status
{"stage": "onboarding", ..., "error": "GET /api/onboarding -> 404"}
$ curl -o /dev/null -w '%{http_code}' http://localhost:18080/
200
This confirms, for real: the image builds cleanly on the real official
base image; s6-overlay correctly recognizes and starts the willo-local
service; the run script's real bashio calls and env vars work; the
orchestrator starts, correctly detects the Supervisor-less environment
(both device_model.py and hostname.py degrade to their documented
no-op path, not a crash) and correctly attempts http://homeassistant:8123
(the real HAOS internal DNS name for Core an add-on with
homeassistant_api: true gets, not localhost) — which 404s here only
because there's no real Home Assistant network in a bare docker run,
exactly as expected; and the claim UI itself is served correctly (GET /
→ 200) from inside the container. The ONE thing this does NOT prove is
the add-on actually installed and started BY Supervisor (as opposed to a
bare docker run) — that's the VM section below.
Found the same way os/info's board field was found earlier: by reading
aiohasupervisor's actual installed source, not guessing an endpoint.
aiohasupervisor/host.py's HostClient exposes GET host/info →
HostInfo.hostname (the current value) and POST host/options ←
HostOptions(hostname=...) (set_options) — both real, typed, confirmed
by import (from aiohasupervisor.models import HostOptions; HostOptions(hostname="willo") constructs cleanly). Wired into
main.py's boot sequence early (independent of onboarding, same as
deviceModel), gated on SUPERVISOR_TOKEN exactly like device_model.py,
never raising. Verified: the no-Supervisor path (every sandbox test here,
including the real docker run above) degrades correctly. NOT verified:
that host/options actually renames the host against a live Supervisor —
see below for why that specific call couldn't be reached this round.
Home Assistant publishes official HAOS QEMU/VirtualBox VM images specifically for this kind of testing. Checked feasibility honestly before assuming anything:
$ ls -la /dev/kvm
crw-rw---- 1 root kvm 10, 232 ... /dev/kvm
$ egrep -c '(vmx|svm)' /proc/cpuinfo
64
$ systemd-detect-virt
wsl
This sandbox runs inside WSL2 (itself a Hyper-V VM) — nested virtualization
inside a VM is exactly the kind of setup that often silently doesn't work.
Tested rather than assumed: installed qemu-system-x86 (Debian's real apt
package), added the sandbox user to the kvm group, and booted a real
KVM-accelerated QEMU guest (qemu-system-x86_64 -accel kvm -cpu host ...)
— it worked, with no fallback-to-software-emulation warnings. Real
hardware-accelerated virtualization genuinely works in this sandbox —
not a given, confirmed rather than assumed.
Downloaded the official release: home-assistant/operating-system
release 18.2, haos_ova-18.2.qcow2.xz (the QEMU/VirtualBox-targeted
OVA variant). First real finding: this image is UEFI-only — booting
with plain SeaBIOS (QEMU's default) hangs silently at "Booting from Hard
Disk..." forever; booting with OVMF firmware
(-drive if=pflash,file=/usr/share/OVMF/OVMF_CODE_4M.fd + a writable
copy of OVMF_VARS_4M.fd) boots correctly into a real HAOS systemd
environment (HAOS ZRAM units, the real EXT4 root mount, the genuine
"Welcome to Home Assistant" console banner).
Home Assistant Core, under real Supervisor management, DID become
reachable once: curl http://localhost:<forwarded-port>/api/ answered
401 (up, unauthenticated) on the very first successful boot — real,
concrete proof this whole pipeline can work end to end in this sandbox.
That specific attempt was then lost to a real mistake, not a fundamental
blocker: repeated probes against /api/ (which requires auth) rather
than the actually-public /api/onboarding appear to have triggered HA's
own IP-ban security middleware, after which even the public endpoint
returned a bare 401 for the rest of that boot. Lesson applied for every
attempt after: only ever poll /api/onboarding for readiness (the same
real, already-verified check HAClient.wait_until_api_ready uses against
bare Core).
Every subsequent attempt (fresh disk each time, to rule out any
carried-over bad state) hit a reproducible stall: GET /api/onboarding
consistently returned 307 Temporary Redirect → Location: http://<host-without-port>/api/onboarding, with Server: Python/3.14 aiohttp/3.14.3 — a different Python version than bare Core's 3.13.5 in
every earlier venv test, strong evidence this response comes from
Supervisor's own landing/proxy service while Core itself was never
successfully started. Diagnosed with real evidence, not guessed: QEMU's
own monitor (info usernet) showed the guest actively opening large
numbers of short-lived DNS and DNS-over-TLS (port 853, to 1.1.1.1/
1.0.0.1) connections that established at the TCP level but produced no
further traffic — a recognized category of QEMU usermode-networking
(slirp) limitation, not a HAOS/Supervisor bug. Tried a targeted, evidence
based fix (-device virtio-net-pci,...,host_mtu=1400, addressing a known
slirp MTU/fragmentation issue) on a fresh disk; it did not resolve the
stall within the time available for this task. The next real fix — a
bridged/tap network device instead of slirp, avoiding QEMU's usermode
networking entirely — was not attempted: it needs installing and
configuring iptables/a DHCP server/bridge-utils from scratch, a
materially larger new effort, and time ran out on this pass.
Reported honestly, not forced: full HAOS+Supervisor first-boot
provisioning did not complete in this sandbox this round. What IS now
genuinely verified, distinct from every earlier bare-Core test:
Docker/OS-level virtualization is real and works here; the official HAOS
image is correctly downloadable and bootable (with the UEFI finding);
Core reachability under real Supervisor management was directly observed
once. What remains unverified, and needs either a follow-up session with
bridged VM networking or the user's own real HAOS Green hardware: the
actual host/options hostname-rename call, os/info's real response
shape, and the packaged add-on actually being installed and started BY a
live Supervisor (as opposed to the bare docker run verified above,
which proves the container itself is correct but not Supervisor's own
add-on lifecycle management of it).
Asked to retry specifically because this sandbox runs inside WSL2, a possible source of stacked NAT/MTU issues on top of QEMU's own slirp layer. Checked rather than assumed:
$ grep -i networkingMode /mnt/c/Users/*/.wslconfig
networkingMode=mirrored
WSL2 itself is in mirrored networking mode here — there is no WSL2-level NAT stacked on top of slirp; slirp was always the only NAT layer involved, which narrowed the problem back to QEMU itself.
Built a real bridged-TAP replacement for slirp instead of another MTU
tweak: a private Linux bridge (br-willo, 10.99.99.1/24) with a TAP
device (tap-willo) attached, kernel ip_forward + iptables -t nat MASQUERADE out the sandbox's real uplink, and dnsmasq bound to the
bridge for real DHCP + DNS (forwarding to 1.1.1.1/8.8.8.8) — this
makes the guest a normal peer on a real bridge rather than double-NATed,
which was the specific concern raised. Booted the HAOS image against
this (fresh disk, OVMF/UEFI as before, -netdev tap,ifname=tap-willo).
This produced genuinely different, more promising behavior than every
slirp attempt: a real DHCP lease in ~2 seconds, and (on the first,
4096MB-RAM run) 719MB of real inbound data transfer through the
bridge's FORWARD chain — slirp attempts never moved meaningful data
before hanging. But the same 307/no-Core-yet symptom still appeared
afterward, and a 5-minute wait showed the FORWARD byte counters frozen
and QEMU at 0% CPU — a genuine stall, just reached differently than the
slirp DNS-over-TLS hang.
Hypothesized memory pressure (QEMU's RSS was at ~4.0GB of the 4096MB
allocated — right at the ceiling) and retested on a fresh disk with
-m 8192 (8GB) as one bounded final attempt. Result: the same stall
reproduced, just later and at a higher plateau — RSS climbed to and then
sat flat at ~8.41GB from roughly t=105s onward, while CPU decayed
smoothly and predictably from ~81% down through the 40s% over the next
several minutes, the same shape as the 4GB run's decay into its stall,
not a different failure mode. This rules out memory pressure as the
cause — doubling available RAM delayed the stall but did not prevent
it, so whatever is actually happening is not simply "ran out of memory."
Net result of this retry: real, concrete progress (mirrored WSL2 networking confirmed as a non-factor; TAP/bridge networking confirmed to move real, substantial data where slirp never did; the memory-pressure hypothesis tested and ruled out) but the underlying stall itself is still not resolved. The most likely remaining suspects — none confirmed, since there is no console/SSH access into the guest to observe what is actually stuck — are: Supervisor's own container-image pull hitting a slower-but-still-limited path even over the bridge, or an internal retry/backoff loop (e.g. the same class of DNS-over-TLS behavior seen under slirp, now happening at the container-runtime level inside the guest rather than at QEMU's network layer) that simply takes longer to reach than the 4-6 minutes attempted here. Getting further would need either serial-console/SSH access into the guest to see what is actually blocked, or substantially longer unattended wait times than were spent on this task — a genuinely different, larger effort than a retry, not a quick fix. Per the explicit instruction not to chase this indefinitely, stopped here and cleaned up the VM/bridge/TAP/dnsmasq infrastructure rather than continuing further.
ha_config.py's ensure_explicit_configuration() was unconditional: it
always overwrote configuration.yaml with Willo's own fixed template and
restarted Core to apply loopback binding. That is only safe on a
genuinely fresh, never-configured device. It is catastrophic on an
existing install — confirmed against a real user's actual Home Assistant
Green: an 800+ line configuration.yaml, ~15 packages, shell_commands
controlling their home router's VPN, per-room climate/ventilation
automations, and a custom "Marco" dashboard panel — months of real work
that an unconditional overwrite would have destroyed.
The fix is self-detecting, not an opt-in mode. main.py's boot
sequence now checks has_meaningful_existing_configuration()
(ha_config.py) before ever calling ensure_explicit_configuration() or
restarting Core for it — nothing for a caller to remember to set:
- Fresh/default content → unchanged behavior. A missing
configuration.yaml, HA's own untouched default, or Willo's own already-applied template all proceed exactly as before: the explicit allow-list + loopback binding gets written, Core restarts, onboarding runs to completion, cleanup runs, the claim flow runs. - Real pre-existing content → configuration.yaml is never touched.
The entire onboarding-automation branch (creating a throwaway admin
user, the configuration.yaml rewrite, the loopback-binding restart,
cleanup deletion, the claim flow, writing a config entry) is skipped
outright — onboarding's "user" step would fail anyway on a device
that's been onboarded for months, and cleanup's deletion of
analytics/cloudfrom the sharedhomeassistantpackage install is not something to ever risk on a device with real, active users. Only what already runs unconditionally, independent of this decision — hostname rename via Supervisor, and serving this status/claim UI — still runs. A new"existing-install"status stage (status.py,willo-claim-ui'suseOrchestratorStatus.ts/App.tsx) reports this live, with distinct copy ("Importando configuración actual…") instead of a misleading "setting up" message. The orchestrator logs exactly which path was taken and why, every time — never silent.
What "fresh" actually means was verified empirically, not guessed:
running a real, never-before-launched hass against an empty config
directory (HA Core 2026.2.3) and reading back exactly what it wrote —
11 lines: default_config:, a frontend theme include, and
automation/script/scene !include directives. That exact content,
and Willo's own template once applied, are the two fast-path "definitely
fresh" cases. Everything else is judged by a small, closed allow-list of
top-level YAML keys plus the homeassistant: block's own sub-keys
(catching packages:, HA's real mechanism for pulling in an entire
directory of real automations from a single short line, which lives
nested under homeassistant: rather than as its own top-level key) and a
generous line-count ceiling as a defensive catch-all. Deliberately
conservative: content this can't even parse, or any single unrecognized
key, is treated as real — never guessed as "probably fine."
Verified against real local HA Core instances for both branches (unit
tests in test_ha_config.py cover the detection function itself,
including a realistic large fixture with packages/shell_command/inline
platform config modeled on the real device this was verified against):
- Fresh path, unchanged behavior: a brand-new HA Core instance, run
through the full boot sequence with this round's code — admin user
created,
configuration.yamlrewritten to Willo's template, Core restarted, onboarding completed, cleanup ran, reachedawaiting-pairingwith a real claim code. Byte-for-byte confirmed the finalconfiguration.yamlmatchesCONFIGURATION_YAML_CONTENTexactly. - Existing-install path: a separate real local HA Core instance seeded
with a realistic hand-authored
configuration.yaml(nestedhomeassistant.packages,shell_command, inlinesensor:platform config — nowilloconfig entry, so this exercises the new detection path rather than the already-existinghas_willo_entryshort-circuit). Ran the real orchestrator against it and confirmed:configuration.yamlbyte-for-byte unchanged (md5 identical before/after), Core's process never restarted, no new admin user created (\.storage/auth's user count unchanged), nowilloentry written, the orchestrator logged exactly why it stopped,status.stagereported"existing-install", andGET //GET /statuskept serving normally throughout.
A real, pre-existing sandbox limitation surfaced (and worked around) by
this verification, not caused by this fix: a bare-venv Core does not
always relaunch itself after a homeassistant.restart service call —
sometimes it re-execs in place, but a hung shutdown thread (observed here
from default_config's Sonos discovery reaching for real UPnP devices on
this sandbox's LAN) can make it exit for good instead. Real HAOS doesn't
have this gap (Supervisor always relaunches Core), so this was worked
around for these tests only with a small shell loop that relaunches
hass whenever it exits — test infrastructure, not a code change.
With the existing-install safety fix verified in the sandbox, this add-on
was actually installed on the user's real, daily-used Home Assistant
Green (with their and the coordinator's explicit review of the exact plan
before anything touched the device). Read-only recon first (board/model,
Supervisor version, configuration.yaml size, existing config entries,
port usage), then an offline dry-run of has_meaningful_existing_configuration()
against a copy of the real configuration.yaml (returned True, deleted
the copy immediately after), then the actual install: a self-contained
package (this repo's orchestrator/ + willo-claim-ui/dist/ + haos-addon/'s
rootfs/config, repackaged so Supervisor's local-add-on build — which
always uses the add-on's own folder as context — has everything it needs,
since the repo's own Dockerfile deliberately shares orchestrator/ from
the repo root instead) transferred to /addons/willo-local/ and installed
via ha apps install local_willo-local.
For this specific deployment, two changes from the repo's own
haos-addon/config.yaml default: no image: field (Supervisor builds
natively for the device's real architecture instead of pulling a
nonexistent registry image), and homeassistant_config mapped
read_only: true as extra defense-in-depth on top of the code-level
checks — both has_willo_entry() and has_meaningful_existing_configuration()
only ever read that directory, so read-only access is sufficient for
everything this device needs and makes a write physically impossible
regardless of application logic.
Real, live results: this device already had a genuine willo config
entry (source: "user", created via the normal config flow, not this
orchestrator) — so has_willo_entry() alone already short-circuited the
whole boot sequence, confirmed live in the add-on's own logs:
2026-09-16 04:17:03 INFO willo_orchestrator.server: Willo orchestrator serving on http://0.0.0.0:8080 ...
2026-09-16 04:17:09 INFO willo_orchestrator.hostname: Renamed host to 'willo' via Supervisor (host/options)
2026-09-16 04:17:09 INFO __main__: A willo config entry already exists in /homeassistant — nothing left to do
This is the first real confirmation, against genuine live Supervisor, of
two things previously only implemented/unit-tested: hostname.py's
host/options call (the device's real hostname changed to willo,
confirmed via ha host info) and device_model.py's os/info call
(GET /status from another LAN host returned "deviceModel": "Green" —
real Supervisor data, not the previously-only-verified null-off-Supervisor
path). configuration.yaml's md5 and mtime were both confirmed identical
before and after every step of this deployment.
Moved the orchestrator's port from 8080 to 80, since a real appliance shouldn't need a port typed in. Checked rather than assumed, in order:
- Real port-80 conflict check on the actual device: none of the
already-installed add-ons (Matter Server, Music Assistant, the local
marco_webadd-on, Spotify Connect, etc.) publish port 80 or 443 — confirmed via each add-on's ownnetwork:mapping throughha apps info. Also confirmed directly and unambiguously from an external LAN host (this sandbox, the same vantage point a real browser uses):curl/a raw TCP connect to192.168.8.25:80both got a clean "connection refused" beforehand — genuinely free, not just unconfigured-looking. - Binding a sub-1024 port from inside a container: checked the real,
currently-published
home-assistant/addons/sshadd-on (it binds port 22) rather than assuming. ItsDockerfilehas noUSERdirective and itsconfig.yamlhas noprivileged:field at all — it binds a privileged port purely by running as root, which is the official base image's default. This add-on's ownDockerfilenever drops to a non-root user either, so it already had the same implicit capability — noprivileged: [NET_BIND_SERVICE]grant was needed, matching the real, confirmed convention rather than reaching for a broader or narrower fix than what other add-ons actually do. - Verified in the sandbox first: rebuilt the package with
ports: 80/tcp: 80andWILLO_PORT=80, ran it, and confirmed for real — not just that it didn't crash — that the process bound port 80 (ss//proc/net/tcpinside the container showed0.0.0.0:80 LISTEN .../python3, running asroot) and served/statuscorrectly through the mapped host port. - Redeployed to the real device: stopped the running add-on,
replaced
/addons/willo-local/with the updated package,ha refresh-updates,ha apps rebuild local_willo-local(rebuilds the image but does not itself restart the app — needed an explicitha apps startafterward), confirmed the live log linewillo_orchestrator.server: Willo orchestrator serving on http://0.0.0.0:80, confirmedcurl http://192.168.8.25/status(genuinely no port) returns the correct JSON from an external LAN host, confirmed the old port 8080 is gone (connection refused), and confirmedconfiguration.yaml's md5/mtime unchanged through the whole redeploy.
What is NOT claimed as verified: http://willo.local (mDNS, no port)
resolving from an actual browser. This sandbox has no mDNS resolver
configured at all (curl http://willo.local fails to resolve here,
confirmed), so a curl-based check from this Linux sandbox would not be
meaningful either way — mDNS resolution behavior is genuinely different
across client stacks (Windows vs. Linux vs. mobile), which is exactly why
this needs a real check from the user's own browser, not a self-declared
pass from here. (Notably, the add-on's own access logs already show the
user's Windows browser successfully browsing http://willo.local:8080/
in the minutes before this port change — real evidence mDNS resolution
itself already works for them; only the port needed to change.)
A separate, minor finding worth a future fix, not addressed here:
Supervisor's own log flagged that stopping this add-on doesn't handle
SIGTERM gracefully (willo_orchestrator.main's async_main() has no
signal handler, so asyncio.Event().wait() just gets killed by the
default handler) — cosmetic/non-blocking (the process does stop), but
worth trapping and shutting down cleanly in a future pass.
- Onboarding REST payload shapes — fully verified (see "Onboarding REST automation" above).
- Headless config-entry creation mechanism — fully verified, mechanism (b) chosen (see "Headless config-entry creation" above).
- HAOS Supervisor hostname-rename API — fully verified against
real, live Supervisor (see "Real Home Assistant Green deployment"
above): the actual device's hostname changed to
willo, confirmed viaha host infoon the device itself. - Add-on ↔ Core networking — the add-on being built and installed
by real Supervisor (not just
docker runin isolation) is now verified,device_model.py'sos/infocall returned real data ("Green") against live Supervisor, and the add-on's own network reachability (http://<device-ip>/statusfrom another LAN host) is confirmed. Still not verified against live Supervisor:cleanup.py's belt-and-suspenders deletion actually running (this device correctly never needed it, since it was already willo-paired) — that specific sub-case would need a genuinely fresh HAOS Supervisor device to exercise, which real hardware understandably wasn't used for.
No code in this repository or its tests ever attempted to reach real Home
Assistant Green / HAOS hardware or the user's home network — every test
above ran against a disposable local HA Core install or a disposable
local HAOS VM created for this task, and custom_components/willo's own
tunnel target (DEFAULT_TUNNEL_URL) was never pointed anywhere but the
real, public api.willo.sh (reachable from this sandbox, unrelated to
any home network) or an explicit local test stub.