Installing ThingsBoard Edge using Remote Agent — Docker container management

Remote Agent installs, upgrades, and monitors ThingsBoard Edge remotely from the cloud: no manual Docker commands and no maintenance access to the target machine. The agent is a small Docker container that runs next to Edge on the same host, connects to your ThingsBoard server, and executes deployments on its behalf. This page covers the Edge-specific flows; for the full feature — agents, profiles, application actions, and bulk operations — see the Remote Agent documentation.

Compared to a manual Docker installation, the agent adds:

• Remote installation: Deploy Edge from the ThingsBoard UI to any host where the agent runs.
• Managed upgrades: Push new Edge versions from the cloud, with volume backups, automatic database migration, and rollback on failure.
• Monitoring: Host and container metrics, container states, and live logs in the ThingsBoard UI.
• Fleet operations: Upgrade or restart all Edge instances of a fleet with bulk actions.

• ThingsBoard server or a ThingsBoard Cloud tenant.
• Docker installed on the target machine (Linux, amd64 or arm64).
• Outbound network access from the target machine to the ThingsBoard gRPC port (default 7070).

Full guide: Auto-provision an agent.

Auto-provisioning covers hosts that have never run an agent: nothing needs to be deployed or created up front, neither the agent nor the Edge entity. Generate one provisioning command bound to an agent profile and run it on the target machine: the command starts the agent, and ThingsBoard registers it and creates the Edge entity tied to it automatically, configured from the application profile assigned to the agent profile. It is also the fastest way to roll out a fleet: every machine that runs the same command receives its own agent and Edge instance.

1. Go to Edge management > Edges, open the Add edge (+) menu, and click Auto-provision.

2. Pick an agent profile that has an Edge application profile assigned, or create one: the Edge and Edge + Gateway presets create the agent profile with the latest Edge application profile already assigned. The dialog shows Ready to provision once the selected profile qualifies.

3. Click Next and copy the provisioning script.

4. Run the script on every target machine. Each run registers a new agent that installs Edge on its host; the new Edge instance appears in the Edge instances table.

Full guide: Deploy an application.

1. Create an Edge instance in ThingsBoard — go to Edge management > Edges, click Add edge, enter a name, and click Add — or open an existing one.

2. In the Edge details, click Upgrade Instructions and select the Agent tab. The four-step wizard opens.

3. On Select Agent, pick the agent that runs on the target machine: only online agents can install. If the machine has no agent yet, create one and run the generated command on the machine first; see Install Remote Agent.

4. On Review & Customize, select the application profile that supplies the Docker Compose configuration — one of your profiles or a predefined profile shipped with the platform — then enter the application name, adjust the image pull policy, and review the resulting Compose configuration. The related entity is the Edge itself: its credentials are wired into the configuration automatically.

5. On Save Application, check the summary and click Save. The agent downloads the images and starts the containers.

6. The Install step confirms that your agent is online and links to the created deployment: open Agent application and check its Events tab to verify that the install finished.

Once deployed, open the Edge UI at http://<target-machine>:8080 and log in with your tenant administrator credentials.

Full guide: Update an application.

To change the configuration of a deployed instance, click Update on the application details page. For a profile-managed application, the configuration panes in the update dialog are read-only: edit the configuration through the profile with Update profile. In the profile editor, the template stays read-only on the left, and your Compose on the right is what gets saved. Back in the update dialog, the comparison shows exactly what the updated profile changes; confirm with Update, and the agent re-deploys the application with the new configuration and the Edge credentials merged in. The finished update appears on the Events tab.

Full guide: Monitor an application.

The Agent tab of the Upgrade Instructions dialog stays useful after the installation: it shows whether the managing agent is online and healthy, and links to the agent, the managed application with its services and logs, and the live stream of agent events. On the application’s Units tab, check the state of every container and open the live logs of a single unit.

Full guide: Upgrade an application.

Agent-managed Edge instances upgrade from the ThingsBoard UI: the agent stops the instance, backs up the selected volumes, migrates the database when needed, and starts the new version. A failed upgrade rolls back automatically, using the backed-up volumes.

1. When a newer template version exists, the Upgrade available button appears in the Edge details. Click it: the Upgrade Application wizard opens.

2. If the application is linked to a profile that still points to the previous template version, the wizard starts with the Upgrade Profile step: review the new template next to the profile’s current Compose with the new image auto-merged in, and click Upgrade Profile so the application can adopt the new configuration.

3. On Review & Customize, select the volumes to back up before the upgrade and the image pull policy, then click Next.

4. On Save Application, confirm the target version and the volumes to back up, and click Upgrade.

5. Wait in the Event progress dialog until every stage reports Completed. View in events opens the agent’s event log.