Tunnelmole Client: Public URLs for Local HTTP Services

Tunnelmole Client Exposes Local HTTP Applications

Tunnelmole Client addresses a specific local-development problem. An application may listen successfully on a developer’s machine while remaining unreachable to a webhook provider, phone, collaborator, or remote client because `localhost` is private to that machine. Tunnelmole creates a public `tunnelmole.net` URL that routes requests to a selected local port.

The README names web servers, Docker containers, APIs, React or Node applications, and static websites as suitable targets. The `package.json` description narrows the purpose further by referring to “http/https based application.” Tunnelmole is therefore positioned as a client for publishing an HTTP service during development, not as a general-purpose tunnel for arbitrary network protocols.

Its intended audience includes developers testing webhooks, checking a site on a physical phone, sharing unfinished work, or validating HTTPS-dependent browser behavior. Public URLs make those tests straightforward, but they also make the endpoint reachable by anyone who obtains the URL. The README does not document authentication, request filtering, or a private tunnel option. Teams exposing an authenticated application must therefore verify that protection exists inside the application rather than assuming the public URL provides access control.

Client Repository and Remote Service Roles

The repository is a TypeScript client package named `tunnelmole`, with package version `2.3.9`. Its structure includes `src/`, `bin/`, `cjs/`, tests, message handlers, configuration files, and TypeScript build configuration. The package manifest exposes compiled JavaScript and type declarations as the main package interface. It also identifies both CLI and npm integration as supported forms of use.

The documented request path begins with a local application listening on a port. The client starts with that port and receives public HTTP and HTTPS URLs from the Tunnelmole service. Those addresses forward traffic to the local listener, illustrated in the README by `localhost:8080`. The client therefore supplies the local-side integration, while a separate service receives public traffic and establishes the connection used to reach that client.

The remote service is not contained in this repository. The README links self-hosting instructions to the separate `robbie-cahill/tunnelmole-service` repository. Installing `tunnelmole` alone does not install the complete service. This distinction matters for engineers who require control of hosting, network routing, or service availability, because those decisions belong to the service deployment rather than the client package alone.

Installing Tunnelmole and Opening the First Tunnel

The README supports NodeJS 16.10 or later for installation through npm. A first use consists of starting the local application, noting its listening port, and running the `tmole` command with that port. The documented global installation is:

sudo npm install -g tunnelmole

For an application listening on port `8080`, create the public tunnel with:

tmole 8080

The reader should see HTTP and HTTPS forwarding addresses printed by the command. The README’s example says those addresses are forwarding to `localhost:8080`. Either URL can then be opened from the same machine or another network-connected device.

For Linux, macOS, and Windows Subsystem for Linux, the README also documents a precompiled installation route:

curl -O https://install.tunnelmole.com/xD345/install && sudo bash install

The README states that the script detects the operating system and installs the appropriate binary. It also says the precompiled binary includes Node, so this path does not require a separately installed Node version. On native Windows, the README directs users to download `tmole.exe` and put it in `PATH`. Because the npm command uses `sudo`, administrators may instead install under a controlled user account, although the README does not prescribe that alternative.

Node.js API, Modules, and Quiet Mode

Tunnelmole is also published as an npm dependency for application-level integration. The documented command is:

npm install --save tunnelmole

The README documents both ES module and CommonJS imports. An ES module can start the tunnel for port `3000` as follows:

import { tunnelmole } from 'tunnelmole';

const url = tunnelmole({
    port: 3000
});
// url = https://idsq6j-ip-157-211-195-169.tunnelmole.net

The README calls the function `async` and says it starts Tunnelmole in the background without blocking the rest of the application. A custom domain can be supplied through the `domain` option:

const url = tunnelmole({
    port: 3000,
    domain: '<your tunnelmole domain e.g. mysite.tunnelmole.net>'
});

Initial URL output can be suppressed with the documented `TUNNELMOLE_QUIET_MODE=1` environment variable. That option is relevant to scripts that parse their own output, although the README only identifies CI/CD and other scripts as possible use cases. It does not document the function’s return type, failure value, shutdown mechanism, or reconnect behavior. Those omissions limit how confidently the API can be embedded in a long-running production process.

Custom Subdomains and npm Script Integration

Generated Tunnelmole URLs suit short test sessions, but a webhook consumer may need to retain the same hostname across sessions. The CLI documents custom subdomains through this syntax:

tmole 8080 as <yourdomain>.tunnelmole.net

The README says custom subdomains require a purchased subscription when the default hosted service is used. It points to the separate service repository for self-hosting. Although the default hosted configuration is described as free, the README does not guarantee that an automatically generated subdomain remains unchanged. Engineers requiring a fixed callback hostname should check the service terms rather than rely on a generated name.

An npm dependency also installs project-local executables at `node_modules/.bin/tmole` and `node_modules/.bin/tunnelmole`. The README says both behave like the command-line application. Its example connects the tunnel to an npm script:

{
    "name": "myapp",
    "version": "0.0.1",
    "scripts": {
        "start": "dist/index.js",
        "start-public": "npm run start && tmole 3000"
    }
}

That script starts the application before exposing port `3000`. It does not define shutdown handling, readiness checks, or a restart policy. The README is therefore useful as a quick integration example rather than a complete production process definition.

Hosted and Self-Hosted Tunnelmole Paths

The README compares Tunnelmole with ngrok and describes Tunnelmole as open source. That naming should not be mistaken for a complete capability comparison: the README does not enumerate matching features or explain whether Tunnelmole supports every ngrok workflow. Its documented distinction is architectural and commercial. The default path uses Tunnelmole’s hosted service, while the client can be paired with a separately operated service.

The hosted path minimizes server-side setup for a developer. It generates public addresses, offers HTTPS under the default configuration, and reserves custom subdomains for subscribers. Its trade-off is dependence on an external service whose authentication model, retention policy, limits, and availability guarantees are not documented in this README.

The self-hosted path is described through a link to `tunnelmole-service`, not through instructions in this repository. Engineers adopting that route must inspect that service separately for installation, network exposure, certificate management, scaling, and access control. Tunnelmole Client is consequently the wrong choice when an organization expects a single package to provide the entire tunnel system, or when it cannot permit public traffic to pass through a hosted endpoint.

Tunnelmole Maintenance, Licensing, and Upgrade Checks

The client repository uses the MIT license. That license applies to the client code, but it does not settle the terms of the hosted service, subscriptions, or the separate service repository. Engineers using the hosted offering should review its own documentation and account terms rather than assume that the client’s MIT license applies to the hosted infrastructure.

The repository is not archived. Its last push was on 2026-04-13, which is more than six months before 2026-10-17, so its maintenance status should not be described as active based on repository activity. GitHub releases are not listed, and `package.json` reports version `2.3.9`. The available record therefore shows a package version and push history but no GitHub release cadence.

Upgrade work is easier to scope for npm users because the repository contains `package-lock.json`, `CHANGELOG.md`, build configuration, and scripts for building, linting, testing, and producing platform binaries. The README does not document a migration procedure or compatibility policy. Before replacing a working installation, an engineer should compare `CHANGELOG.md`, review the package diff, and verify that the service endpoint still accepts the selected client.

Editorial conclusion

Tunnelmole Client fits developers who need a temporary public HTTP endpoint for webhook testing, cross-device work, collaboration, or a local demonstration. It is less suitable for workflows that need undocumented access controls, guaranteed hostname stability on the free hosted service, or complete control over the tunnel infrastructure. Check the public exposure model first, then determine whether the default service or the separate `tunnelmole-service` repository satisfies your network and operational requirements.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. robbie-cahill/tunnelmole-client on GitHub