Skip to content
Stand with Ukraine flag
Star
 
Pricing Try it now

Remote Integrations

Remote Integrations allow reliable data streaming from multiple devices in the local area network (LAN) to the ThingsBoard platform in the cloud. They are helpful if you have, for example, a local MQTT broker or OPC-UA server with no external IP address that is not reachable from where your ThingsBoard platform is installed. The remote integration initiates a connection to these servers, pulls the data, stores it locally, and then streams it to the ThingsBoard instance.

Although this approach requires some additional steps in the deployment process, it allows integration with servers and devices deployed in the LAN. A separate integration process improves isolation level and performance.

The remote integration approach enables tenants to launch plain TCP and UDP integrations. Those two integrations are unique because they start a server that binds to a specific port. Since ThingsBoard is a multi-tenant environment, TCP and UDP integrations cannot run as part of the core service due to possible port collisions between tenants. That is why each tenant needs to launch a TCP/UDP integration as a remote one. The same applies to any custom integration that the tenant creates.

Before proceeding, check whether the IoT Gateway already supports your protocol — it provides built-in connectors for MQTT, OPC-UA, Modbus, BACnet, and others. If a connector covers your use case, the gateway is simpler to deploy.

If a remote integration is the right choice, the essential step is enabling the Execute remotely toggle in the integration’s Connection settings. This generates the Integration key and Integration secret required to launch the integration as a standalone process.

It is possible to execute any ThingsBoard Integration separately from the ThingsBoard instance.

This guide contains step-by-step instructions on how to launch an MQTT remote integration that connects to a local MQTT broker and pushes data to ThingsBoard.

You can find additional information about the ThingsBoard Platform integrations feature in the Integrations documentation.

ThingsBoard configuration

Section titled “ThingsBoard configuration”

We assume you already have a tenant administrator account on your own ThingsBoard PE instance or ThingsBoard Cloud.

Create remote integration in ThingsBoard

Section titled “Create remote integration in ThingsBoard”

Let’s create a remote MQTT integration in ThingsBoard that will connect to the local broker using port 1883 and subscribe to all topics.

  1. Go to Integrations center → Integrations and click the ”+” icon to add a new integration.
  2. Select the Integration type: MQTT and set the Name to “MQTT remote integration”. Click Next.
  3. Add a default Uplink data converter. The new converter will contain the necessary code to convert incoming data. Click Next.
  4. Leave the Downlink data converter field empty. Click Skip.
  5. On the Connection step:
    • Set Host to thingsboard.cloud (or your ThingsBoard PE host) and Port to 1883.
    • Subscribe to all topics by entering # in the Topic field.
    • Select an MQTT QoS level (default: 0 — At most once).
    • Enable the Execute remotely toggle. The Integration key and Integration secret fields will appear — copy and save both values, as you will need them when launching the remote integration process.
  6. Expand Advanced settings and uncheck the Clean session parameter. Many brokers do not support sticky sessions and will silently close the connection if this option is enabled.
  7. Click Add to create the integration.

Choose your platform and install

Section titled “Choose your platform and install”

One can install ThingsBoard Integration via Docker, Debian, or RPM packages.

Docker on Linux/Mac

Section titled “Docker on Linux/Mac”

Install Docker CE

Pull the Docker image:

Terminal window
docker pull thingsboard/tb-pe-http-integration:4.3.1.1PE

Create a volume for the integration logs (799 is the user ID of the ThingsBoard non-root Docker user):

Terminal window
mkdir -p ~/.tb-pe-http-integration-logs && sudo chown -R 799:799 ~/.tb-pe-http-integration-logs

Run the integration:

Terminal window
docker run -it -p 8082:8082 -v ~/.tb-pe-http-integration-logs:/var/log/tb-http-integration \
-e "RPC_HOST=thingsboard.cloud" -e "RPC_PORT=9090" \
-e "INTEGRATION_ROUTING_KEY=YOUR_ROUTING_KEY" -e "INTEGRATION_SECRET=YOUR_SECRET" \
--name my-tb-pe-http-integration --restart always thingsboard/tb-pe-http-integration:4.3.1.1PE

