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

Remote Integrations

Any ThingsBoard Integration can run remotely from the ThingsBoard Edge instance — either on the same machine or on a separate machine that has network access to the Edge. This guide walks through setting up a remote HTTP integration as a concrete example.

Prerequisites

Section titled “Prerequisites”
  • A running ThingsBoard Edge instance already connected to the Cloud server, with Tenant administrator access.

Configure ThingsBoard server

Section titled “Configure ThingsBoard server”

Converter and integration templates are created on the Cloud instance. Log in as Tenant administrator.

Section titled “Step 1. Create the uplink converter”

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

  1. Go to Edge management > Converter templates and click +, then Create new converter. Set type to Uplink and enable Debug mode.

  2. Paste the following decoder script into the function Decoder field, then click Add:

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

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

    function decodeToString(payload) {
      return String.fromCharCode.apply(String, payload);
    }
    

    function decodeToJson(payload) {
      var str = decodeToString(payload);
      return JSON.parse(str);
    }
    

    return result;

Step 2. Create the remote integration template

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

  1. Go to Edge management > Integration templates and click +, then Create new integration.

  2. In Basic settings: set Integration type to HTTP and enter a name (e.g. HTTP Demo Remote). Click Next.

  3. In Uplink data converter: select the Select existing tab and choose the converter created in Step 1. Click Next.

    Alternatively, create a new converter inline.

  4. In Connection: set Base URL to {{remoteHttpIntegrationUrl}}. Enable the Execute remotely toggle. Click Add.

    The {{remoteHttpIntegrationUrl}} placeholder will be replaced by an Edge attribute value when the integration is assigned to the Edge.

Step 3. Save the integration credentials

Section titled “Step 3. Save the integration credentials”

You will need the Integration key and Integration secret when configuring the remote service.

  1. Go to Edge management > Integration templates and open the integration you created.
  2. In the Execute remotely block, copy the Integration key and Integration secret.

Step 4. Assign the integration to Edge

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

Before assigning the integration, add the remoteHttpIntegrationUrl attribute to the Edge instance. This attribute provides the IP address and port of the machine where the remote HTTP integration service will run (default port: 8082).

  1. Go to Edge management > Instances and click the Edge instance.

  2. On the Edge details page, select the Attributes tab and click Add.

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

  4. Close the Edge details page and return to the Instances section.

  5. Click Manage edge integrations on the Edge row.

  6. Click Assign to edge.

  7. Select the HTTP integration from the drop-down and click Assign.

  8. Log in to the ThingsBoard Edge instance and go to Integration center > Integrations. Open the HTTP Demo Remote integration and confirm that the {{remoteHttpIntegrationUrl}} placeholder is replaced with the attribute value.

Install the remote integration service

Section titled “Install the remote integration service”

Use the Integration key and Integration secret from Step 3 to configure the service.

Make sure Docker CE is installed.

Pull the image:

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

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 \
-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-pe-http-integration:4.3.1.1PE

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:

ParameterDescription
mytbedgeHostname of the ThingsBoard Edge service
9090Integration RPC port (INTEGRATIONS_RPC_PORT in tb-edge.yml)
YOUR_ROUTING_KEYIntegration key from Step 3
YOUR_SECRETIntegration secret from Step 3
edge_docker_defaultDocker network where the Edge container runs. Check with docker network ls
--restart alwaysAutomatically restarts on system reboot or failure

To detach without stopping the container, press Ctrl+p then Ctrl+q.

Validate the remote HTTP integration

Section titled “Validate the remote HTTP integration”

  1. On the Edge, go to Integration center > Integrations and open the HTTP Demo Remote integration. Copy the HTTP endpoint URL.

  2. Send a test uplink message (replace $DEVICE_NAME and $YOUR_HTTP_ENDPOINT_URL with actual values):

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

  3. Go to Entities > Devices on the Edge to see the newly created device and its telemetry.

Remote integration configuration

Section titled “Remote integration configuration”

Configuration is done entirely through the ThingsBoard interface — no special steps are required on the remote service side beyond the connection parameters. For integration-specific configuration, see:

Troubleshooting

Section titled “Troubleshooting”

Check the log files. Their location depends on the platform and installation method used:

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

Look for INFO log messages showing the latest integration configuration received from the server.

© 2026 The ThingsBoard Authors