Secure Remote Device Tunnel

This service enables secure, global access to your local devices over WebSocket tunneling. It supports automatic HTTPS provisioning using Let's Encrypt, allowing you to expose HTTP services with valid SSL certificates — even from behind NAT or firewalls.

Getting Started

To use the tunnels, you need:

• An account on device-tunnel.top
• A valid domain name (e.g. your-device.site)

Some services provide domains absolutely free, for example "cloudns" or "noip"

Connect to wss://device-tunnel.top:3333 using any WebSocket client and provide the following configuration:

{
    domain: 'free.domain.site',
    device: 'my-device-name',
    secret: 'YOUR_SECRET_KEY'
}       

This tunnel works with a variety of devices including:

• Raspberry Pi (all versions)
• Orange Pi, Banana Pi, etc.
• Libre Computer boards
• BeagleBone Black
• Intel NUC
• Any x86/x64 Linux system
• Even microcontrollers such as ESP-32

Node.js Client

npm install self-tunnel

Ideal for running on small computers and single-board systems.

import selfTunnel from 'self-tunnel'; // or require('self-tunnel');
...
const tunnel = selfTunnel( 
{
    domain: 'my.domain.site',
    device: 'my-device-name',
    secret: 'my_secret_key'
});
        

Module readme: self-tunnel

Demo available at: StackBlitz Example

ESP-32 Support

ESP-IDF client

Example use with httpd server: Tunnel Example

Include the Tunnel Component in your idf_component.yml

dependencies:
esp-idf-tunnel:
    git: https://github.com/bahr1k/esp-idf-tunnel
    version: "0.3.4"
        

Arduino client

Install library: ESPTunnel

Example use with Arduino WebServer: Tunnel Example

Protocol Overview

The Remote Device Tunnel uses a simple protocol for authentication and data transfer:

• Authentication: Initial connection uses JSON messages for basic authorization.
• Connection Flow:
  1. Client connects to WebSocket server
  2. Server sends greeting message ({"type": "hello"})
  3. Client responds with authentication credentials ({"type": "login", "domain": "...", "device": "...", "secret": "..."})
  4. Server verifies credentials and responds with success/failure
  5. Client requests tunnel start ({"type": "start"})
  6. Server provides special control markers for EOF and suspend operations
• Special Markers:
  • EOF Marker: Must be appended to responses without Content-Length or chunked encoding to signal end of transmission
  • Suspend Command: Can be sent at any time to pause proxying without disconnecting
• Data Format: After authentication, all tunnel data is transmitted as binary

Disclaimer

• We make no representations or warranties regarding the reliability or security of this service.
• We assume no responsibility for the protection of your devices or their security when connected to the public internet.
• No data transmitted through our tunnels is stored or processed by us in any way.
• We solely provide an encrypted connection to facilitate communication between you and your devices.
• By commencing use of our service, you acknowledge your understanding and acceptance of the aforementioned risks.

Restrictions

• Requests with body content must include the Content-Length header
• Responses without Content-Length or chunked encoding must end with the custom EOF marker.
• All responses must be valid HTTP and response headers must fit within the first packet.
• The following URLs are blocked from proxying: /.well-known/*
• Maximum message size: 2 MB
• Responces order most be some as requests, or use "x-original-id" header

License

MIT