Frequently asked questions

General

What is myHAB, in one sentence?

A self-hosted home automation backend that models your whole electrical installation — zones, controllers, ports, cables and peripherals — and drives it over MQTT, with a Vue 3 PWA on top.

How does it compare to the big open-source platforms?

It is narrower and more opinionated. There is no add-on store, no radio stack, no integration for every consumer gadget. What it has instead is a model of the physical installation, first-class energy and heating telemetry, floor-plan control surfaces, and an automation language that is just Groovy.

If your house is full of plug-in smart devices, a platform with hundreds of integrations will serve you better. If your house is wired and you already run a broker, myHAB is likely to fit the way you think about it.

Is it production-ready?

It runs a real house continuously and has done for years. That is a different claim from “broadly deployed”: you are an early adopter, the documentation is this website, and support is GitHub issues. Read the security answers before exposing it to the internet.

What is the licence?

myHAB is developed under the GNU Lesser General Public License v3 (LGPLv3). The source is at github.com/kirpi4ik/myhab.

In practice: run it, modify it and deploy it anywhere, commercially included, at no cost. If you distribute a modified myHAB, those changes go out under the LGPLv3 too. Your own software may link to it and stay under whatever licence you like — that is what the Lesser in the name buys you.

Does it depend on a cloud service?

Not for control. Devices talk MQTT to your own broker, and switching a light never leaves the LAN. Some optional integrations are inherently cloud-backed — Huawei FusionSolar, NIBE myUplink, Segway Navimow, Open-Meteo, the voice assistant's LLM — because that is the only interface those vendors offer. Every one of them is off by default and degrades to “that widget shows nothing”.

Hardware

Which devices are supported?

ESP32 boards and MegaD-2561 controllers for physical I/O; TMEZON intercoms; ONVIF cameras through an MQTT bridge; NIBE heat pumps, Huawei inverters and DTSU meters, Open-Meteo and Segway Navimow as cloud-backed virtual devices. See Integrations for the full list and topic contracts.

My device is not on the list. Can I use it?

If it can publish and subscribe on MQTT, yes — teach it the topic contract and it looks like an ESP32 board to myHAB. If it speaks something else, the usual answer is a small bridge process that translates onto MQTT, exactly as the ONVIF integration does.

What about Zigbee, Z-Wave, Matter or Thread?

There is no built-in radio stack. In practice you would run a separate Zigbee-to-MQTT style bridge and present its devices to myHAB as MQTT devices. That works, but it is not something the product does for you today.

What hardware does the server need?

A small x86 machine or a Raspberry Pi 4/5 class board with about 2 GB of RAM for the JVM. The database is the part that grows — time-series port values accumulate quickly if you poll a lot of sensors, so give it real storage rather than an SD card.

Setup

Why does configuration live in a git repository?

So a change to MQTT credentials or a feature flag is a commit rather than a redeploy, and so you can see what changed and when. The application clones the repository at start and re-reads it on a schedule, and the in-app configuration editor commits back to it.

Is putting secrets in git really a good idea?

It is a deliberate, stated trade-off, not an oversight. Use a private repository, and remember that git history keeps old values — rotation means issuing a new credential and revoking the old one, never just overwriting the value. Bootstrap secrets (database, JWT key) stay in environment variables and never enter the repository.

There is no default admin account. Why?

Because there is then no well-known password to forget to change. Insert the first account with SQL — see Installation, step 3 — and create the rest from the UI.

Everything looks fine but nothing actually switches.

Almost always one of three things:

1. Nothing is answering on MQTT. myHAB waits for the device to echo its new state; without an echo the control does not move. Watch the raw monitor in the MQTT explorer while you press the button.
2. The device code contains a hyphen. Commands publish fine, but inbound state topics are matched with \w-based patterns which exclude -, so every echo is silently dropped.
3. The peripheral is not connected to a port, so there is nothing to command.

My charts are shifted by a few hours.

Run the container in UTC. myHAB stores every timestamp in UTC and converts for display using each user's timezone preference.

The audit log shows my reverse proxy's IP for everything.

Set myhab.security.trustedProxies to the proxy's own address. It is empty by default, which means no forwarding header is trusted at all — restrictive rather than permissive.

Security

Can I expose it to the internet?

Yes, but it was written for a LAN behind a router and it does not harden itself. Terminate TLS at a proxy you control, refuse the LAN-only device endpoints from outside, and rate-limit /api/login and the public share endpoints — myHAB does none of those for you.

How strong is the PIN on a shared link?

It is a speed bump, not a credential. PINs are stored and compared in plaintext with a non-constant-time comparison, and there is no rate limiting on verification. The audit trail makes brute force visible after the fact; preventing it is your proxy's job. The token in the URL is the real secret — send it over a channel you trust.

Are scenario scripts sandboxed?

No. They are authored by administrators through the UI and executed as ordinary Groovy, without a sandbox or a method allowlist. Treat write access to scenarios as equivalent to shell access on the server, and hand out ROLE_ADMIN accordingly.

Does the voice assistant send my house to a third party?

When enabled, yes — the transcript and a catalogue of your peripheral, zone and scenario names go to whichever LLM provider you configured, using your own API key and account. No audio leaves the browser (speech-to-text runs locally), and no device data is sent beyond the names and states the command needs. If that is not acceptable, leave the feature off; it is off by default.

What should I back up?

The PostgreSQL database and the configuration repository. Between them they are the whole installation. Schema changes are additive (dbCreate = update never drops anything), so a rollback means restoring a dump.

Using it

Can one instance manage two houses?

Not really. Zones nest, so you can model a second building as a top-level zone, but there is no tenant isolation — every user with the right role sees everything. Run two instances instead.

What happens when the internet goes down?

Local control keeps working: devices, broker and server are all on your LAN. Cloud-backed widgets (solar, heat pump, weather, mower) stop updating and say so; the jobs behind them retry. Remote access and Telegram obviously stop until connectivity returns.

Does the app work offline?

The PWA caches its shell, so it opens instantly and shows last-known state, then reconnects. It cannot control anything while it has no route to the server.

Which languages does the interface support?

English and Romanian, chosen per user and stored on the account. The same setting drives speech recognition and spoken replies. Adding a language means shipping a locale file; the backend needs no change.

Is there an iOS app?

No native one. The PWA installs on iOS from Safari and covers everything except hands-free wake-word listening, which only the Android client does.

Why Grafana for charts instead of building them in?

The data is in PostgreSQL and Grafana is very good at querying PostgreSQL. Rather than reimplement it badly, myHAB embeds a dashboard where long-range analysis is wanted and keeps its own widgets focused on live state.

How do I report a bug or ask for a feature?

GitHub issues. A description of your device model, the relevant MQTT topics and what the raw monitor showed will get you an answer considerably faster than a screenshot of the UI.