# Getting Started

Follow these 3 simple steps to get started with SocketXP quickly.

# Step #1: SocketXP agent installation

Download and Install a simple SocketXP agent to run on the localhost server(or IoT device) where your web application or SSH server also runs. SocketXP agent is a CLI utility with which you could configure and create tunnels to your localhost web application or SSH server or any local server.

You'll find the download and installation instructions for your OS and CPU platform here:

Download and Install

# Step #2: Login to your SocketXP account

Execute the following command to authenticate the SocketXP agent installed in your device with the SocketXP Cloud Gateway, using the auth-token provided to you in the SocketXP Portal (opens new window).

$ socketxp login <your-authtoken-goes-here>

Visit the SocketXP Portal (opens new window) to get your auth token. Don’t have an account ? Sign up for free to receive your auth-token.


If you prefer to name your device using a unique identifier, you could use additional arguments to the login command as shown below.

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

Security Note:

The login command uses the authtoken to generate a unique per-device private key file at /var/lib/socketxp/device.key. The authtoken is never stored in the device as part of the /etc/socketxp/config.json file or anywhere in the device. Your customer or vendor or your team will not be able to know your authtoken unless you explicitly share the token or your SocketXP account with them. Device key cannot be used to access the REST APIs.

# Step #3: Create secure tunnels

Once you have authenticated the SocketXP client with the SocketXP Cloud Gateway, you could begin creating secure tunnels to your IoT device's SSH server, VNC server or any localhost web application.

# Usecase #1: IoT Remote SSH Access Over the Internet:

For example, to enable remote SSH access to your Raspberry Pi or IoT devices in your office or home network, execute the below command.

$ socketxp connect tcp://localhost:22

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


SocketXP automatically assigns a unique ID for your device.

Now you could remote SSH into your Pi or IoT device over the internet from the SocketXP Web Portal (opens new window) devices page. Click the terminal icon displayed next to your device to get into its SSH shell.

# Usecase #2: Public URL for your IoT Web Service:

For example, to remotely access a web service running in your localhost network (say, port 8080) over the internet, execute the below command. The command creates a secure HTTP tunnel to your localhost web service.

$ socketxp connect http://localhost:8080

Public URL -> https://test-user-a29dfe42e3.socketxp.com

After you have successfully created the HTTP tunnel, use the public URL provided by SocketXP https://test-user-a29dfe42e3.socketxp.com to access your localhost web service from anywhere in the world.

# Single-Touch Installation Command:

The 3 step instruction explained above to setup SocketXP agent on your IoT device is a tedious process, if you have thousands of devices to install, configure and manage.

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

You can find the detailed instruction on how to use the single-touch-installation command here.