skip to content
Sean Thawe
Table of Contents

When setting up my Raspberry Pi, I needed a simple way to expose a local web service to the internet for testing. Tunnelmole is a great tool for this, but getting it installed correctly required a few extra steps to avoid common issues with outdated software on Raspberry Pi OS.

This guide documents the problem I encountered and the reliable method I used to get Tunnelmole running perfectly.

This guide has been successfully tested on Raspberry Pi 3 and Raspberry Pi 4 running both Bullseye and Bookworm OS. The steps should be compatible with the latest Raspberry Pi models as well.

Part 1: The Problem - Initial Installation & Version Conflicts

My first attempt was to use the system’s default package manager, apt, to install npm and then use it to install Tunnelmole globally.

Terminal window
sudo apt install npm
sudo npm install -g tunnelmole

While the installation process completed, the output was filled with EBADENGINE warnings. This is a critical sign that the version of Node.js provided by the Raspberry Pi OS repositories (e.g., v12.22.12) is too old for Tunnelmole and its modern dependencies.

An application installed this way is unreliable and likely to crash or produce unexpected errors during use.

1.1. A Note on Architecture Mismatches

Another common issue, especially with generic installation scripts, is downloading a binary compiled for the wrong CPU architecture. For example, a command like curl -O https://install.tunnelmole.com/xD345/install && sudo bash install might fetch a version intended for x86-64 machines, which will not run on an ARM-based Raspberry Pi, leading to execution errors.

Using a Node.js package manager like npm helps prevent this by installing a version that is compatible with your Pi’s specific architecture.

Part 2: The Solution - Using Node Version Manager (nvm)

The best way to solve this is to bypass the system’s outdated Node.js package entirely. Node Version Manager (nvm) is a script that allows you to install and manage multiple, up-to-date versions of Node.js without interfering with the system.

2.1. Install nvm

First, I ran the official nvm installation script in my Pi’s terminal. This downloads the script from GitHub and executes it.

Terminal window
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

2.2. Activate nvm

The installation script automatically updates your .bashrc profile file, but the changes won’t apply to your current terminal session. You can either close and reopen your SSH session or run the following commands to activate it immediately:

Terminal window
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

2.3. Install the Latest Stable Node.js

With nvm active, I installed the latest Long-Term Support (LTS) version of Node.js. This is the most stable and recommended version for most projects.

Terminal window
nvm install --lts

To verify that the new version was active, I ran:

Terminal window
node -v

The output confirmed a modern version was now in use (e.g., v20.x.x or newer), which is exactly what Tunnelmole needs.

Part 3: Installing Tunnelmole Correctly

Now that the environment is set up with a modern version of Node.js, I could install Tunnelmole properly.

A key benefit of using nvm is that it installs packages to your user’s home directory, which means you no longer need to use sudo for global npm installations.

Terminal window
npm install -g tunnelmole

The installation completed successfully, and this time, there were no EBADENGINE warnings.

To confirm everything was working, I ran the help command:

Terminal window
tmole --help

It displayed the tool’s usage and options as expected. This method ensures a stable and reliable installation for any Node.js-based tool on a Raspberry Pi.

Part 4: Basic Usage

With Tunnelmole installed, you can now expose any local service to the internet. The most common use case is forwarding a local web server.

For example, if you have a service running on port 8080, you can make it publicly accessible with the following command:

Terminal window
tmole 8080

Tunnelmole will generate a public URL (e.g., https://random-subdomain.tunnelmole.net) that tunnels traffic directly to your Raspberry Pi’s port 8080. Anyone with this URL can now access your local service.

Part 5: References & Further Reading

For more information on the tools and concepts used in this guide, check out these excellent resources: