⚡ 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
  • 🔒 Password Protection & API Authentication
  • 🔗 Origin Link Rewriting (Replace URLs)
  • 📈 Live Resource Usage Monitor (tunnelmate-top)
  • 🪟 Universal Windows & Linux Compatibility
  • ⚡ 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:

Challenge	How TunnelMate Solves It
CGNAT & Closed Routers	Creates secure outbound tunnels to Cloudflare's global edge network. Zero port forwarding, zero router configuration, and zero custom domain registration required.
Process Death & URL Loss	A background daemon runs continuously, supervises cloudflared subprocesses, detects disconnections, and auto-recovers with exponential backoff while persisting state in a WAL-mode SQLite database.
Dynamic In-Place Updates	Reverse proxy architecture allows remapping ports (tunnelmate port <name> <port>) and toggling security in-place without downtime and without changing the public URL.
Broken Origin Links on Ingress	Built-in Link Rewriting scans and dynamically replaces local origin URLs (e.g. http://172.16.11.180:8090) with public tunnel URLs across HTML, JS, CSS, JSON, and redirects.
System Restarts / Reboots	Built-in autostart engine restores running tunnels and the Telegram Bot automatically when the operating system boots up.
Resource & Component Visibility	Interactive tunnelmate-top provides live CPU, RAM, thread count, and process status for TunnelMate and Cloudflare components.
Multi-Device SSH Discovery	Uses Telegram Bot metadata as a private, token-encrypted registry. Any number of devices can publish their active SSH tunnels, and the tunnelmate-ssh client discovers and presents them in an interactive menu with hostnames, devices, and detected usernames.
ProxyCommand Headache	The tunnelmate-ssh CLI automatically locates or installs cloudflared and dynamically establishes the OpenSSH ProxyCommand bridge on Linux, macOS, and Windows.
Windows Flashing CMD Windows	Suppresses console popups via CREATE_NO_WINDOW and hidden startupinfo; automatically tunes console code pages to UTF-8 and enables Virtual Terminal Processing.
Security & Privacy Leaks	Telegram notifications and menus are strictly gated behind server-side session authentication. Logged-out users receive 0 URLs or alerts. Administrators can view active sessions via tunnelmate bot sessions and revoke access instantly via tunnelmate bot revoke-sessions.

---

🎯 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.

---

🔗 Origin Link Rewriting (Replace URLs)

When exposing internal web applications, development servers, or private dashboards through a tunnel, applications frequently generate internal links, asset paths, or HTTP redirects pointing back to the internal address (such as http://172.16.11.180:8090/ or http://localhost:3000/). Browsing from external networks or mobile devices results in broken page rendering, asset loading failures, or endless buffering because the external browser attempts to contact private IP addresses directly.

TunnelMate's reverse proxy engine includes transparent Origin Link Rewriting:

# Enable origin link rewriting when creating a tunnel
tunnelmate create my-dashboard --port http://172.16.11.180:8090/ --rewrite-links

# Enable link rewriting on an existing tunnel
tunnelmate replace-links my-dashboard --enable

# Disable link rewriting
tunnelmate replace-links my-dashboard --disable

How Link Rewriting Operates:

1. Bidirectional Header Translation (Zero Server Rejections):
   • Preserves backend Host as {target_host}:{target_port} so frameworks with strict host validation (e.g. Django ALLOWED_HOSTS, Vite Invalid Host header, Ruby on Rails) never reject incoming requests with 400 Bad Request.
   • Translates incoming Origin and Referer headers back to the local origin address so backend CSRF and CORS protections pass without 403 Forbidden.
   • Strips restrictive Domain= attributes from Set-Cookie so session cookies bind cleanly to trycloudflare.com.
2. Deep Body & API Rewriting:
   • Rewrites plain URLs (http://172.16.11.180:8090 → https://xxx.trycloudflare.com).
   • Rewrites JSON-escaped URLs (http:\/\/172.16.11.180:8090 → https:\/\/xxx.trycloudflare.com) in API payloads and embedded scripts.
   • Rewrites URL-encoded parameters (e.g. OAuth callbacks, redirect_uri).
   • Rewrites quoted host/port configurations in JavaScript and JSON configs.
3. Client-Side Interceptor Shim:
   • Injects a lightweight (<1KB) zero-dependency browser interceptor into HTML responses.
   • Intercepts window.fetch, XMLHttpRequest.prototype.open, window.open, navigator.sendBeacon, history.pushState, form submissions, and hyperlink clicks.
   • Automatically re-routes dynamically assembled in-flight requests and button actions to the public tunnel, guaranteeing zero leaked redirects.
4. Transparent Decompression:
   • Handles compressed responses (gzip, deflate, brotli), decompresses in-memory, rewrites matching URLs, and recalculates Content-Length transparently.
5. Zero Code Changes:
   • Your internal services, web apps, and frameworks function immediately without having to configure reverse-proxy base URLs or reverse-proxy headers manually!

---

📈 Live Resource Usage Monitor (tunnelmate-top)

TunnelMate provides an interactive terminal resource monitor inspired by htop and top, designed specifically for TunnelMate, Cloudflare, and connected ingress components:

# Launch interactive live monitor
tunnelmate-top

# Or launch through the tunnelmate CLI:
tunnelmate top

# Or select "📈 Live Resource Monitor (tunnelmate-top)" inside the interactive TUI menu:
tunnelmate

Key Capabilities:

• Dedicated Component Isolation: Samples metrics specifically for TunnelMate Daemon, Telegram Bot, Cloudflare worker processes (cloudflared), and local target processes.
• Accurate Resource Measurement: Tracks real-time CPU % (interval deltas), physical RAM (RSS), Virtual Memory (VMS), thread count, uptime, and operational status.
• Interactive Hotkeys:
  • [q] / [Esc] — Quit monitor
  • [r] — Force instant metrics refresh
  • [s] — Cycle sort column (CPU, RAM, NAME, PID)
  • [Space] / [p] — Pause / Resume live polling
  • [+] / [-] — Increase or decrease poll interval (0.5s to 5.0s)
  • [h] / [?] — Display on-screen keyboard shortcut cheat sheet
• Scriptable Snapshot Mode:

  # Output a single snapshot table and exit (ideal for cron, CI, or shell scripts)
  tunnelmate-top --once
  

---

🪟 Universal Windows & Linux Compatibility

TunnelMate is engineered for seamless operation across Windows (Command Prompt, PowerShell, Windows Terminal) and all Linux distributions (Ubuntu, Debian, Fedora, Arch, Alpine, headless servers):

1. Zero Flashing / Blank CMD Windows on Windows:
   • On Windows, subprocesses use CREATE_NO_WINDOW (0x08000000) and STARTUPINFO with STARTF_USESHOWWINDOW and SW_HIDE (0).
   • Running tunnels or background daemons creates zero blank popup console windows.
2. Automatic Terminal Code Page & Virtual Terminal Tuning:
   • On startup, TunnelMate automatically activates UTF-8 code page 65001 and enables Windows Virtual Terminal Processing (ENABLE_VIRTUAL_TERMINAL_PROCESSING).
   • Unicode borders, status badges (🟢 RUNNING, 🔄 RESTARTING), and emojis display cleanly without text overlap or font corruption.
3. Dynamic IPC Port Allocation on Windows:
   • Windows utilizes loopback TCP for local inter-process communication. If the default port (53821) is busy, the daemon automatically claims an available port and writes synchronization data to daemon.info, preventing socket collision errors.
4. One-Click Daemon Initialization:
   • If tunnelmate is launched when the background daemon is offline, users can press Enter on 🚀 Start Background Daemon directly in the TUI to spawn the daemon inline.

---

⚡ 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. 100% Interactive Button-Driven Telegram Bot Experience

TunnelMate features a modern, attractive inline button UI in Telegram. You never need to memorize or type complex commands like /login pass, /create name port 8080, or /port name 3000. Everything is guided step-by-step through interactive buttons and smart conversational prompts:

• 🔒 Interactive Admin Login Wizard:
  • Click [🔒 Login as Admin] from the main menu.
  • The bot prompts you to enter your server administrator password.
  • Zero Privacy Leak: Your password message is automatically deleted from Telegram chat history the instant it arrives, unlocking the full administrative dashboard.
• ➕ Interactive Create Tunnel Wizard (4-Step Guided Flow):
  • Click [➕ Create Tunnel] from the main menu or tunnels list.
  • Step 1: Enter tunnel name (e.g., api-dev).
  • Step 2: Select a target port using quick preset buttons ([8080], [3000], [8000], [5000], [80], [22]) or enter a custom port.
  • Step 3: Select protocol with one click ([🌐 HTTP], [🔒 HTTPS], [⚡ TCP / SSH]).
  • Step 4: Choose password security ([🔒 Yes, Enable Password] or [🔓 No, Public Access]). If enabled, prompts for the password (auto-deleted) and launches the tunnel immediately!
• ✏️ Dynamic In-Place Port Changer:
  • Click [✏️ Change Port] on any tunnel detail card.
  • Choose from popular preset buttons (8080, 3000, 8000, 5000, 80, 22) or type any custom port.
  • Tunnel updates immediately with zero downtime and preserves your live public URL!
• 🗑️ Interactive Delete Confirmation:
  • Click [🗑️ Delete Tunnel] on any tunnel.
  • Features confirmation dialog ([🗑️ Yes, Delete] / [❌ Cancel]) to prevent accidental deletions.
• 🔒 Interactive Password Protection Manager:
  • Click [🔒 Password Auth] or [🔓 Add Password] on any tunnel card.
  • Click [🔑 Set / Change Password] to enter a new password (message auto-deleted for privacy; preserves live URL).
  • Click [🔓 Disable Password Protection] for 1-click removal of the password gate (preserves live URL).
• 📋 Full Process Controls & Health Checks:
  • [▶️ Start], [⏹️ Stop], [🔄 Restart], [🔗 Latest Link], [🩺 Health Check], [🔔 Notifications].

(Optional power-user slash commands remain supported: /start, /login, /logout, /create, /auth, /port, /cancel)

---

🔁 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

Command	Arguments	Description
tunnelmate menu	—	Open interactive arrow-key TUI dashboard
tunnelmate list	—	Display color-coded table of all configured tunnels
tunnelmate create	<name> --port <port_or_url> [--protocol http|tcp|tls] [--auth] [--password <pwd>] [--rewrite-links]	Create a new Quick Tunnel
tunnelmate start	<name>	Launch tunnel subprocess and acquire live URL
tunnelmate stop	<name>	Gracefully stop running tunnel subprocess
tunnelmate restart	<name>	Restart tunnel and assign fresh trycloudflare.com URL
tunnelmate port / target	<name> <port_or_url>	Dynamically remap target port or URL on the fly (preserves public URL)
tunnelmate auth	<name> [--enable|--disable] [--password <pwd>]	Configure password protection (preserves public URL)
tunnelmate replace-links	<name> [--enable|--disable]	Configure origin link rewriting to replace origin URLs in responses
tunnelmate top	[-i <sec>] [--once]	Live interactive resource monitor for TunnelMate & Cloudflare
tunnelmate-top	[-i <sec>] [--once]	Standalone binary for live interactive resource monitoring
tunnelmate url	<name>	Output raw URL for shell scripts and piping
tunnelmate health	<name>	Test local service response and Cloudflare edge status
tunnelmate logs	<name> [--lines 50]	Stream or view recent cloudflared process logs
tunnelmate history	<name>	Inspect full lifecycle audit trail
tunnelmate delete	<name> [--yes]	Delete tunnel configuration and purge history
tunnelmate install-cloudflared	—	Auto-download official Cloudflare binary
tunnelmate ssh	[target]	Connect to Cloudflare SSH tunnel

Daemon Commands (tunnelmate daemon)

Command	Description
tunnelmate daemon start	Launch background daemon service process
tunnelmate daemon stop	Stop background daemon service
tunnelmate daemon status	Check daemon PID, uptime, and IPC connectivity
tunnelmate daemon run	Run daemon in foreground (for systemd or debugging)

Telegram Bot Commands (tunnelmate bot)

Command	Arguments	Description
tunnelmate bot start	—	Launch Telegram Bot process in background
tunnelmate bot stop	—	Stop background Telegram Bot process
tunnelmate bot status	—	Inspect bot process status, token, and admin whitelist
tunnelmate bot set-token	<token>	Configure Telegram bot API token
tunnelmate bot set-password	<password>	Set salted SHA-256 admin password
tunnelmate bot chats	—	List all historical chat IDs and subscriber names
tunnelmate bot whitelist	<chat_id>	Add Telegram Chat ID to administrator whitelist
tunnelmate bot unwhitelist	<chat_id>	Remove Telegram Chat ID from whitelist
tunnelmate bot sessions	—	Display active server-side session status table
tunnelmate bot revoke-sessions	—	Invalidate all active sessions (force logout)
tunnelmate bot clear-tunnels	—	Purge published SSH tunnel metadata from Telegram

---

🐍 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.