TunnelSats: Hybrid Lightning Node Setup

Overview

TunnelSats simplifies running a hybrid Lightning node by routing clearnet traffic through a VPN while maintaining Tor connectivity. This guide helps you configure your node for optimal reliability, liquidity, and discoverability.

Key Benefits:

• Clearnet connectivity for faster routing
• Privacy-preserving VPN tunneling
• Tor fallback for additional privacy
• Simplified setup process

Important: Review this entire guide before proceeding. Understand the implications of exposing clearnet connections before enabling hybrid mode.

Prerequisites

Supported Node Platforms

• RaspiBlitz (LND/CLN) v1.8.0+
• Umbrel (LND) v0.5+ on Raspberry Pi
• myNode (LND) v0.2.x
• RaspiBolt (LND/CLN)
• Bare Metal Systems meeting these requirements:
  • Debian/Ubuntu-based OS (apt-get required)
  • Linux kernel 5.10.102+ (check: uname -r)
  • nftables 0.9.6+ (check: nft -v)
  • LND/CLN running as systemd service

Software Requirements

• LND 0.14.2-beta minimum (latest recommended)
• CLN latest version
• Only one Lightning implementation per system (port 9735)
• Ability to edit configuration files
• Small amount of sats for subscription payment

System Check: Run sudo bash tunnelsats.sh check to verify compatibility.

How It Works

TunnelSats operates in three stages:

1. VPN Subscription – Rent a WireGuard server from tunnelsats.com and obtain your configuration file
2. Software Installation – Install WireGuard, nftables, and split-tunneling components
3. Node Configuration – Update your Lightning node settings for hybrid mode

Installation

Step 1: Subscribe to TunnelSats

1. Visit tunnelsats.com
2. Select a server location (choose one close to your physical location for best performance)
3. Choose subscription duration (1-12 months)
4. Pay the Lightning invoice
5. Download the tunnelsats_<server>.conf file (e.g., tunnelsats_us3.conf)

Critical: Back up your configuration file to a safe location (e.g., /mnt/hdd/app-data/tunnelsats/ on RaspiBlitz).

Step 2: Install TunnelSats Software

Download the unified setup script on your node:

bash
wget -O tunnelsats.sh https://raw.githubusercontent.com/Tunnelsats/tunnelsats/main/scripts/tunnelsats.sh
# Checksum (SHA256): 65a6da73e05039eab846379b02268e90baff11f1a7730b0bdf8bfaf7ad2965e2

Always verify the integrity of executed scripts. Run sha256sum tunnelsats.sh and compare the output with the checksum displayed above to ensure the file hasn't been tampered with.

Transfer your WireGuard configuration to your node (if not already there):

bash
scp tunnelsats_us3.conf <user>@<hostname>:/<home-directory>

Example for Umbrel:

bash
scp tunnelsats_us3.conf [email protected]:/home/umbrel/

Ensure both files (tunnelsats_us3.conf and tunnelsats.sh) are in the same directory, then run the installer:

bash
sudo bash tunnelsats.sh install

Upon successful completion, the script displays your VPN credentials and configuration parameters. Save these values – you'll need them to configure your Lightning node.

Configuration

Before proceeding: Back up your configuration file!

bash
cp /path/to/lnd.conf /path/to/lnd.conf.backup

Choose your Lightning implementation below:

Verification

Once you've completed the configuration, verify that your connection is working by running:

sh
sudo bash tunnelsats.sh status

This acts as a "Headless Status Page" for your node, checking VPN connectivity, Tor status, and Public IP visibility.

Subscription Renewal

Extend your subscription without reconfiguration:

1. Visit tunnelsats.com → Renew Subscription
2. Enter your WireGuard public key (found in tunnelsats_*.conf as # myPubKey).
3. Click Query Key Info to view your current expiry date
4. Select extension duration (appends to current expiry)
5. Click Update Subscription and pay the invoice

Alternately, you can manage your subscription directly in My Dashboard.

In either case, your existing configuration remains valid – no changes needed.

Uninstallation

To remove TunnelSats and restore your original configuration:

bash
sudo bash tunnelsats.sh uninstall

Restore your Lightning configuration from the backup you created earlier. The uninstall script removes hybrid mode settings to prevent IP leakage.

Technical Details

What does tunnelsats.sh do?

This unified script manages the entire lifecycle of the TunnelSats connection:

1. Install: Installs components (wireguard, cgroup-tools, nftables), configures split-tunneling, and creates systemd services.
2. Status: Provides a comprehensive health check of the connection.
3. Uninstall: Cleanly removes all components and restores network settings.
4. Restart: Restarts the TunnelSats service. (Warning: Stops and restarts your lightning services to avoid IP leakage)
5. Pre-Check: Checks if your node is compatible with TunnelSats.

Support

• FAQ: Review common questions
• Telegram: Join Tunnel⚡Sats for community support
• GitHub: Report issues