# IoT Remote Desktop VNC Access

SocketXP IoT Cloud Gateway provides Remote Desktop(RDP or VNC) Access solution, in-addition to the Remote SSH/SFTP Access solution. IoT Remote Desktop Access solution comes in handy when you want to access your IoT device or Raspberry Pi desktop application remotely.

# Pre-requisites

To remotely access your Raspberry Pi desktop, we will be installing TightVNC Server on the Raspberry Pi. We'll also install the TightVNC Client on your Windows laptop/PC (from which you want to remote desktop into your Pi).

If you have already installed these TightVNC softwares, you can skip the below section and jump straight to the next section about installing SocketXP IoT Agent.

# Installing TightVNC Server on Raspberry Pi for VNC access

For this tutorial we will assume that your Raspberry Pi doesn't have a desktop environment installed. We will install XFCE desktop environment, to have the actual desktop accessible on the Pi.

$ sudo apt install -y xfce4 xfce4-goodies 

Next, we will install tightvncserver to be able to access that desktop.

sudo apt install -y tightvncserver The next thing we'll have to do is to set up an access password for VNC clients. This is done on the first run of your VNC server. Simply run the command below:

$ vncserver

# TightVNC Password Setup

You will be asked to provide two passwords. One is an access password and the other is a view-only password. The access password lets you connect to the desktop and interact with it using keyboard and mouse whereas the view-only password will only let a user observe your desktop. The view-only password is optional so you can skip setting it up when asked by pressing the enter key on your keyboard.

Now that the password is set up we will configure a startup file for VNC. Firstly, we'll have to shut down our currently running VNC server.

$ vncserver -kill :1

Then we'll create a backup of current startup file, in case we'd like to revert back to it.

$ mv ~/.vnc/xstartup ~/.vnc/xstartup.bak

Finally, we'll create a new startup file.

$ printf '#!/bin/bash\nxrdb $HOME/.Xresources\nstartxfce4 &\n' > ~/.vnc/xstartup
$ sudo chmod +x ~/.vnc/xstartup

This will create the following file:

xrdb $HOME/.Xresources
startxfce4 &

The first line xrdb $HOME/.Xresources tells the VNC's GUI framework to read the server user's Xresource file.

The second line starts the Xfce in background.

Now, re-start the VNC server using the command below.

$ vncserver

Now we're ready to access our Raspberry Pi desktop from the Windows PC.

# SocketXP IoT Agent installation

Install a simple, secure and lightweight SocketXP IoT Agent on your IoT device (or Rasperry Pi). The SocketXP agent will securely connect to the SocketXP IoT Cloud Gateway via an SSL/TLS tunnel.

We need to setup SocketXP Agent to run in two different places:

  • Raspberry Pi - in IoT Master Mode (Default Mode)
  • Laptop or PC - in IoT Slave Mode

Follow the instructions below to install SocketXP IoT Agent on your IoT or Raspberry Pi device. Also follow the same instructions to install SocketXP IoT Agent on your access device (such as your laptop, or PC).

# Step 1: Download and Install

Download and install (opens new window) SocketXP IoT agent on your IoT or Raspberry Pi device.

# Step 2: Get your Authentication Token

Sign up at https://portal.socketxp.com (opens new window) and get your authentication token.

Auth Token

Use the following command to login to the SocketXP IoT Cloud Gateway using the auth token.

$ socketxp login <your-auth-token-goes-here>  --iot-device-name "sensor12345" --iot-device-group "temp-sensor"

# Step 3: Setup SocketXP Agent on your IoT or Raspberry Pi Device

To make SocketXP agent to run in IoT Master Mode (which is the default mode of SocketXP agent) use the below command, as you would normally do.

$ socketxp  connect tcp://localhost:5901 

Connected to SocketXP Cloud Gateway.
Access the TCP service securely using the SocketXP agent in IoT Slave Mode.

where localhost port 5901 is the VNC server port, on which tightvncserver is listening for connections from a VNC viewer .


SocketXP automatically assigns a unique ID for your device.

Security Info:

SocketXP does not create any public TCP tunnel endpoints that can be connected and accessed by anyone on the internet using an SSH client. SocketXP TCP tunnel endpoints are not exposed to the internet and can be accessed only using the SocketXP agent (using the auth token of the user) or through the XTERM terminal in the SocketXP Portal page.

# Step 4: Setup SocketXP Agent on your Windows or Mac

