Home Assistant — how to connect

The plugin ships one node type, HomeAssistant/Home: a node whose content is the connection to one Home Assistant instance and whose page is a live dashboard of it. Getting the plugin puts a My Home node in your own space — that copy is yours to configure and nobody else can read it.

0. No Home Assistant yet? Install it on your Mac or PC

The connect form offers this step itself while no address is set (HaInstall, beneath the form): three lines per system — install Docker Desktop (brew install --cask docker on a Mac, winget install Docker.DockerDesktop on Windows), open it once and finish its first-run setup, wait until docker info answers (the installer does not start the engine, and a docker run before it is up fails with "cannot connect to the Docker daemon"), then docker run … -p 8123:8123 … ghcr.io/home-assistant/home-assistant:stable (host networking on Linux). Open http://localhost:8123, create the account, and enter the computer's address on the form.

🚨 The mesh cannot run this for you. A cloud portal reaches neither your computer nor your LAN, and nothing today lets the cloud push a command to a device: the bridges we have all point the other way (a local mesh as an MCP client against the cloud, the iMessage bridge hosted on the Mac, an installation registering at the registry). The install step is therefore copy-and-run, and a Home Assistant on your own machine is reached from the cloud only through Home Assistant Cloud or your own reverse proxy (see Reachability). A device agent — the local mesh app dialling out and taking jobs the portal queues for it, the way every activity enqueues on the control instance — is the step beyond this one, and is not built.

1. Create a long-lived access token

In Home Assistant, click your user name (bottom-left) → Security → scroll to Long-lived access tokens → Create token. Name it (e.g. meshweaver) and copy the value — Home Assistant shows it exactly once.

2. Configure your node

Open your My Home node. Until it is configured, its page IS the connect form:

Setting	Value	How it is entered
`baseUrl`	the instance's URL as the mesh server reaches it — typically `http://homeassistant.local:8123` on a LAN. The scheme is optional; plain `http://` is assumed.	typed into the form; saved as you leave the field
`hideEmbed`	tick it to stop the page embedding Home Assistant's own UI beneath the controls — unticked (the default) embeds it	a checkbox on the form; saved on click
`token`	the long-lived token from step 1	🔑 Enter token opens a masked dialog; paste it and press Save

The address and the checkbox are bound straight to the node — there is no Save button for them, and nothing you did not touch is ever rewritten. The token is the one field that is not: it is write-only, so it goes through its own dialog, and a blank dialog keeps the stored token rather than wiping it.

Optional (on the node's Edit view):

Setting	Value
`entities`	a list of entity ids to show, in your order — a curated page. Find ids under Developer tools ▸ States in Home Assistant.
`maxEntities`	how many entities an uncurated page shows before it says "N more not shown" (default 60)

3. Open the dashboard

The node's page now shows your home: a header naming the instance and its version, Controls (one button per light, switch, fan, cover, input boolean, automation, scene, script and button) and Readings (everything else, with each state's unit and when it last changed — rendered in your time zone). Refresh re-reads the instance; every control press re-reads it too, so the page shows the state the press produced.

Reachability — the one thing that bites

The mesh server makes the HTTP calls, not your browser. So:

a local mesh on the same network reaches http://homeassistant.local:8123 directly;
a cloud mesh cannot reach a private LAN address — your instance needs an externally reachable URL (Home Assistant Cloud, or your own reverse proxy with HTTPS).

If the page says it cannot reach the instance, that checklist — URL reachable from the mesh, token still exists, http vs https, port 8123 — is almost always the answer.

Security, by design

The page never renders the token. The connect form says only whether one is set; the dashboard's diagnosis shows at most ···· plus its last four characters. The token is stored in the node's content, in the clear, so the node's partition access control is what protects it: keep the node in your own space, and don't move it into a shared one — anyone who can open the node's generic Edit view can read it.
Locks are read-only. The dashboard never offers lock.unlock; a page that can be shared must not open doors. Sensors, cameras and climate render as readings only.
Deleting the token in Home Assistant (Profile ▸ Security) revokes the mesh's access instantly.