Where:

  • thingsboard.cloud — host name of your ThingsBoard PE instance;
  • 9090 — integration gRPC port, configured via INTEGRATIONS_RPC_PORT in thingsboard.yml;
  • YOUR_ROUTING_KEY — integration key obtained in Create remote integration in ThingsBoard;
  • YOUR_SECRET — integration secret obtained in Create remote integration in ThingsBoard;
  • -p 8082:8082 — maps the host port 8082 to the container’s HTTP integration port;
  • -v ~/.tb-pe-http-integration-logs:/var/log/tb-http-integration — mounts the host directory to the integration logs directory;
  • --restart always — automatically starts the integration after system reboot or failure.

Logs are written to ~/.tb-pe-http-integration-logs. After startup you should see INFO log messages with the latest integration configuration received from the server.

Reattach, stop, and start commands:

Terminal window
docker attach my-tb-pe-http-integration
Terminal window
docker stop my-tb-pe-http-integration
Terminal window
docker start my-tb-pe-http-integration

Advanced configuration

See the configuration YAML below for the full list of configuration parameters, corresponding environment variables, and their default values. For example, the default client ID used in integration debug messages is remote and can be changed by setting the RPC_CLIENT_ID environment variable.

server:
  # Server bind address
  address: "${HTTP_BIND_ADDRESS:0.0.0.0}"
  # Server bind port
  port: "${HTTP_BIND_PORT:8082}"


integration:
  routingKey: "${INTEGRATION_ROUTING_KEY:PUT_YOUR_ROUTING_KEY_HERE}"
  secret: "${INTEGRATION_SECRET:PUT_YOUR_SECRET_HERE}"
  # Allows connection to the localhost resources. For example, local MQTT broker, etc.
  allow_local_network_hosts: "${INTEGRATION_ALLOW_LOCAL_NETWORK_HOSTS:true}"
  statistics:
    # Enable/disable integration statistics
    enabled: "${INTEGRATION_STATISTICS_ENABLED:true}"
    # Send statistics interval. Default value is once per hour
    persist_frequency: "${INTEGRATION_STATISTICS_PERSIST_FREQUENCY:3600000}"


storage:
  # Location of the folder to store data files
  data_folder_path: "${INTEGRATION_STORAGE_DATA_FOLDER_PATH:./}"
  # Max amount of data files to maintain
  max_file_count: "${INTEGRATION_STORAGE_MAX_FILE_COUNT:100}"
  # Max records per data file
  max_records_per_file: "${INTEGRATION_STORAGE_MAX_RECORDS_PER_FILE:30}"
  # Max records between persistence of data file
  max_records_between_fsync: "${INTEGRATION_STORAGE_MAX_RECORDS_BETWEEN_FSYNC:100}"
  # Size of the upload chunk
  max_read_records_count: "${INTEGRATION_STORAGE_MAX_READ_RECORDS_COUNT:50}"
  # Sleep interval while no new records
  no_read_records_sleep: "${INTEGRATION_STORAGE_NO_READ_RECORDS_SLEEP:1000}"


executors:
  # Size of the thread pool to handle incoming messages and tasks
  thread_pool_size: "${EXECUTORS_SIZE:1}"
  # Timeout to reconnect to ThingsBoard
  reconnect_timeout: "${EXECUTORS_RECONNECT_TIMEOUT:3000}" # in milliseconds


rpc:
  # Host of the ThingsBoard server
  host: "${RPC_HOST:thingsboard.cloud}"
  # Port of the ThingsBoard server
  port: "${RPC_PORT:9090}"
  # No reply timeout
  timeout: "${RPC_TIMEOUT:5}" # Timeout in seconds for channel termination
  # ID of the RPC client
  client_id: "${RPC_CLIENT_ID:remote}"
  ssl:
    # SSL enabled/disabled
    enabled: "${RPC_SSL_ENABLED:false}"
    # SSL certificate
    cert: "${RPC_SSL_CERT:roots.pem}"


js:
  evaluator: "${JS_EVALUATOR:local}"
  # Built-in JVM JavaScript environment properties
  local:
    # Use Sandboxed (secured) JVM JavaScript environment
    use_js_sandbox: "${USE_LOCAL_JS_SANDBOX:true}"
    # Specify thread pool size for JavaScript sandbox resource monitor
    monitor_thread_pool_size: "${LOCAL_JS_SANDBOX_MONITOR_THREAD_POOL_SIZE:4}"
    # Maximum CPU time in milliseconds allowed for script execution
    max_cpu_time: "${LOCAL_JS_SANDBOX_MAX_CPU_TIME:5000}"
    # Maximum allowed JavaScript execution errors before JavaScript will be blacklisted
    max_errors: "${LOCAL_JS_SANDBOX_MAX_ERRORS:3}"


