etunnel for Node.js
Expose a local service through an etunnel reverse-tunnel server. Zero dependencies (Node >= 22 built-in WebSocket).
Zero registration: every SDK client speaks the same tiny wire protocol
(PROTOCOL.md) against any etunnel server
(default wss://t.etun.uk/tunnel).
Install
npm install @easytunnel/et-sdk
Requires Node >= 22.
CLI
npx @easytunnel/et-sdk 3000
Prints TUNNEL_URL: https://<subdomain>.t.etun.uk — that URL now routes to
your local service. Ctrl-C closes the tunnel.
Reconnects automatically. If the connection drops (including a server
restart) the CLI re-dials with exponential backoff (500ms → 30s, ±20%
jitter, reset on success) and prints TUNNEL_URL: again. The subdomain is
reclaimed, not re-randomised: the client replays the server's signed
resumeToken in hello.resume, so links already shared keep working (the
server needs a stable SESSION_SECRET; see PROTOCOL.md §1). Set
ETUNNEL_RECONNECT=0 to restore the old one-shot behaviour.
Embed
const { connect } = require('@easytunnel/et-sdk');
const t = await connect('wss://t.etun.uk/tunnel', 3000);
console.log(t.url);
connect(server, local, opts) takes an optional third argument: token,
subdomain, resume (strings), and wsFactory — a (serverUrl) => WebSocket
constructor injection used instead of the global WebSocket (the CLI passes a
factory that captures the socket it creates). Library embedders with their own
WebSocket implementation or per-connection sockets should inject wsFactory;
the global is never patched.
Environment variables
| Variable | Meaning | Default |
|---|---|---|
ETUNNEL_SERVER | tunnel server WebSocket URL | wss://t.etun.uk/tunnel |
ETUNNEL_LOCAL | local port or host:port (or 1st CLI arg) | 3000 |
ETUNNEL_TOKEN | paid-plan API key (optional) | - |
ETUNNEL_RECONNECT | 0 disables auto-reconnect (one-shot CLI) | enabled |
ETUNNEL_SUBDOMAIN | custom subdomain (paid plans) | random |
License
MIT — see LICENSE. Buffer-based protocol client: request and response bodies are buffered per stream (fine for webhooks/dashboards/demos; use the Go SDK for streaming and WebSocket pass-through).
Service terms
Use of the etunnel relay service (default wss://t.etun.uk/tunnel) is governed
by its Terms of Service and
Privacy Policy.