Tuya Devices in Home Assistant: Cloud vs Local Control

Adding Tuya devices in Home Assistant takes about ten minutes: install the official Tuya integration, scan a QR code with the Smart Life app, and your plugs, bulbs and sensors appear. That route runs through Tuya's cloud, so a local-control integration is the fix if you want speed and offline resilience.

Tuya makes the chips and firmware inside hundreds of budget brands, so the odds are high that at least one cheap plug, bulb or sensor in your house is a Tuya device. The catch is that the cloud and local routes behave quite differently. This guide walks through both, in order, and explains how to choose between them.

What do you need before you start?

• Home Assistant: a running instance on your home network. The Tuya integration ships with Home Assistant core, so there is nothing extra to install for the cloud route.
• A Tuya-based app: the Tuya Smart or Smart Life app, with your devices already paired and working there. Home Assistant's documentation names both apps as supported.
• Your Tuya user code: found inside the app under Me, then the cog, then Account and Security.
• For the local route: HACS or the built-in Marketplace (see our guide to the HACS Marketplace in Home Assistant 2026.11), plus a way to give each device a fixed IP address on your router.
• Wi-Fi Tuya devices only: Bluetooth devices need a Tuya Bluetooth or multi-mode gateway, covered under common problems below.

Should you use the cloud integration or local control?

Use the official cloud integration first, because it is the simplest and supported by the Home Assistant project, then add local control only for devices where speed or reliability matters. The two are not mutually exclusive, but they are very different in how they work.

Home Assistant classifies the official Tuya integration as Cloud Push, and its documentation states that the integration only communicates with the Tuya cloud. If your broadband drops, or Tuya has an outage, those entities stop working even though the bulb is a few metres from your router. The documentation also notes that Tuya's SDK does not expose all the functionality available in Smart Life, so some device features never appear.

Local integrations talk to the device over your own network instead. The Tuya Local project describes itself as local support for Tuya devices that can improve speed and reliability and may unlock features the cloud API does not expose. LocalTuya, by contrast, is a custom integration whose own documentation says the cloud is optional and used only to pre-fill setup fields.

Step 1: Find your Tuya user code

Open the Smart Life or Tuya Smart app on your phone, tap Me, open the settings cog, then choose Account and Security. Your user code is shown there. Keep the app open, because you will need its scanner in the next step.

Check now that every device you want in Home Assistant is online in the app. If a plug shows as offline there, it will not appear in Home Assistant either, and it is much easier to fix the Wi-Fi problem before you start.

Step 2: Add the official Tuya integration

In Home Assistant go to Settings, then Devices and services, and add the Tuya integration. Home Assistant may also discover it automatically and offer it on the dashboard. Enter your user code when prompted.

A QR code is then shown on screen. In the Smart Life app, use the plus button or Add Device and choose Scan, then scan the code and approve the login. Home Assistant creates entities for every supported device on your account. Scenes you built in the Tuya app are brought across too.

Step 3: Check what each device exposes

Open each new device in Home Assistant and compare its entities to what the app offers. Home Assistant supports all its platforms with the Tuya integration except lock and remote, so a Tuya smart lock or IR remote will not behave the way you expect. For IR, see our roundup of the best IR blasters for Home Assistant instead.

If a device shows few or no controls, download its diagnostics from the device page and look at the status, status_range and function keys. When all three are empty, Home Assistant can only see scenes created in the Tuya app for that device, and it is a candidate for the local route below.

Step 4: Reserve a fixed IP address for each local device

Before installing a local integration, give every Tuya device you intend to control locally a DHCP reservation in your router so its IP address never changes. Local integrations connect to a specific address, and a device that moves to a new address will drop offline until you edit the configuration.

If your network is more than a basic ISP router, our Home Assistant network setup guide covers sensible VLAN and reservation choices for IoT devices. Keep the Tuya devices on the same network, or a network Home Assistant can reach directly, because local control does not work through a cloud relay.

Step 5: Install Tuya Local from the Marketplace or HACS

On Home Assistant 2026.11 or later, the Tuya Local project says you can install it from the built-in Marketplace; on earlier versions install it through HACS, or add the repository as a custom repository. Restart Home Assistant if prompted, then add Tuya Local from the Integrations page. Our custom components guide explains the general process and the risks of unreviewed code.

Tuya Local supports a long list of device configurations. Its documentation describes it as covering over 1,000 device types, mainly Wi-Fi devices, with only limited support for devices behind hubs. Check the supported devices list for your exact model before spending time on it.

Step 6: Add a device with cloud-assisted setup

When you add a device, Tuya Local offers a cloud-assisted route: you log in with the Tuya or Smart Life app and it fills in the device list and connection details, without needing a Tuya IoT developer account. Pick your device from the list, confirm its IP address, and let the protocol version stay on auto unless it fails to connect.

The alternative is to enter the device ID, IP address or hostname, and local key by hand. The documented protocol options run from 3.1 to 3.5, plus 3.22. One warning: the local key changes every time you re-pair the device in the manufacturer's app, so do not re-pair a device after you have set it up locally without updating the key.

Step 7: Test it with the internet unplugged

Switch off your router's WAN connection, or block the device's internet access, and toggle the device from Home Assistant. If it responds instantly, local control is working. If it does not, the integration is probably still depending on the cloud or the device is not reachable on your LAN.

Once it works, remove the matching cloud entities from the official integration, or disable them, so you do not have two copies of the same plug in your dashboards and automations. Then build a simple automation to prove the point, for example:

automation:
  - alias: "Lamp off at midnight"
    triggers:
      - trigger: time
        at: "00:00:00"
    actions:
      - action: switch.turn_off
        target:
          entity_id: switch.hallway_lamp

Replace the entity ID with your own. Because the command now goes over your LAN, it should keep firing during an internet outage.

Why does my Tuya device only work in one place at a time?

Many Tuya devices accept only one local connection at once, so a second client can lock out the first. The Tuya Local documentation says that if you have connection problems you should close other local Tuya integrations, close mobile apps on your network, and stop any other software connecting to the devices.

That means you cannot run LocalTuya and Tuya Local against the same plug at the same time. Pick one local integration per device, and leave the official cloud integration for devices you are not controlling locally. A phone with the Smart Life app open can also grab the connection, so close it while testing.

Common problems and fixes

Home Assistant keeps asking me to sign in again: this can happen when Tuya updates the terms and conditions on its developer platform. Log in to iot.tuya.com, accept the terms, restart Home Assistant, then reconfigure the Tuya integration.

A new device does not appear: the documentation says new devices only show up after you reload the integration, so reload it from the Devices and services page.

Bluetooth Tuya devices are unavailable: the official integration only talks to the Tuya cloud and does not use Home Assistant's Bluetooth integration or Bluetooth proxies. Add the device through a Tuya Bluetooth or multi-mode gateway rather than straight to your phone, and confirm both show online in the app. Our Bluetooth proxy guide explains why proxies do not help here.

A local device stopped working after a firmware update: Tuya Local warns that firmware updates or incompatible variants sold under the same model name may fail. File an issue with the device's data-point logs, or contribute a config.

The local key no longer works: you probably re-paired the device. Fetch the new key through the cloud-assisted setup and update the entry.

What should you do next?

Pick your five most-used Tuya devices and move only those to local control. Leave the rest on the cloud integration, where setup is a one-off QR scan. If you are buying new devices and have the choice, Zigbee or Matter devices avoid the problem entirely, because they were designed to work locally from the start.