Edge instance

A ThingsBoard Edge instance is a standalone ThingsBoard deployment that runs locally, on-premises or on a device at the network edge. It connects to a ThingsBoard server, which provisions it, pushes configuration (device profiles, rule chains, dashboards), and receives synchronized data. The key difference from a cloud deployment is where data is processed:

	ThingsBoard Edge	ThingsBoard Cloud
Data processing	Locally on the Edge device	Centrally in the cloud
Connectivity	Operates over LAN without internet	Requires internet connectivity
Clustering	Supported from release 4.0	Supported

ThingsBoard Edge and the ThingsBoard server communicate using the gRPC protocol over port 7070 by default. Messages are serialized with Protocol Buffers (ProtoBuf) to minimize overhead and latency.

All messages sent from Edge to the server are stored locally in PostgreSQL tables before transmission: cloud_event for entity, attribute, and alarm events, and ts_kv_cloud_event for time-series data. Starting with release 3.9, these events can be stored in Kafka topics (tb_cloud_event and tb_cloud_event_ts) when Kafka is used as the queue. This lets Edge operate without a live server connection. Once connectivity is restored, all queued messages are sent and marked as transferred.

Key connection defaults (configurable via environment variables in tb-edge.conf):

Parameter	Default	Env variable
gRPC port	7070	CLOUD_RPC_PORT
Reconnect interval	3000 ms	CLOUD_RECONNECT_TIMEOUT
Uplink batch size	50 records	CLOUD_RPC_STORAGE_MAX_READ_RECORDS_COUNT
Keepalive ping interval	10 s	CLOUD_RPC_KEEP_ALIVE_TIME_SEC

Downlinks are messages pushed from the server to the Edge: entity assignments, configuration changes, rule chain updates, and similar operations. When an entity is assigned to an Edge instance on the server, it is added to the downlink queue. If the Edge is connected, the entity arrives immediately; if disconnected, it is delivered once the connection is restored.

Inspecting downlinks is useful when an Edge instance is missing an expected configuration: you can verify whether the server has sent it and whether it was received. The Downlinks tab is available on the Edge instance details page on the server.

Devices, assets, entity views, dashboards, device and asset profiles, rule chains, users, and scheduler events can be created directly on the Edge instance. Customers, entity groups, roles, integrations, data converters, and OTA packages are created on the server only: they control access and configuration across Edge instances, so they are assigned to the Edge from the server. An Edge receives the customer that owns it and the users of the user groups assigned to it.

Before installing Edge, you must create an Edge instance on the server. Go to Edge management > Edges, click Add edge, select Add new edge, enter a name, and click Add. This creates the Edge key and Edge secret that bind the Edge to the server during installation. For installation instructions, see Edge installation.

With Remote Agent auto-provisioning, ThingsBoard creates the Edge instance for you when the agent starts on the host, so there is no key and secret to copy.