BETA — Open to testers. Tell us what to fix on @vomehome or via a tester code.

Set up HomeLink L2

How to put a hosted Home Assistant on the same LAN as the house — and the traps that look like a broken VPN but are not.

Updated 28 August 2026 networkinghomelinkhow-to

HomeLink L2 extends your home network: the hosted Home Assistant becomes a member of your LAN, on the same broadcast domain as the bulbs and the Thread border router. A routed tunnel cannot do that. Broadcasts are designed never to leave the LAN they were sent on.

This is opt-in, not the default, and it moves the house box's LAN address onto a bridge. That is the whole configuration. It is also every way this has gone wrong. If you only wanted the symptoms, see HomeLink L2.

The whole change, in one picture Before the network card 192.168.1.16 · default route nothing else involved After hl-br — the bridge 192.168.1.16 · default route the card the tunnel both now just ports on it The address does not change. Where it lives does.
This is why the recovery path is SSH to that same LAN address: it is the same address either way, so it still reaches the box whether the change worked, half-worked, or was rolled back.

What you need

  1. A small always-on Linux machine on the LAN (the house box). One NIC is enough. Root access by SSH — not a hypervisor console. Some consoles cannot take a paste; SSH to the LAN address is the recovery path, and that address stays the same whether it sits on the NIC or on the bridge.
  2. HomeLink slot 1 already up on that box, with a recent handshake. That is the site-router tunnel; L2 rides inside it.
  3. Someone who can confirm from another machine that the house box is still reachable after the address moves.

The datacentre half is provisioned for you. You are setting up the house half.

Steps

1. Put the current L2 script on the box. An older copy will write a boot unit that cannot start, and will uninstall itself ten minutes after a successful boot. Checksum what you install against what we shipped.

2. Bring the link up, with rollback armed first.

homelink_l2.sh up --force --role house --lan <your-nic> \
    --peer <dc-wg-ip> --local <house-wg-ip> --vni <id>

--force is required on a single-NIC box: the NIC holds the default route, and moving it is how you lose the session you are typing into. The script arms a ten-minute rollback before it touches anything. If you cannot reach the box afterwards, do nothing. Silence is what restores it. Do not reboot, and do not "fix" the network, while that timer is running.

It will wait about 35 seconds for the bridge to start forwarding.

Why doing nothing is the correct action arm change +10 min you can reach it run confirm — it is kept you cannot do nothing — it undoes itself A rollback you have to reach the box to trigger is not a rollback.
Rebooting or “fixing” the network while the timer runs is what turns a self-healing ten minutes into a site visit.

3. Confirm from outside, then keep it.

homelink_l2.sh confirm --role house --lan <your-nic>

That disarms the rollback and enables the two units that must both be on: one rebuilds the link at boot, the other puts the NIC back in the bridge when netplan takes it out while the machine is running.

4. Reboot it on purpose. Three of the faults that took a live site down existed only at boot, and one of them was in a unit described as verified because it had been read rather than run. After reboot, SSH to the same LAN address and check: the tunnel is up, the L2 unit is active, the LAN address is on the bridge (hl-br), and Home Assistant still has its house address. Anything less is still an untested claim.

Why it is this way

These are not style choices.

Trap Why
Rollback before the risky step Losing contact is the failure. The timer does not need you to reach the box.
--force in the boot unit At boot, netplan has just given the NIC the default route. The interactive guard refuses that state, and without --force the unit fails on every reboot while the house looks fine.
No rollback at boot The rollback command is uninstall. A confirmed boot that re-armed it would delete itself ten minutes later.
stop ≠ down systemd runs ExecStop on the way to a reboot. Uninstall there would remove the units during shutdown.
netplan still owns the NIC Taking it off netplan on a remote box is how you lose the box. A watchdog repairs the specific failure in about 80 seconds instead.
No # in a PostUp wg-quick treats # as a comment, mid-line. ${var#pattern} becomes a missing brace and the tunnel dies.
No awk in a PostUp wg-quick is confined by AppArmor. The refusal looks like a dead VPN.
Route MTU for the endpoint The bridge inherits the overlay MTU, then fragments the tunnel's own packets. There is no stable tunnel MTU. Measured: 4.3 Mbps without the pin, 296 Mbps with it.
IPv6 MTU floor 1280 Below that the kernel silently strips IPv6; wg-quick reports "No such device" and tears the whole VPN down.
MSS clamp on forwarded traffic Pinning this box's MTU does not change what a phone on the LAN negotiates. The ICMP that would correct it is dropped. Ping stays perfect.
Flood multicast both ends Snooping black-holes IPv6 toward the tunnel. IPv4 mDNS still looks healthy.
Two NICs on the guest; management has no gateway Home Assistant picks a NIC per service. It advertised Matter onto the management network.

If you are copying this rather than running our script, copy those constraints too. The longer write-up of the wrong turns is Four megabits on a three-hundred line.

When it goes wrong

The symptom table lives on HomeLink L2. The short version: a healthy tunnel does not mean L2 is up. After a reboot the house can look perfect (netplan gave the NIC its address back) while the hosted server has no house devices at all.

Rather not do this alone?
The Vome assistant will walk you through this guide a step at a time, and can do some of it for you.
Sign in for AI help

Something wrong or missing here? Tell us — these pages are written from real work, so corrections are welcome.