Getting Started

SocketXP is a cloud based SaaS service that empowers web applications running in your local network, behind the firewall and NAT, to securely communicate with web applications running in the cloud or the internet.

SocketXP creates a secure and unique public endpoint (URL) for your localhost web applications, through which online services could talk to your localhost web applications.

For the SocketXP service to work, you need to download and install a lightweight SocketXP agent to run on your local host machine.


Download and install a simple SocketXP agent to run on the localhost server where your web application also runs.  SocketXP agent is a CLI utility with which you could configure and create tunnels to your localhost web application or service.  A single SocketXP agent process could create any number of tunnels on the same host machine, limited only by your subscription plan.


$ curl -O && chmod +wx socketxp && sudo mv socketxp /usr/local/bin


$ curl -O && chmod +wx socketxp && sudo mv socketxp /usr/local/bin


Windows (32 bit)


$ curl -O && chmod +wx socketxp && sudo mv socketxp /usr/local/bin

ARM(aarch64, arm64, v8)

$ curl -O && chmod +wx socketxp && sudo mv socketxp /usr/local/bin

Docker Container

$ docker pull expresssocket/socketxp

Create a config.json file in your local directory and map it as a volume inside the container at /data direcotry as shown in the example below.

$ docker run -d  -v /tmp/my_data:/data expresssocket/socketxp

$ docker logs 25ad
Using config file: /data/config.json
Login Succeeded.
User [] Email [].

Public URL ->

Here is the content of a sample config.json file.