Next, to access the Raspberry Pi device from your Laptop/PC, setup SocketXP IoT Agent for Windows (or MacOS) to run in the IoT Slave Mode as shown below:

$ ./socketxp.exe connect tcp://localhost:10111 --iot-slave --peer-device-id "DEV000000012345" --peer-device-port 5901
Listening for TCP connections at:
Local URL -> tcp://localhost:10111  

where 10111 is a local port on your PC at which you want to access the Raspberry Pi. You can choose to use any free local port instead of port 10111. You can find the device ID of your device in the SocketXP Portal page in the IoT Devices section. Alternatively, you could provide the IoT device name to connect in slave mode as shown below:

$ ./socketxp.exe connect tcp://localhost:10111 --iot-slave --peer-device-name "sensor12345" --peer-device-port 5901
Listening for TCP connections at:
Local URL -> tcp://localhost:10111  

Why this step is important?:

SocketXP IoT Agent when run in IoT Slave Mode acts like a localproxy server. It proxies all connections to a user-specified local port (10111 in the example above) in your laptop/PC to the SocketXP IoT Cloud Gateway using a secure SSL/TLS tunnel. Also the SocketXP IoT Agent authenticates itself with the SocketXP IoT Cloud Gateway using your auth token. This ensures that only legitimate, authenticated users are permitted to access your remote IoT devices. SocketXP ensures Zero-Trust security on all connected devices.


IoT Business Plan support creating remote TCP connections to SSH server running on port 22 only. Services running on all other ports such as VNC, RDP, and Web Service cannot be accessed. An upgrade to IoT Enterprise Plan is required to access services running on all other ports.

# Connect from Windows Laptop/PC

# TightVNC Viewer (client software) installation

Install TightVNC Viewer on your Windows PC from the TightVNC website (opens new window).

Launch TightVNC Viewer and it will bring you straight to the login window. Fill it out with the following details:

  • Remote Host: localhost:10111.

Raspberry Pi Remote Desktop VNC Access Over the Internet using TightVNC

When done click on "Connect". This will bring you to the authentication window.

Raspberry Pi Remote Desktop VNC Access Over the Internet using TightVNC

This is where you provide your TightVNC access password that you've set up in the first section of this article. When you click OK, you will see the desktop of your Raspberry Pi. Raspberry Pi Remote Desktop VNC Access Over the Internet using TightVNC

Please keep in mind that there's a lot of data being transferred in between your Raspberry Pi and your PC in order to provide live desktop experience, so the quality and response time might not be exactly as on a local desktop.

# Single-Touch Installation

The 3 step instruction explained above to install & configure SocketXP IoT Agent on your IoT device is a tedious process, if you got thousands of RPi to install, configure and manage.

With this mind, SocketXP IoT Remote Access Solution also provides a single-touch installation command for installing and configuring SocketXP IoT Agent on large number of IoT or RPi devices.

Copy paste the below single-touch installation command into the terminal of your IoT devices and it will install/configure/setup and bring up the devices online in our SocketXP portal. Don't forget to update the auth-token in the below command with the one uniquely assigned to you.

$curl -O https://portal.socketxp.com/download/iot/socketxp_install.sh && chmod +wx socketxp_install.sh && sudo ./socketxp_install.sh -a <your-auth-token-goes-here> -p "arm" -l "tcp://"

Platform Architecture Type:

The above single-touch installation command automatically reads your CPU platform arch and OS type information from the uname -m command output.

If your device is Orange Pi, Nano Pi or other Pi variations, feel free to edit the socketxp_install.sh script to meet your device or platform archtecture requirements.

The socketxp_install.sh installation script takes the following arguments:

./socketxp_install.sh -a <auth-token> [ -p <platform> ] [ -l <local-destination> ] [ -s <subdomain-prefix> ]

Command argument auth-token is mandatory.  All other arguments are optional.
Acceptable platform values: [ amd64, arm, arm64 ]

# Configuration JSON File

The single-touch installation script creates a config file at: /etc/socketxp/config.json. It would look something like this:

$ cat /etc/socketxp/config.json

"tunnels" : [
      "destination": "tcp://"
      "destination": "tcp://"

Update the tunnels section in the above config file to include the HTTP webservice as well. The config.json file would look like this:

$ cat /etc/socketxp/config.json

"tunnels" : [
      "destination": "tcp://"
      "destination": "tcp://"
      "destination": "",
      "subdomain": "test-abc123456789"

Restart the socketxp systemd service using the following command. So that the above config change could take effect.

$ systemctl restart socketxp
$ systemctl status socketxp