Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
three.ws for Home Assistant
Put a 3D agent with a voice in front of your house, from a Home Assistant that only exists on your own network.
three.ws can already connect to a Home Assistant that has a remote https address. Most installs do not have one: they sit on a LAN behind a router, with no port forwarded and nothing public, and three.ws runs on the internet, so there is no address for it to dial.
This integration is the answer for those. Your house dials three.ws, and three.ws never dials your house.
- Nothing listens on your network. No port is forwarded. No firewall rule changes.
- No tunnel daemon, no third-party service, no other account.
- three.ws never receives a Home Assistant token. This integration signs in to Home Assistant on your own machine, with a credential it makes for itself, that never leaves the house.
Works on every install type: Home Assistant OS, Supervised, Container and Core. Needs Home Assistant 2024.12.0 or newer.
Install
Through HACS
- Open HACS, then the three-dot menu, Custom repositories.
- Add
https://github.com/nirholas/three-ws-home-assistant, category Integration. - Install three.ws, then restart Home Assistant.
- Settings, Devices and services, Add integration, three.ws.
By hand
- Download the latest release.
- Copy
custom_components/three_wsinto your Home Assistantconfigfolder. - Restart Home Assistant, then do step 4 above.
Pair it
- In three.ws, open three.ws/smart-home, choose Connect a home that is only on my network, and press show me a code.
- Paste that code into the integration's setup dialog.
The code works once and lasts ten minutes. If it expires, get another one: it goes back to the same home, not a second one.
That is the whole setup. The three.ws tab flips to connected on its own within a few seconds.
What it adds to Home Assistant
One entity, named three.ws connection on the device three.ws created for this home (so its
entity ID is binary_sensor.<home name>_three_ws_connection), so you can see the state of the
link from your own dashboard without opening three.ws:
| Attribute | What |
|---|---|
relay_id |
This home's public handle. Not a secret. |
open_sessions |
How many connections three.ws currently holds |
refused_messages |
How many messages this integration refused as outside the allowlist |
last_error |
The last reason the link dropped, if any |
It also creates one system user, three.ws relay, visible in Settings, People. That is how it signs in to your own Home Assistant locally, the same pattern the built-in Supervisor integration uses. Deleting the integration deletes that user and its credential.
What three.ws can do through this
Everything it can do is fixed by an allowlist that this integration enforces on your machine,
independently of anything three.ws says. It is shipped as allowlist.json inside this
integration, generated from the relay's own source, so the two cannot quietly disagree.
Permitted: reading entity states, reading your floor, area, device and entity registries, the live state subscription, and calling device services.
Refused outright, and no confirmation anywhere unlocks them: every service on
shell_command, python_script, hassio, supervisor, backup, update, cloud, config,
auth and command_line, plus homeassistant.restart, homeassistant.stop and the reload
services. Those administer your machine rather than a device, so this integration never runs them
on three.ws's behalf.
There is no path through this integration that lets three.ws pick an arbitrary URL, run arbitrary code, or reach anything else on your network.
Unlocking, opening and disarming are permitted, and that is deliberate, because a smart-home agent that cannot unlock your door when you ask it to is not a smart-home agent. Every one of them stops on the three.ws side and waits for a person to approve it explicitly, and every one of them is written to an audit log there and to your own Home Assistant logbook here.
Read the threat model before you decide. It is specific about what a compromise of three.ws would mean for your house, and it does not undersell it.
Remove it
Delete the integration in Home Assistant. Its outbound connection closes and the local credential it created is deleted. Disconnecting from the three.ws side works too, and takes effect immediately at both ends.
Troubleshooting
"Home Assistant could not reach three.ws" during pairing: this machine has no outbound internet access, or something is blocking it. The integration only ever makes outgoing connections, so nothing needs to be opened inbound.
"That pairing code is not recognised": codes expire in ten minutes and work once. Generate another in three.ws.
"This three.ws integration is too old for the relay": update it in HACS and restart. The pairing survives an update; nothing has to be redone.
The connection sensor is off: the integration is not dialled in. It retries with backoff and
comes back on its own. last_error says why. Nothing needs re-pairing.
Developing on it
custom_components/three_ws/
__init__.py setup, the local system credential, teardown
config_flow.py pairing, the only place a code is entered
relay_client.py the outbound socket, and session multiplexing
ha_link.py one authenticated loopback connection to this Home Assistant
allowlist.py the allowlist, enforced here, independently of the relay
allowlist.json generated from services/home-relay/src/protocol.js
binary_sensor.py the connectivity entity
The relay side, the protocol and the tests live in the
three.ws repository: services/home-relay/,
docs/home-relay.md, and tests/home-relay-*.test.js.
License
Apache-2.0.