Home Assistant add-on

The Home Assistant client ships as a Supervisor add-on (a Docker container) rather than an installer. Unlike the other clients, it connects unconditionally and stays connected — a Home Assistant box doesn't roam away from an office network the way a laptop does.

Prerequisites

• A running backend (Community or Pro).
• Home Assistant OS or Supervised (add-ons need Supervisor — a plain Home Assistant Container/Core install can't install this).
• Optional: the official Mosquitto broker add-on, if you want a connected/disconnected entity inside Home Assistant.

Steps

1. Add the Valenius add-on repository

Settings → Add-ons → Add-on Store → ⋮ (top right) → Repositories, and add:

https://github.com/valeniusvpn/valenius

Refresh the store — Valenius VPN appears under a new "Valenius" section.

2. Install it

Click Valenius VPN → Install.

3. Configure it

Open the add-on's Configuration tab and set:

• backend_url — your backend's address, e.g. https://vpn.example.com.
• api_key — your fleet's client API key (Admin → Settings → Client connectivity).
• profile_name (optional) — only needed if you want to pin a specific profile instead of whatever the backend assigns first.
• mqtt_host / mqtt_port / mqtt_username / mqtt_password (optional) — leave blank if the official Mosquitto add-on is installed; it's discovered automatically.

Start the add-on.

4. Activate it in the admin panel

The add-on registers itself as a pending client on first start (the Overview page shows a Pending counter — click it). Open the new client, assign it to its customer, and click Activate. It picks this up on its own within a few minutes.

Verify it works

1. The add-on's log (its Log tab) shows it started without errors.
2. In the admin panel, the client shows as online (green) after activation.
3. It connects on its own — no "Connect" button to click, unlike the other clients. Give it a few minutes after activation, then check the client's status in the admin panel.
4. If you configured MQTT, a binary_sensor for the connection appears in Home Assistant automatically (no manual entity setup).

Common problems

The add-on fails to build with a "not found" error mentioning a file path. This was a real bug in an early version of the add-on (fixed) — if you still see it, Settings → Add-ons → Add-on Store → ⋮ → Check for updates, then reinstall. This pulls the latest commit from the repository; a stuck build is usually just a stale local clone.

The client never appears as pending in the admin panel. Check the add-on's log for the backend URL/API key it's using — a typo there behaves the same as the server being unreachable. backend_url needs the https:// prefix.

No entity shows up in Home Assistant. MQTT is optional and only works if a broker is reachable. If you're using the official Mosquitto add-on, confirm it's installed and running; otherwise fill in mqtt_host and the other mqtt_* options by hand.

Updates: do I ever reinstall by hand? Unlike the other clients, this one is not managed from Admin → Releases — Home Assistant Supervisor updates it the normal Home Assistant way, by pulling new commits from the add-on repository. Check for updates in the Add-on Store surfaces new versions. Learn more →