⚡ TunnelMate by Shashan Lumbhani

Production-Grade Cloudflare Quick Tunnel Manager & Cross-Platform Ingress Orchestrator
Seamless Localhost Ingress, Background Daemon, Multi-Device SSH Discovery, Server-Side Session Security, and Telegram Bot Remote Management.

Author: Shashan Lumbhani
License: MIT License
Supported Platforms: Linux, macOS, Windows (PowerShell / CMD / WSL)
Python Compatibility: Python 3.10+

📑 Table of Contents

• ⚡ TunnelMate by Shashan Lumbhani
  • 📑 Table of Contents
  • 🚨 The Problem Statement
  • 💡 The Solution: What TunnelMate Delivers
  • 🎯 Real-World Use Cases
  • 🏛️ System Architecture
  • 🚀 Installation & Setup
    • 📦 Option 1: Install via PyPI (Recommended)
    • Option 2: Automated Installer (Linux / macOS)
    • Option 3: Automated Installer (Windows PowerShell)
    • Option 4: Install from Source (Manual)
  • 🏁 Quick Start Guide
  • ⚡ Multi-Device SSH Ingress (tunnelmate-ssh)
  • 🤖 Telegram Bot Remote Management
    • 1. Configuration
    • 2. Bot Process Control
    • 3. Server-Side Session Management
    • 4. Telegram Bot Chat Interface
  • 🔁 Reboot Persistence & Daemon Autostart
  • 🖥️ Complete CLI Command Reference
  • 🐍 Python Library API
  • 🔒 Security & Privacy Architecture
  • 🧪 Test Suite & Validation
  • 📄 License & Credits

🚨 The Problem Statement

Modern software engineers, system administrators, and homelab builders face significant friction when trying to expose local servers or remotely access machines behind private networks:

1. Carrier-Grade NAT (CGNAT) & Dynamic IPs:
   Most residential ISPs, mobile 4G/5G hotspots, university Wi-Fi, and corporate intranets place devices behind Carrier-Grade NAT. There is no publicly routable IPv4 address, and incoming ports cannot be opened on the upstream router.
