Skip to content

Cookie preferences

We use cookies for our own analytics, to see how our campaigns perform and, if you allow it, to load content from other services such as the Google site search. We never sell your data. Necessary cookies keep the site working and cannot be switched off. See our Cookie Policy for details and our Privacy Policy for how we handle personal data.

Security, load balancing and remembering your cookie choice.

Show us which pages people read, how they find the site and where they get stuck, so we can improve it (Google Analytics, Microsoft Clarity).

Show us which of our ad campaigns bring visitors to the site and remember the campaign or partner link you arrived from (Google Ads, LinkedIn, Meta, partner program). We do not use these cookies to build advertising profiles.

Load the site search from Google when you use it. Google sets its own cookies and shows ads in the search results.
© 2026 The ThingsBoard Authors
180 Try for free

ThingsBoard Cloud

Choose your data region

Your data stays in the region you choose, for residency and compliance. No credit card required.

North America Data stored in North America Europe Data stored in the European Union

Rather run it yourself? Install on your own servers

Remote Integrations

Any ThingsBoard integration can run remotely, as a separate service outside the ThingsBoard Edge process. The service runs on the same machine as the Edge or on another machine that can reach the Edge over the network. This guide sets up a remote HTTP integration as an example.

Remote integration architecture diagram Remote integration architecture diagram

Prerequisites

Section titled “Prerequisites”
  • A ThingsBoard server with tenant administrator access. The templates are created there.
  • A ThingsBoard Edge instance connected to the server.
  • A machine for the remote integration service with Docker, or with Ubuntu or CentOS/RHEL for the package install. Port 8082, the default port of the remote HTTP integration, must be open there.
  • curl to simulate a device.

Configure the ThingsBoard server

Section titled “Configure the ThingsBoard server”
Section titled “Step 1. Create the uplink converter”

The uplink converter decodes incoming device data into ThingsBoard telemetry and attributes.

  1. On the server, go to Edge management > Templates and open the Converter tab. Click Add data converter and select Create new converter.

  2. Set Converter type to Uplink, select HTTP as the Integration type, and enter the name HTTP remote uplink converter.

  3. In Main decoding configuration, select JS, paste the following script, and click Add:

    // decode payload to JSON
    var data = decodeToJson(payload);
    var deviceName = data.deviceName;
    

    var result = {
      deviceName: deviceName,
      deviceType: 'default',
      attributes: {
        model: data.model,
      },

Step 2. Create the remote integration template

Section titled “Step 2. Create the remote integration template”

  1. On the server, go to Edge management > Templates, open the Integration tab, and click Add integration.

  2. On the Basic settings step, select HTTP as the Integration type and enter the name HTTP Demo Remote. Click Next.

  3. On the Uplink data converter step, select Select existing, choose HTTP remote uplink converter, and click Next. You can also create the converter here with Create new.

  4. On the Downlink data converter step, keep Skip selected and click Skip.

  5. On the Connection step, set Base URL to ${{remoteHttpIntegrationUrl}} and turn on Execute remotely. ThingsBoard shows the generated Integration key and Integration secret. Click Add.

The ${{remoteHttpIntegrationUrl}} placeholder is replaced with the value of the Edge server attribute of the same name when the integration is sent to the Edge. See Configuration placeholders.

Step 3. Save the integration credentials

Section titled “Step 3. Save the integration credentials”

The remote service identifies itself with the Integration key and Integration secret of the template.

  1. On the Integration tab of Edge management > Templates, open the integration you created.
  2. Expand Execute remotely and copy the Integration key and the Integration secret with the copy buttons next to them.

Step 4. Assign the integration to the Edge

Section titled “Step 4. Assign the integration to the Edge”

Add the remoteHttpIntegrationUrl attribute first. It holds the address of the machine where the remote HTTP integration service will run. Without it, the assignment dialog warns Edge has missing attribute(s) and the Edge receives the literal placeholder.

  1. On the server, go to Edge management > Edges and click the Edge.

  2. On the Attributes tab, with the Server attributes scope selected, click +.

  3. In the Add attribute dialog, enter remoteHttpIntegrationUrl as the key and http://IP:8082 as the value, where IP is the address of the remote integration machine. Click Add.

  4. On the Details tab, click Manage integrations, then Assign to edge (+). Select HTTP Demo Remote and click Assign.

  5. Log in to the Edge and go to Integrations > Integrations. Open HTTP Demo Remote. Base URL shows the attribute value instead of the placeholder.

Install the remote integration service

Section titled “Install the remote integration service”

The service connects to the Edge through the integration RPC port, 9090 by default (INTEGRATIONS_RPC_PORT in tb-edge.yml), and uses the Integration key and Integration secret from Step 3. Pick the install method and then the integration type.

Make sure Docker CE is installed.

Pull the image:

Terminal window
docker pull thingsboard/tb-http-integration:4.4.0.2

Create a log volume:

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=mytbedge" \
-e "RPC_PORT=9090" \
-e "INTEGRATION_ROUTING_KEY=YOUR_ROUTING_KEY" \
-e "INTEGRATION_SECRET=YOUR_SECRET" \
--name my-tb-pe-http-integration \
--network edge_docker_default \
--restart always \
thingsboard/tb-http-integration:4.4.0.2

Useful commands:

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

Common Docker parameters:

Parameter Description
mytbedge Hostname of the ThingsBoard Edge service
9090 Integration RPC port (INTEGRATIONS_RPC_PORT in tb-edge.yml)
YOUR_ROUTING_KEY Integration key from Step 3
YOUR_SECRET Integration secret from Step 3
edge_docker_default Docker network where the Edge container runs. Check with docker network ls
--restart always Automatically restarts on system reboot or failure

To detach without stopping the container, press Ctrl+p then Ctrl+q.
Section titled “Send an uplink message”

  1. On the Edge, go to Integrations > Integrations, open HTTP Demo Remote, and copy the HTTP endpoint URL. It has the form http://IP:8082/api/v1/integrations/http/<Integration key> and points to the remote integration machine, so that machine must be reachable from your client and port 8082 must not be blocked by a firewall.

  2. Send a test message. Replace $YOUR_HTTP_ENDPOINT_URL with the copied URL:

    Terminal window
    curl -v -X POST \
      -d '{"deviceName":"SN-001","temperature":33,"model":"test"}' \
      $YOUR_HTTP_ENDPOINT_URL \
      -H "Content-Type:application/json"

  3. On the Edge, open the Events tab of the integration. An Uplink event with status OK appears.

  4. The device SN-001 is created automatically. Go to Devices & assets > Devices on the Edge, open it, and select the Latest telemetry tab. The temperature key shows 33.

Remote integration configuration

Section titled “Remote integration configuration”

The integration itself is configured in the ThingsBoard UI, in the template. On the remote service you only set the connection parameters above. For the settings of each integration type, see:

Troubleshooting

Section titled “Troubleshooting”

Check the log files of the service:

  • Docker: ~/.tb-pe-{type}-integration-logs/
  • Ubuntu / CentOS: /var/log/tb-{type}-integration/

Look for INFO messages that show the latest integration configuration received from the Edge. If there are none, check RPC_HOST, RPC_PORT, the key, and the secret.

© 2026 The ThingsBoard Authors · Privacy Policy · Cookie Policy ·