25 guides · the v1.0.6 release
LocalAssistant docs
Blinds, heat pumps, radiators, cameras and energy on one page, on a server you run. A few integrations done properly instead of thousands done loosely.
Introduction
Your blinds, heat pumps, radiators, cameras and energy on one page, on a server you run. A small, self-hosted alternative to Home Assistant that installs on your phone like an app.
Contributing
The long-form documentation lives in docs/. This file is the short version: what you need to get a change landed.
Getting started
Run LocalAssistant and claim the instance.
Introduction
LocalAssistant controls a household's blinds and heat pumps from one page, on a server you run. It does a few integrations properly instead of thousands loosely: Tuya blinds and Bambu Lab printers over the local network, and Mitsubishi Electric heat pumps through MELCloud.
Install
LocalAssistant is one container. Its /data volume holds the SQLite database: accounts, devices, their encrypted keys and installed plugins. Back it up with AUTH_SECRET.
Configuration
Environment variables cover what the server needs at boot. Everything else (devices, invites, sign-in methods, email) is set in the app's admin area.
First run
A fresh instance sends every page to the setup screen. It asks for a six-digit code only the server's log shows, valid 15 minutes:
Health and updates
Back up LocalAssistant from the server, not the app: the /data volume holds everything (the SQLite database, installed integrations and camera recordings). Snapshot or copy it with the rest of the server's backups, and keep AUTH_SECRET with it: the secrets in the database are encrypted with it. To copy a running database safely, use sqlite3 /data/localassistant.sqlite ".backup /path/to/copy.sqlite", or stop the container first.
Devices
Getting each integration's credentials and what it controls.
Integrations
Every kind of device LocalAssistant talks to comes from an integration: a small plugin hosted on GitHub, GitLab, Gitea or Forgejo, or kept in a folder. The official ones (Tuya blinds, Mitsubishi through MELCloud or ESPHome, Zigbee2MQTT, Shelly, cameras, Frigate, Bambu Lab printers, Dreame robot vacuums, Renault cars, Linky, MQTT discovery and Home Assistant) ship with LocalAssistant. Anyone can publish more, and an admin adds them from a link, without an account anywhere.
Tuya blinds
LocalAssistant talks to each blind directly on your network with the Tuya local protocol, encrypted with the blind's own local key. The Tuya cloud is only needed once, to read that key.
Mitsubishi heat pumps
Mitsubishi Electric units with a Wi-Fi adapter (MAC-567IF and friends) are driven through MELCloud, with the account the MELCloud app uses. The password is stored encrypted with AUTH_SECRET and never shown again.
Bambu Lab printers
LocalAssistant talks to a Bambu Lab printer (P1P, P1S and the other models with the same LAN protocol) over its local MQTT broker, with the printer's access code. No Bambu account is involved.
Zigbee and Shelly
Door and window sensors, radiator valves, relays, metering plugs and the ZLinky reader come in through Zigbee2MQTT, and Shelly meters through the same MQTT broker. LocalAssistant only talks to the broker: pair devices in Zigbee2MQTT, they show up here on their own.
Cameras
Any camera with a local RTSP stream: a Tapo with a camera account set in its app, a Reolink, most ONVIF cameras. Devices, Add a device, Cameras (RTSP), Add the camera with its RTSP address (stored encrypted). The eye shows what you typed. Test it first checks the address before anything is saved: that it reads as one (an @, / or # in the password has to be written %40, %2F, %23), that something answers on its port, and what stream ffprobe finds there, or the camera's answer when it refuses (wrong password, wrong path).
More devices
Devices, Add a device, Dreame robot vacuums, sign in with the Dreamehome app's email, password and region. The robots on the account come in with their state and battery, and start, pause, stop and dock from their card. LocalAssistant signs in the way the Dreamehome app does, over plain TLS; Dreame can refuse clients other than its app at any time, and the error then says so.
AI apps
Claude, ChatGPT and Gemini can see your house and drive its devices through LocalAssistant's MCP server at /mcp. Each person connects their own app; it acts as them.
Mobile app
LocalAssistant has a native app for Android and iPhone, built with Kotlin Multiplatform. It shows the house, drives devices, watches cameras, makes and sets scenes, runs routines, talks to the assistant and reports the phone's battery and, if you share it, whether you're home. The web app still installs on phones too.
Around the house
What the house does on its own, and how it shows.
Weather
Home opens on the time and the weather: the temperature, what it feels like, today's low and high, sunrise and sunset. The weather comes from Open-Meteo, free and without a key.
Automations
The server runs every routine, whether or not anyone has the app open: the worker checks the clock-driven ones once a minute, and device routines the moment a device reports. Everyone signed in can add, change, run or switch one off. Routines has three tabs: the routines, the scenes, and the history of every run.
Notifications
LocalAssistant sends push notifications to the phones, tablets and computers each person turned them on for: Account, Notifications, Turn on for this device. On an iPhone or iPad, add the app to the Home Screen first.
Dashboards
A dashboard is a page of your own: the devices, scenes and graphs you use together, in the order you want. Only you see yours; everyone makes their own.
History and logbook
The worker keeps 30 days of what the devices did, without anyone having the app open.
Energy
Energy charts what the house and each appliance used, per day over the last 30 days and per month over the last 12. The worker snapshots every meter's counter every 15 minutes and keeps about two years.
Wall panel
A screen for a tablet on the wall or a Shelly Wall Display: the clock, the weather, the doors and windows left open, big open and close buttons for each room's blinds with its temperature, and the heat pumps, valves and switches. It keeps the screen on while it's showing, and refreshes every 20 seconds.
Contributing
Working on LocalAssistant itself.
Development
The dev server migrates ./data/localassistant.sqlite and starts the worker under watch. Delete the file to start over; the setup code is in the dev server's output.
Writing an integration
An integration is a GitHub repository (or a folder in one) with a localassistant-plugin.json manifest and the code it names. LocalAssistant builds the setup forms from the manifest, shows each device on one of its built-in cards, and calls your code to connect, find, read and drive devices.