LocalTuya

Last reviewed Sep 13, 2026 · 744 words

Every Tuya device you want LocalTuya to control needs its local key, and the only sanctioned way to get one is a developer account on the Tuya IoT platform, whose free trial plan expires and has to be renewed by hand. Do that step first, before HACS, before the integration, because the hour you spend in Tuya's developer console is the whole difficulty of this project. Once the keys are in hand, LocalTuya turns cloud-dependent switches and bulbs into devices that answer in tens of milliseconds from the LAN and keep working when your internet does not.

What this repository actually is

The repository is xZetsubou/hass-localtuya, a maintained fork of the original LocalTuya custom integration for Home Assistant. There is a separate, unrelated project called Tuya Local by a different author, and the two are routinely confused, including by directory listings. This one is the fork that added cloud-assisted device discovery, automatic entity configuration for many device types, and support for the newer 3.4 and 3.5 protocol versions. It is a Home Assistant custom integration, not a standalone daemon: there is nothing to run outside HA, and the 128 MB in the listing is HA's own overhead rather than an extra service.

Getting keys: the Tuya IoT console is the real work

The sequence: create a Tuya IoT platform account, create a Cloud project, link your Smart Life or Tuya app account to it, and authorise the IoT Core and device APIs. LocalTuya then uses that project's Access ID and secret to pull the device list and local keys for you. Two gotchas. The free IoT Core plan is time-limited and needs renewing in the console, which is when people's setups silently stop discovering new devices. And re-pairing a device generates a new local key, so a factory reset means fetching the key again. Keys for existing devices keep working locally when the cloud project lapses; only discovery and key retrieval depend on it.

One local connection per device

Tuya firmware generally accepts a single persistent local connection. If LocalTuya holds it, the phone app on the same LAN will flake, and if some other tool grabs it, LocalTuya's entities go unavailable. Give each device a DHCP reservation so the IP in the integration stays valid, and keep other LAN pollers (a second HA instance, a script, the official app on the same WiFi) off the devices you hand to LocalTuya. Most flapping-entity reports trace back to this.

Entities, data points and manual configuration

Tuya devices expose numbered data points: DP 1 might be the power switch, DP 20 the brightness. For common device classes this fork maps DPs automatically. For odd hardware (a dehumidifier, a curtain motor, a 4-gang switch with unusual firmware) you will map DPs by hand, and the integration's device dialog lets you pick DP IDs from a live list. Budget 10 minutes per unusual device and keep notes. The mapping lives in HA's config entries, so it survives restarts and is included in HA backups.

Or skip Tuya's firmware altogether

Local control of a device still running Tuya firmware is a compromise. The alternative is replacing the firmware with Tasmota or ESPHome, which removes the cloud and the local-key dance permanently. That path only exists if the device has an ESP8266 or ESP32 inside; a large share of Tuya hardware sold since about 2021 uses Beken or Realtek chips, where you need different community firmware and often a soldering iron. If you are buying new, buy hardware that ships open or is known to be flashable. LocalTuya is the right tool for the pile of Tuya kit you already own.

What I'd do

Set up the Tuya IoT project first, pull every key in one sitting, and store the list of keys somewhere safe. Install the integration through HACS as a custom repository, reserve IPs for every device, and remove the official cloud Tuya integration for the devices you move over so you do not end up with duplicate entities. Put a calendar reminder in for renewing the IoT Core trial. For anything you buy from here on, prefer devices that can run ESPHome. If you are new to Home Assistant, the first month guide is where I would get comfortable before touching custom integrations at all.