localtunnel

This package is a simple wrapper around the local tunneling services. Currently it supports serveo.net and Pinggy. The module is designed to be simple to use and to provide a consistent interface to those services.

Installation

It is available on JSR and npm:

deno add --jsr @hongminhee/localtunnel  # Deno
npm  add       @hongminhee/localtunnel  # npm
pnpm add       @hongminhee/localtunnel  # pnpm
yarn add       @hongminhee/localtunnel  # Yarn
bun  add       @hongminhee/localtunnel  # Bun

Usage

Invoke the openTunnel() function to open a tunnel to a local port. The function returns a promise that resolves to a Tunnel object. The Tunnel object has a url property that contains the URL of the tunnel. The Tunnel object also has a close() method that closes the tunnel:

const tunnel = await openTunnel({ port: 8000 });
console.log(tunnel.url.href);
alert("Press Enter to close the tunnel.");
await tunnel.close();

By default, openTunnel() chooses from SERVICES. To use a different set of services, pass a name-to-Service registry through the services option. The registry replaces the default services for the call and any retries:

import { openTunnel, type Service, SERVICES } from "@hongminhee/localtunnel";

const services = {
  "pinggy.io": SERVICES["pinggy.io"],
  custom: {
    host: "tunnel.example.com:2222",
    port: 80,
    knownHosts: {
      "[tunnel.example.com]:2222": ["ssh-ed25519 AAAA..."],
    },
    urlPattern: /https:\/\/[^\s]+\.example\.com/,
  },
} satisfies Readonly<Record<string, Service>>;

const tunnel = await openTunnel({
  port: 8000,
  services,
  service: "custom",
});

The service and exclude options accept only keys from the selected registry. If service is omitted, openTunnel() chooses a service at random and retries with the remaining services when a connection fails or does not provide a URL within 10 seconds. The startup deadline can be changed with the startupTimeout option.

Set a service's knownHosts field to pin its SSH host keys. The object maps OpenSSH host patterns to arrays of public keys; use the [hostname]:port form for a nonstandard port and list multiple keys during key rotation. Each key must be a single public-key line without the host pattern. When knownHosts is present, localtunnel uses only those keys from a private temporary known_hosts file, enables strict host-key checking, and removes the file when startup fails or the tunnel closes. Omitting knownHosts retains the legacy non-strict behavior. The built-in services in SERVICES have pinned keys.

For more information, see the API documentation.

Changelog

Version 0.5.0

Released on July 14, 2026.

• Added the knownHosts field to Service. Configured services now verify SSH host keys strictly using a private temporary known_hosts file that is removed after startup failure or tunnel shutdown.
• Pinned the current SSH host keys for the built-in Serveo and Pinggy services.

Version 0.4.0

Released on July 13, 2026.

• Added the services option to TunnelOptions and the CustomTunnelOptions type for callers that provide a custom registry. A custom registry replaces SERVICES for selection and retries.
• Exported the Service interface and SERVICES constant from the package entry point.
• The service and exclude options now accept service names from the selected registry instead of Service objects.
• Tunnel startup now times out after 10 seconds and falls back to another service when SSH fails, exits, or does not provide a URL.
• Updated the Serveo URL pattern for its current serveousercontent.com domains.
• Removed the "localhost.run" service from the default services registry as it is no longer functional.

Version 0.3.1

Released on July 13, 2026.

• Updated the host domain of "pinggy.io" service from a.pinggy.io to free.pinggy.io and updated its URL pattern.

Version 0.3.0

Released on August 31, 2025.

• Added support for Node.js and Bun.
• The package is now published on npm as well as JSR.
• Every field in Service, Tunnel, and TunnelOptions is now readonly.
• Added extraOptions and extraArgs fields to the Service interface.
• Added "pinggy.io" to the ServiceName type. [#1]

Version 0.2.0

Released on April 29, 2024.

• Added exclude option to TunnelOptions interface.
• Now openTunnel() automatically retries with another service if the first service fails.

Version 0.1.1

Released on April 28, 2024.

• Fixed a bug in openTunnel() that breaks standard input on Windows.
• Improved error handling in openTunnel().
• Added log messages using LogTape. The log category is ["localtunnel"].

Version 0.1.0

Initial release. Released on April 26, 2024.