gbiccard/tuya-cube-bridge repository overview

⁠Tuya CUBE Bridge

Connect supported Tuya and BNETA devices to SONOFF iHost / eWeLink CUBE with a lightweight Docker bridge.

The bridge discovers devices through Tuya Cloud, controls supported plugs and climate sensors over the LAN, and exposes them in iHost. Supported IR air conditioners use Tuya Cloud control. Custom JSON profiles allow additional compatible device mappings.

⁠Supported devices

Compatibility depends on the supplied device profiles and datapoint mappings; not every Tuya or BNETA model is supported. IR state reflects remembered commands, not physical confirmation from the air conditioner.

⁠Image tags

All of these version 0.4.2 images use Alpine Linux. Docker selects the matching architecture when pulling a combined tag. This release does not include an AMD64 image.

docker pull gbiccard/tuya-cube-bridge:0.4.2

⁠Requirements

• iHost / eWeLink CUBE with a CUBE API token.
• A Tuya IoT Cloud project linked to the app account containing your devices, with access ID, secret and region configured.
• Network access from the bridge to the devices and iHost, and from iHost back to the bridge on port 8099.
• Host networking for LAN discovery. Docker Desktop must have host networking enabled when used for this setup.

Cloud credentials provide inventory and local keys. Local device control uses the LAN where supported; IR air conditioner control requires Tuya Cloud.

⁠Quick start with Docker Compose

Create a .env file beside your Compose file. Replace the example addresses and credentials:

IHOST_BASE_URL=http://192.168.1.100
IHOST_TOKEN=replace-with-cube-api-token
PUBLIC_BASE_URL=http://192.168.1.100:8099
TUYA_CLOUD_ACCESS_ID=replace-with-tuya-access-id
TUYA_CLOUD_ACCESS_SECRET=replace-with-tuya-access-secret
TUYA_CLOUD_REGION=eu
TUYA_LAN_PREFIXES=192.168.1
BRIDGE_MODE=inventory
PERSIST_LOCAL_KEYS=false

IHOST_BASE_URL is the iHost address. PUBLIC_BASE_URL is the address of the machine running this container, reachable from iHost. They use the same host address when the bridge runs on iHost, and different addresses when the bridge runs on another machine.

Use this compose.yml:

services:
  tuya-cube-bridge:
    image: gbiccard/tuya-cube-bridge:0.4.2
    container_name: tuya-cube-bridge
    restart: unless-stopped
    init: true
    network_mode: host
    env_file:
      - .env
    read_only: true
    pids_limit: 128
    tmpfs:
      - /tmp:rw,noexec,nosuid,size=64m
    volumes:
      - bridge-data:/data
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true

volumes:
  bridge-data:

docker compose pull
docker compose up -d
docker compose logs --tail=100 tuya-cube-bridge

Start in inventory mode to review device discovery. Open http://<bridge-host>:8099/settings. The management token is generated in /data/admin-token unless you configure ADMIN_TOKEN with at least 32 random characters. Retrieve the generated token locally with:

docker exec tuya-cube-bridge cat /data/admin-token

Keep that token private. Once inventory is correct, stop any other integration controlling the same Tuya devices, change BRIDGE_MODE to active, and recreate the container with docker compose up -d. Test iHost control and device-state updates.

For installation through iHost's Docker interface, use the same image, host networking, environment variables and a persistent mount at /data. That directory must be writable by container UID 1000. Keep existing data mounts when upgrading; the named volume above is for a new installation.

⁠Operation and recovery

• Reconnects local devices after outages and rediscovers changed addresses.
• Reports local device availability after fresh telemetry. iHost controls how offline tiles are displayed and may hide them.
• Avoids disk writes for unchanged state and live polling timestamps.
• Shares discovery work and suppresses duplicate state reports while retrying failed reports.
• Runs as a non-root user and uses a lightweight wget health check.

If iHost control callbacks are rejected, verify the bridge address and the actual callback source IP. CALLBACK_ALLOWED_IPS can allow a known proxy/NAT source when necessary; see the source documentation. Run only one active bridge against the same devices.

⁠Source and documentation

• Source code and setup guide⁠
• Release notes⁠
• Alpine build and deployment guide⁠
• Custom device profiles⁠
• Issues⁠