$ cat /tmp/my_data/config.json

    "authtoken": "",
    "tunnel_enabled": true,
    "tunnels" : [{
        "destination": "",
        "protocol": "http",
        "custom_domain": ""
    "relay_enabled": false,
    "relays": [{
    "destination": ""

If you want to configure TLS tunnels then use the below config.json file.

$ cat /tmp/my_data/config.json

    "authtoken": "",
    "tunnel_enabled": true,
    "tunnels" : [{
        "destination": "",
        "protocol": "tls",
        "custom_domain": ""
    "relay_enabled": false,
    "relays": [{
    "destination": ""

Where “” is the IP address of the other docker container running your web application (Eg; Jenkins server or Home Automation server or nodejs app)

Verify Installation:

After installing the SocketXP agent, check if it works.


Usage: socketxp [OPTIONS] COMMAND

Socketxp - secure tunnels to your localhost servers.

SocketXP is a cloud based SaaS service that empowers web applications running in your local network, behind the firewall and NAT, to securely communicate with web applications running in the cloud or the internet.

By using this product, you are agreeing to the terms of SocketXP Ltd. Terms of service can be found at:

Don't have an account? Create a free account here:

If you have any questions or security related issues, please contact us via email:


--help             Print usage

--no-auto-update   Disable SocketXP agent software auto-update feature

--use-system-dns   Use the system's DNS to resolve domain names;

default is Google's DNS


connect     Connect the supplied local destination to the public endpoint

login       Login to the SocketXP service.  Obtain an auth token from

relay       Relay webhook notifications from the public endpoint to the localhost webhook supplied

Run 'socketxp COMMAND --help' for more information on a command.

SocketXP Linux Daemon

For production, it is better to run SocketXP agent as a daemon service. SocketXP can be installed as a linux systemd daemon service. Here are the steps.

Follow the instruction above to first download and install the linux SocketXP agent in your /usr/local/bin directory.

Install the daemon

Create a config.json file (Refer to the sample config.json file shown in the Docker example above) in your home directory and execute the below daemon service install command.

[For IoT devices refer to this configuration file]

$ sudo socketxp service install --config /home/test-user/config.json


$ sudo systemctl daemon-reload

SocketXP will come up as a daemon service.

Status Check

Check the status of the SocketXP daemon service using the below cli.

$ sudo systemctl status socketxp

If you want to check the logs from the SocketXP daemon to find the public URL, execute the following command using the “journalctl” command.

$ journalctl -u socketxp.service -f

Note: systemctl , journalctl are linux commands/utilities.

Start/Stop the service:

$ sudo systemctl start socketxp
$ sudo systemctl stop socketxp


To uninstall, first stop the service. Then uninstall using the socketxp CLI.

$ sudo systemctl stop socketxp

$ sudo socketxp service uninstall


Authentication Token:

Sign up at and get your authentication token.

SocketXP Portal - Authtoken

Use the authentication token to authenticate the SocketXP agent with the SocketXP Cloud Service, as shown below.

$ socketxp login "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NDk1MTg0MDAsImlkIjoiZ2FuZXNodmVscmFqYW5AZ21ha6K208n0.cB2uYevpH4lWIQGQUJdQ0eiEDqS8OiP_YOiqernnui3rjjadfadsfsfas34"

HTTP Tunnels:

Make your localhost web application or web server go online, by creating a HTTP tunnel using the SocketXP agent.  Here is the SocketXP command to create a HTTP tunnel endpoint.

$ socketxp connect http://localhost:8000

Public URL -> https//

Where 8000 is the tcp port on which your localhost web application is listening for HTTP requests.  Use the public URL provided in the output above to access your localhost web application from anywhere in the internet.

Note the “https” in the SocketXP public URL created above.  Even though the localhost web application doesn’t have the capabilities to encrypt the data it transfers,   (meaning, it is just a plain HTTP server and not a HTTPS server ), we provide the SSL encryption on behalf of the localhost web application.

SocketXP always encrypts the data while transmitting over the internet.  We never send anything unencrypted over the internet. Customer data security is the heart and soul of our business.

Only the data exchanged between SocketXP agent and your local web application will be a clear-text data transfer(because your web application doesn’t support HTTPS), and the data transfer happens within the realm of your local server or local network.

HTTP Tunnels with Custom Subdomain

SocketXP public URLs with random subdomain name (your email-id plus some random number) is good for quick testing. But for production or for sharing your URL publicly with others, it is nice to have a subdomain that makes sense and easy to remember.

Use the “–subdomain” option in the above command to get a SocketXP public URL with your preferred subdomain name.

$ socketxp connect http://localhost:3000 --subdomain database

Public URL ->

Note: Subdomains are assigned to users from a free pool of available subdomains. Subdomains are not reserved resources. It will be recycled automatically, if it is found not being used by a user.

HTTP Tunnels with Custom Domain (White-Label URLs)

Instead of your tunnels appearing as a subdomain of domain, you could run your HTTP tunnels on your own domain.  It’s a two step process.

First, execute the following SocketXP command to create a HTTP tunnel, for example, over “”,

$ socketxp connect --white-label-domain http://localhost:5000

Public URL -> https//

Next, use the above SocketXP public URL to create a DNS CNAME record for “” and point it to “”.  Please check with your DNS provider on how to configure a DNS CNAME record for your custom domain.

Thereafter, you could use the public URL “” to access your web service.

HTTPS Tunnels

If your web application has the capabilities to encrypt and decrypt HTTP traffic using its own SSL certificate and key, then you could create a HTTPS tunnel, as  shown below.

$ socketxp connect https://localhost:8000

Public URL -> https//

Now the data exchanged between SocketXP agent and your localhost web application will also be encrypted, in addition to the data transferred over the internet.  This capability is extremely important if your local network is unsafe for clear text data transfer.

Please note that the data transferred through HTTPS tunnel is encrypted hop-by-hop and not end-to-end. HTTPS tunnels are good for development and testing purposes but for production you should create SSL/TLS tunnels with end-to-end encryption capabilities.  Read the next section about TLS tunnels to know more about configuring end-to-end SSL/TLS tunnels using SocketXP.

SSL/TLS Tunnels

HTTPS tunnels terminate all SSL/TLS traffic at the SocketXP Cloud Servers using SSL certificate and key.  For production-grade services or anything that involves sharing sensitive information, such as authentication token or financial data, you’ll want your traffic to be tunneled through SSL/TLS tunnel, which encrypts data traffic end-to-end with your own SSL Certificate and Key.  SocketXP supports TLS tunnels and it is extremely easy to set it up.

$ socketxp connect --tls-e2e
Public URL ->

Make sure, your web application running at has the proper SSL certificate and key setup.

Now, try accessing the public URL above with curl utility.

$ curl --insecure

TLS end-to-end tunnels without certificate warnings

In the previous curl command example, “–insecure” option is required so that we can ignore certificate warnings. You need to specify that because your local HTTPS server doesn’t have the TLS key and certificate necessary to terminate traffic for any subdomains. If you try to load up that page in a web browser, it will ask you to add an exception.

If you want your certificates to match and be protected from man-in-the-middle attacks, you need two things. First, you’ll need to buy an SSL certificate for a domain name that you own and configure your local web server to use that certificate and its private key to terminate TLS connections. How to do this is specific to your web server and SSL certificate provider and beyond the scope of this documentation. For the sake of example, we’ll assume that you were issued an SSL certificate and key for the domain “”.

Once you have your key and certificate, it’s time to run an end-to-end TLS tunnel on your own custom domain name. The instructions to set this up are identical to those described in the previous section on “HTTP Tunnel with Custom Domain(White Label URL)”.  We will be specifying the “–white-label-domain” option to specify the custom white-label domain to be used over your TLS tunnel.

The custom domain you register should be the same as the one in your SSL certificate (For eg:

Now run the TLS tunnel over your custom domain name, as shown below in the example below.

$ socketxp connect --tls-e2e --white-label-domain “”

Public URL ->

Where 8233 is the TCP port on which your HTTPS server is listening for new connections.  Next configure the DNS CNAME record for your custom domain “” to point towards the above SocketXP public URL.

Accessing your custom white-label domain ( using curl should work just fine now. It shouldn’t throw any certificate mismatch errors.

$ curl

Running non-HTTP services over SSL/TLS tunnels:

SocketXP SSL/TLS tunnels make no assumptions about the underlying protocol being transported. All examples in this documentation use HTTPS because it is the most common use case, but you can run run any TLS-wrapped protocol over a TLS tunnel (e.g. imaps, smtps, sips, etc) without any changes.

TCP Tunnels:

TCP tunnels, unlike HTTP(S) tunnels, can be used to take any localhost applications online not just web applications that talk HTTP. Use TCP tunnels to take your local SMTP server, SFTP server, game server, databases or SSH server online.
For example, to take your localhost network service such as SSH (which listens on TCP port 22 and talks no HTTP) online, use the below command to create a TCP tunnel endpoint for your localhost SSH server.

$./socketxp  connect tcp://localhost:22 --iot-device-id "DEV00000001"

TCP tunnel [test-user-gmail-com-34445] created.
Access the tunnel using SocketXP agent in IoT Slave Mode

SocketXP Cloud Gateway will not open any public TCP endpoint for TCP tunnels. The Gateway also authenticates all connections coming to TCP tunnels from the internet using the auth token for the given user.

Now you can SSH into your server by opening up a browser and logging into SocketXP Portal and going to the Devices page: and click the terminal icon next to your device. It will open a SSH session to your device in the browser.

Alternatively, you could access your server or IoT device using your own SSH client by installing and configuring SocketXP agent to run in IoT Slave Mode on your access devices such as laptop/desktop. This is explained in detail in the next section.

Configuring SocketXP agent to run in slave mode

First download and install the regular SocketXP agent software on your accessing device (such as a laptop running Windows or Mac OS). Next, configure the agent to run in slave mode using the command option “–iot-slave” as shown in the example below.

$ socketxp connect tcp://localhost:3000 --iot-slave --iot-device-id "DEV00000001"

Listening for TCP connections at:
Local URL -> tcp://localhost:3000

Accessing the IoT device from your laptop

Now you can access your IoT device’s SSH server using the above SocketXP local endpoint, instead of a public endpoint, as shown below.

$ ssh -i ~/.ssh/john-private.key john@localhost -p 3000

We recommend using SocketXP Private TCP Tunnels for all your remote IoT device access needs. Public TCP tunnels can be used for hobby usecase, quick testing or one-off accesses.

Config file for running SocketXP agent as a background service in IoT devices

Use the following configuration file when running SocketXP agent as a background (systemd) service in IoT device.

$ cat /home/iot-user/config.json

    "authtoken": "",
    "tunnel_enabled": true,
    "tunnels" : [{
        "destination": "tcp://",
        "protocol": "tcp",
        "custom_domain": "",
        "subdomain": "",
        "iot_master": true,
        "iot_device_id": "DEV00000012345",              // Some device identifier scheme unique within your organization; required field
        "iot_device_name": "some_unique_device_name",   // Eg: temperature_sensor_machine_100
        "iot_device_group": "some_device_grouping"      // Eg: temperature_sensors
    "relay_enabled": false,
    "relays": [{
    "destination": "",
    "subdirectory": ""


Webhook Relay Tunnels:

SocketXP webhook relay tunnel provides a public endpoint which can accept webhooks from an online service and relay it to a localhost destination.  Webhook relay tunnels can be created using the following command.

$ socketxp relay https://localhost:8080/github-webhook/
Public URL ->

Use the above public webhook URL to configure the online service from which you are expecting to receive webhook notifications.