2. Ephemeral URL Instability & Process Death:
   Standard Cloudflare Quick Tunnels (cloudflared tunnel --url http://localhost:8080) are helpful, but closing the terminal or a transient network glitch terminates the tunnel. The newly assigned https://*.trycloudflare.com URL changes every restart, requiring manual re-discovery and copy-pasting.
3. Reboot Amnesia (No Persistence Across Restarts):
   When a machine restarts or updates, running tunnel processes and management bots do not automatically recover without complex custom scripting. For headless servers, home workstations, and IoT gateways, this results in extended outages.
4. Multi-Device SSH Remote Access Chaos:
   Managing remote SSH into multiple physical machines (e.g. office workstation, development laptop, home server) requires tracking different URLs, changing hostnames, and figuring out which machine has which URL active.
5. OpenSSH ProxyCommand Configuration Complexity:
   Connecting to an SSH server over Cloudflare requires configuring ProxyCommand cloudflared access ssh --hostname %h inside ~/.ssh/config on every single client computer, downloading the appropriate cloudflared binary for the OS, and specifying exact flags.
6. Security, Privacy & Notification Leaks:
   Naive remote-management bots broadcast sensitive live tunnel URLs to anyone who triggers /start in Telegram. Without strict server-side session authentication, unauthorized chat users can discover private tunnels and access internal services.

💡 The Solution: What TunnelMate Delivers

TunnelMate by Shashan Lumbhani is an all-in-one tunnel management and remote ingress orchestrator that eliminates these hurdles:

🎯 Real-World Use Cases

1. Remote SSH Access to CGNAT / Home Servers

Connect to your home workstation, Raspberry Pi, or local VM from anywhere in the world (coffee shop, airport, office) without a static public IP, port forwarding, or third-party VPN configurations.

2. Multi-Machine Fleet SSH Management (tunnelmate-ssh)

Run TunnelMate across your laptop, desktop, and remote server with the same Telegram Bot token. Launch tunnelmate-ssh on your client machine to instantly see all active devices, select one with arrow keys, and SSH in seamlessly.

3. Ephemeral Webhook & Payment Gateway Testing

Instantly expose local HTTP servers (FastAPI, Next.js, Django, Express, Flask) to public webhooks from Stripe, GitHub, Shopify, or PayPal with secure HTTPS URLs.

4. Client Demonstrations & Staging Previews

Share live work-in-progress web applications directly from your local development machine with clients or team members without deploying to staging servers.

5. Remote Server Management from Mobile (Telegram Bot)

Monitor your host machine from your phone: start, stop, or restart tunnels, change forwarded ports, inspect daemon statistics, run health checks, and receive real-time alerts when URLs update.

6. Dynamic Port Remapping for Multi-Service Workflows

Switch target ports on the fly (e.g. from port 3000 to 8080) using tunnelmate port <name> <new_port>. TunnelMate safely swaps the running process without breaking tunnel configurations.

7. Automated CI/CD Preview Environments

Integrate tunnelmate url <name> into automated CI/CD scripts to launch temporary test tunnels and export live URLs for integration tests.

🏛️ System Architecture

┌─────────────────────────────────┐       ┌─────────────────────────────────┐
│     Interactive TUI / CLI       │       │       Telegram Bot Client       │
│    (Questionary + Rich + Typer) │       │   (Session Auth + Notifications)│
└────────────────┬────────────────┘       └────────────────┬────────────────┘
                 │                                         │
                 │          Unix Domain Socket IPC         │
                 │      (mode 0600) / Local TCP Fallback   │
                 └───────────────────┬─────────────────────┘
                                     │
                  ┌──────────────────▼──────────────────┐
                  │       TunnelMate Daemon Service     │
                  │  ┌───────────────────────────────┐  │
                  │  │       Async IPC Server        │  │
                  │  └───────────────┬───────────────┘  │
                  │                  │                  │
                  │  ┌───────────────▼───────────────┐  │
                  │  │       Tunnel Supervisor       │  │
                  │  │  (Auto-Recovery & Health)     │  │
                  │  └───────┬───────────────┬───────┘  │
                  └──────────┼───────────────┼──────────┘
                             │               │
            ┌────────────────▼─┐           ┌─▼────────────────┐
            │   cloudflared    │           │ SQLite Database  │
            │   Subprocesses   │           │   (WAL Mode)     │
            │ (no shell=True)  │           └──────────────────┘
            └──────────────────┘

🚀 Installation & Setup

📦 Option 1: Install via PyPI (Recommended)

Install the library and CLI directly from PyPI:

pip install tunnelmate-cli

(On systems with PEP 668 managed environments, use pip install tunnelmate-cli --break-system-packages or install in a virtual environment / pipx).

Once installed, download the official Cloudflare cloudflared binary with one command:

tunnelmate install-cloudflared

You now have full access to both tunnelmate and tunnelmate-ssh commands!

Option 2: Automated Installer (Linux / macOS)

chmod +x install.sh
./install.sh

The script will:

1. Verify Python 3.10+
2. Download official cloudflared binary for your architecture (x86_64, aarch64, armv7)
3. Initialize ~/.tunnelmate state directory with secure 0700 permissions
4. Install tunnelmate and tunnelmate-ssh into your environment
5. Register systemd user service units for background operation

Option 3: Automated Installer (Windows PowerShell)

Run the included PowerShell installer in PowerShell:

powershell -ExecutionPolicy Bypass -File .\install.ps1

The script will:

1. Verify Python 3.10+
2. Auto-download official cloudflared.exe for Windows
3. Initialize %USERPROFILE%\.tunnelmate state directory
4. Install tunnelmate and tunnelmate-ssh CLI executables

Option 4: Install from Source (Manual)

# Clone the repository
git clone https://github.com/soni-shashan/tunnelmate.git
cd tunnelmate

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install TunnelMate in editable mode
pip install -e .

# Auto-download official cloudflared binary
tunnelmate install-cloudflared

🏁 Quick Start Guide

Step 1: Start the Background Daemon

tunnelmate daemon start

Verify daemon status:

tunnelmate daemon status

Step 2: Open the Interactive Arrow-Key TUI Menu

Simply run:

tunnelmate

(or explicitly: tunnelmate menu)

The interactive menu lets you create, start, stop, restart tunnels, remap ports, view live logs, inspect daemon stats, manage Telegram Bot settings, and connect via SSH.

Step 3: Direct CLI Commands

# Create a tunnel for a web server on port 8080
tunnelmate create my-web --port 8080

# Create a password-protected tunnel (Approach A)
tunnelmate create secure-app --port 8080 --auth --password "MySecretPass123"

# Enable or update password on an existing tunnel
tunnelmate auth my-web --password "MySecretPass123"

# Disable password protection
tunnelmate auth my-web --disable

# Create an SSH tunnel for local port 22
tunnelmate create my-ssh --port 22 --protocol tcp

# Start the tunnel and get the live trycloudflare.com URL
tunnelmate start my-web

# Print only the URL (ideal for shell scripts)
tunnelmate url my-web

# Remap target port on the fly (e.g. from 8080 to 3000)
tunnelmate port my-web 3000

# Run diagnostics on local port & Cloudflare ingress
tunnelmate health my-web

# View real-time logs (last 50 lines)
tunnelmate logs my-web --lines 50

# List all configured tunnels
tunnelmate list

# Stop a tunnel
tunnelmate stop my-web

# Delete a tunnel
tunnelmate delete my-web --yes

🔒 Password Protection & API Authentication

TunnelMate features built-in password protection for HTTP/HTTPS tunnels. When password protection is enabled, Cloudflare routes ingress traffic through an internal zero-overhead authentication reverse proxy (AuthProxyServer) running on 127.0.0.1 before forwarding verified requests to your local application port.

🌐 For Web Browsers

• Visitors opening the trycloudflare.com link in a browser are presented with a modern, glassmorphic dark-mode password gate branded with ⚡ TunnelMate by Shashan Lumbhani.
• Upon entering the correct password, a cryptographically signed HMAC tunnelmate_session cookie is issued (HTTP-only, Lax, 24-hour expiration).
• Subsequent browsing, navigation, asset loading, and form posts pass through transparently to your local web application.

⚡ For APIs, Scripts, & Webhooks (GET, POST, PUT, DELETE, PATCH, etc.)

Microservices, mobile apps, CI/CD webhooks, and REST clients do not need to navigate browser cookies. Simply send the password in any request header:

# Method 1: Using X-TunnelMate-Password header
curl -H "X-TunnelMate-Password: MySecretPass123" https://your-tunnel.trycloudflare.com/api/data

# Method 2: Using Authorization Bearer token header
curl -H "Authorization: Bearer MySecretPass123" https://your-tunnel.trycloudflare.com/api/data

# POST / PUT request with JSON payload:
curl -X POST https://your-tunnel.trycloudflare.com/api/submit \
  -H "X-TunnelMate-Password: MySecretPass123" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

Both browser apps and automated API consumers operate simultaneously on the exact same tunnel!

Managing Password Protection

• Interactive Menu (tunnelmate): Select any tunnel and choose 🔒 Configure Password Protection to enable, update, or disable passwords with hidden input.
• Direct CLI:
  • tunnelmate auth <name> --password <pwd> (enables/updates password)
  • tunnelmate auth <name> --disable (disables password protection)
• Telegram Bot:
  • Create protected tunnels: /create <name> <port> [protocol] [password]
  • Real-time tunnel details show 🔒 Enabled or 🔓 Disabled status.

⚡ Multi-Device SSH Ingress (tunnelmate-ssh)

TunnelMate includes a specialized tunnelmate-ssh client that turns any SSH tunnel into a frictionless remote shell without touching ~/.ssh/config:

# 1. Interactive Mode: Auto-discover all SSH tunnels from your Telegram Bot
tunnelmate-ssh

# 2. Discover SSH tunnels using a specific Bot Token:
tunnelmate-ssh --token <YOUR_TELEGRAM_BOT_TOKEN>

# 3. List active SSH tunnels discovered from your bot:
tunnelmate-ssh --list

# 4. Direct non-interactive connection:
tunnelmate-ssh user@<trycloudflare_url>

# Examples:
tunnelmate-ssh shashansoni@subjective-lenses-working-subscription.trycloudflare.com
tunnelmate-ssh root@https://my-app.trycloudflare.com -i ~/.ssh/id_rsa

How Multi-Device Discovery Works:

1. Each host machine running TunnelMate publishes its active SSH tunnels to private Telegram Bot metadata using token-derived encryption.
2. The payload contains the machine's detected hostname, device model, and current OS username (e.g. shashansoni).
3. Running tunnelmate-ssh on any client machine decrypts the registry and displays all online devices.
4. Selecting a machine auto-configures the Cloudflare ProxyCommand bridge and opens an SSH session immediately.

🤖 Telegram Bot Remote Management

TunnelMate includes a full-featured Telegram Bot interface for remote mobile management.

1. Configuration

# 1. Set Telegram Bot token (from @BotFather)
tunnelmate bot set-token "123456789:ABCdefGhIJKlmNoPQRstuVWXyz"

# 2. Set salted SHA-256 administrator password
tunnelmate bot set-password "YourStrongPassword"

# 3. View discovered chat IDs from recent interactions
tunnelmate bot chats

# 4. Whitelist a Chat ID as Administrator
tunnelmate bot whitelist <CHAT_ID>

2. Bot Process Control

# Start Telegram bot in background (enables auto-restore on reboot)
tunnelmate bot start

# Check bot running status & PID
tunnelmate bot status

# Stop background bot (disables auto-restore on reboot)
tunnelmate bot stop

3. Server-Side Session Management

Strict server-side session management guarantees that unauthenticated users cannot see live links or receive notifications:

# Inspect all registered chat IDs and their active session status
tunnelmate bot sessions

# Revoke all active sessions on the server (logs out all users immediately)
tunnelmate bot revoke-sessions

4. Telegram Bot Chat Interface

• /start — Opens the main interactive control hub. Unauthenticated users see restricted menus with no tunnel links.
• /login <password> — Authenticates the user as an Administrator (the password message is auto-deleted for privacy).
• /logout — Clears the active admin session and revokes access.
• /create <name> <port> [protocol] [password] — Creates a new tunnel (optional password protection) directly from chat.
• /auth <name> <password|disable> — Enables, updates, or disables password protection with zero URL changes.
• /port <name> <new_port> — Updates the target port for an existing tunnel.
• /cancel — Aborts an active interactive password prompt.
• Inline Menus:
  • [📋 Tunnels List] — View running and stopped tunnels across local and remote devices.
  • [▶️ Start] / [⏹️ Stop] / [🔄 Restart] — Full real-time process controls.
  • [🔗 Latest Link] — Retrieve active URL with one-click [🌐 Open in Browser] button.
  • [🔒 Password Auth] / [🔓 Add Password] — Interactive password management sub-menu:
    • [🔑 Set / Change Password] — Type the new password in chat (auto-deleted instantly for privacy; preserves public URL).
    • [🔓 Disable Password Protection] — 1-click disable (instant public access; preserves public URL).
  • [🩺 Health Check] — Diagnose target service and Cloudflare edge status.
  • [🔔 Notifications] — Opt in/out of real-time alerts when URLs update or tunnels recover.

🔁 Reboot Persistence & Daemon Autostart

TunnelMate includes an auto-restoration engine:

# Check current autostart configuration
tunnelmate autostart status

# Enable autostart on system boot / restart
tunnelmate autostart enable

# Disable autostart on boot
tunnelmate autostart disable

When enabled:

• If the Daemon was running before a reboot, it starts automatically on system startup and restores all active tunnels.
• If the Telegram Bot was running before a reboot, it relaunches in the background and restores tunnel synchronization.

Systemd User Services (Linux)

mkdir -p ~/.config/systemd/user
cp systemd/tunnelmate-daemon.service ~/.config/systemd/user/
cp systemd/tunnelmate-bot.service ~/.config/systemd/user/

systemctl --user daemon-reload
systemctl --user enable --now tunnelmate-daemon
systemctl --user enable --now tunnelmate-bot

# Keep services active without an open SSH login session:
loginctl enable-linger $USER

🖥️ Complete CLI Command Reference

Main Commands

Daemon Commands (tunnelmate daemon)

Telegram Bot Commands (tunnelmate bot)

🐍 Python Library API

Install TunnelMate as a library in your project:

pip install tunnelmate-cli

Then embed TunnelMate directly into your Python scripts and services:

from tunnelmate.client import TunnelMateClient

client = TunnelMateClient()

# Check daemon connectivity
if not client.is_daemon_online():
    print("Daemon is offline. Start with 'tunnelmate daemon start'")
    exit(1)

# Create and start a tunnel
client.create_tunnel(name="fastapi-app", port=8000)
tunnel = client.start_tunnel("fastapi-app")
print(f"Public Quick Tunnel URL: {tunnel.current_url}")

# Health diagnostics
health, details = client.check_health("fastapi-app")
print(f"Status: {health.value} -> {details['message']}")

# Change target port dynamically
client.change_port("fastapi-app", 8080)

# Stop tunnel
client.stop_tunnel("fastapi-app")

🔒 Security & Privacy Architecture

1. Subprocess Isolation (No shell=True):
   All cloudflared instances are spawned using explicit argument lists via subprocess.Popen without shell=True. Process groups prevent orphan or zombie processes.
2. Restricted Unix Domain Socket:
   The IPC socket (~/.tunnelmate/tunnelmate.sock) is strictly restricted to filesystem permissions 0600 (read/write only by the owning user).
3. State Directory Permissions:
   The configuration and SQLite database directory ~/.tunnelmate is initialized with permissions 0700.
4. Salted SHA-256 Authentication:
   Admin passwords use high-entropy random salts (secrets.token_hex(16)) and SHA-256 hashing. Password verification uses constant-time string comparisons (secrets.compare_digest) to prevent timing attacks.
5. Private Encrypted SSH Tunnel Metadata:
   Published SSH tunnels are encrypted with token-derived keys (counter-mode HMAC keystream + SHA-256 HMAC authentication) and stored under hidden language tags. Public visitors to the bot see only the default description.
6. Server-Side Session Verification:
   Broadcast notifications are strictly restricted to subscribers with an active, authenticated server session (is_authenticated == True). Logged-out users receive zero URLs.

🧪 Test Suite & Validation

TunnelMate comes with a comprehensive test suite covering database operations, IPC serialization, process lifecycle, password hashing, SSH discovery, and session security:

# Run all unit and integration tests
pytest -v tests/

Test coverage includes:

• test_cross_platform.py — Process termination, cross-platform paths, reboot persistence, session revocation, and notification security.
• test_ssh_discovery.py — Hostname parsing, token keystream encryption/decryption, username/device detection, and multi-device merging.
• test_db.py — SQLite schema migrations, WAL mode transactions, subscriber preferences, and session tracking.
• test_config.py — Salted password hashing, configuration serialization, and validation.
• test_ipc.py — Unix socket / TCP client-server roundtrips and serialization.
• test_cli.py — Typer CLI command dispatch, formatting panels, and help outputs.
• test_health.py — Ephemeral HTTP origin and TCP latency verification.

📄 License & Credits

Created by Shashan Lumbhani (lumbhanishashan1510@gmail.com).
Distributed under the MIT License. See LICENSE for details.

Built with ❤️ for seamless, secure localhost ingress across every device.