service:
  type: "${TB_SERVICE_TYPE:tb-integration}"

Troubleshooting

Docker on Windows

Section titled “Docker on Windows”

Install Docker Desktop for Windows

Windows users should use Docker managed volumes for integration logs. Open Docker Quickstart Terminal and create the volume before running the container.

Create a Docker volume:

Terminal window
docker volume create tb-pe-http-integration-logs

Run the integration:

Terminal window
docker run -it -v tb-pe-http-integration-logs:/var/log/tb-http-integration `
-e "RPC_HOST=thingsboard.cloud" -e "RPC_PORT=9090" `
-e "INTEGRATION_ROUTING_KEY=YOUR_ROUTING_KEY" -e "INTEGRATION_SECRET=YOUR_SECRET" `
--name my-tb-pe-http-integration --restart always thingsboard/tb-pe-http-integration:4.3.1.1PE

Where:

Reattach, stop, and start commands:

Terminal window
docker attach my-tb-pe-http-integration
Terminal window
docker stop my-tb-pe-http-integration
Terminal window
docker start my-tb-pe-http-integration

Advanced configuration

See the advanced configuration yml in the Docker on Linux/Mac section above.

Troubleshooting

Ubuntu Server

Section titled “Ubuntu Server”

Install Java 17 (OpenJDK):

Terminal window
sudo apt update && sudo apt install openjdk-17-jdk-headless

Configure the default Java version:

Terminal window
sudo update-alternatives --config java

Verify the installation:

Terminal window
java -version

Expected output:

openjdk version "17.x.xx"
OpenJDK Runtime Environment (...)
OpenJDK 64-Bit Server VM (...)

Download the installation package:

Terminal window
wget https://dist.thingsboard.io/tb-http-integration-4.3.1.1pe.deb

Install the integration as a service:

Terminal window
sudo dpkg -i tb-http-integration-4.3.1.1pe.deb

Open the configuration file:

Terminal window
sudo nano /etc/tb-http-integration/conf/tb-http-integration.conf

Locate the following block and set your connection parameters (uncomment the export statements):

Terminal window
# UNCOMMENT NEXT LINES AND PUT YOUR CONNECTION PARAMETERS:
export RPC_HOST=thingsboard.cloud
export RPC_PORT=9090
export INTEGRATION_ROUTING_KEY=YOUR_INTEGRATION_KEY
export INTEGRATION_SECRET=YOUR_INTEGRATION_SECRET

Start the integration:

Terminal window
sudo service tb-http-integration start

Logs are written to /var/log/tb-http-integration/.

CentOS/RHEL Server

Section titled “CentOS/RHEL Server”

Install Java 17 (OpenJDK):

Terminal window
sudo dnf install java-17-openjdk-headless

Configure the default Java version:

Terminal window
sudo update-alternatives --config java

Verify the installation:

Terminal window
java -version

Expected output:

openjdk version "17.x.xx"
OpenJDK Runtime Environment (...)
OpenJDK 64-Bit Server VM (build ...)

Download the installation package:

Terminal window
wget https://dist.thingsboard.io/tb-http-integration-4.3.1.1pe.rpm

Install the integration as a service:

Terminal window
sudo rpm -Uvh tb-http-integration-4.3.1.1pe.rpm

Open the configuration file:

Terminal window
sudo nano /etc/tb-http-integration/conf/tb-http-integration.conf

Locate the following block and set your connection parameters:

Terminal window
# UNCOMMENT NEXT LINES AND PUT YOUR CONNECTION PARAMETERS:
export RPC_HOST=thingsboard.cloud
export RPC_PORT=9090
export INTEGRATION_ROUTING_KEY=YOUR_INTEGRATION_KEY
export INTEGRATION_SECRET=YOUR_INTEGRATION_SECRET

Start the integration:

Terminal window
sudo service tb-http-integration start

Logs are written to /var/log/tb-http-integration/.

Remote integration configuration

Section titled “Remote integration configuration”

Remote integration configuration is done via the ThingsBoard UI — there are no deployment-specific steps. Explore guides related to specific integrations:

Remote integration troubleshooting

Section titled “Remote integration troubleshooting”

Review the log files. Their location depends on the platform and installation method used and is mentioned in the installation steps above.

© 2026 The ThingsBoard Authors