Cumulocity IoT offers a public API which enables device integrators to support the Cloud Remote Access feature on their devices.

For this functionality, the gateway needs to listen for an operation which establishes a new tunnel to a device endpoint. For this purpose, the gateway needs to create a WebSocket connection to the cloud and a TCP connection to the device. Using these connections, simple tunneling of protocol data is done on a binary level.


This section describes how to implement a device agent at a gateway.

Image 1

The device agent is responsible for creating the device part of the tunnel between an unencrypted TCP/IP connection at private network and the secure device WebSocket endpoint.

Supported operation

To indicate that your device is capable of handling Cloud Remote Access, it should report c8y_RemoteAccessConnect as supported operation in its managed object:

	"c8y_SupportedOperations": [

Connect operation

This operation is created when the application generates a connect request. The operation is then sent to the device agent to establish the connection between the WebSocket endpoint at the server and the local network endpoint.

Example of an c8y_RemoteAccessConnect operation:

		"deviceId" : "10200",
		"c8y_RemoteAccessConnect": {
			"hostname": "",
			"port": 5900,
			"connectionKey": "eb5e9d13-1caa-486b-bdda-130ca0d87df8"
		"description": "Connect to remote access server"
Field Data type Details
connectionKey String Shared secret to authenticate the connection request from device side.
hostname Number Endpoint on the local network to connect to.
port String Port to be used on local network endpoint.

Connecting to a new endpoint

For each c8y_RemoteAccessConnect operation received the device agent connects to the provided hostname and port using TCP. Using the provided ConnectionKey the agent also securely connects to the WebSocket endpoint on server side. If all these operations succeeded the device reports the operation as SUCCESSFUL and starts forwarding binary packets between the TCP connection and the WebSocket in both directions.

Image 2

The following events are triggered when the device agent receives a c8y_RemoteAccessConnect operation.

Operating a connected endpoint

When both connections are established and fully functional the agent simply needs to forward all binary packets between the TCP connection and the WebSocket in both directions.

Disconnecting an endpoint

Whenever one of the connections is terminated (WebSocket or TCP) the device agent should consider the session as ended and should also terminate both connections associated with the tunnel.


It is highly recommended to implement a small buffer especially for bootstrapping when one connection is already functional while the other is not setup yet.

Reference implementation

Cumulocity IoT provides a C++ reference agent which includes a plugin for Cloud Remote Access.

Find the source code at our public GitHub repositories:

(note that for historical reasons the module is called vnc here)