TunnelRick

Portal your localhost to the multiverse!

TunnelRick is a reverse proxy tunneling service (similar to ngrok) that allows you to expose your local development servers to the internet. Built with Node.js, TypeScript, Express, and WebSockets.

---

Quick Start

cd client
chmod +x install.sh
./install.sh

After installation, use the tunnelrick command:

tunnelrick -s wss://tunnelrick.coffee -k '7b0dd27a-4456-43cf-aee1-a93c3026a976' -p 3000

Parameters:

• -s - Server URL (the WebSocket address of the TunnelRick server)
• -k - API Key (your authentication key for the server)
• -p - Port (the local port to expose, change this to your app's port)

---

Table of Contents

• Architecture Overview
• Prerequisites
• Server Setup
• Client Setup
• Usage
• How It Works

---

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                              INTERNET                                       │
│                                                                             │
│    User visits: https://tunnel.example.com/t/{tunnelId}/your-api-path      │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                                  │ HTTP Request
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         TUNNELRICK SERVER                                   │
│                    (Your Cloud/VPS Instance)                                │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │                                                                       │  │
│  │   ┌─────────────────┐      ┌─────────────────┐      ┌─────────────┐  │  │
│  │   │  Express HTTP   │      │   WebSocket     │      │   MySQL     │  │  │
│  │   │    Server       │◄────►│    Server       │◄────►│  Database   │  │  │
│  │   │                 │      │                 │      │             │  │  │
│  │   │  Routes:        │      │  - Auth         │      │ - api_keys  │  │  │
│  │   │  /t/:tunnelId/* │      │  - Messages     │      │ - tunnels   │  │  │
│  │   │  /health        │      │  - Connections  │      │             │  │  │
│  │   └─────────────────┘      └────────┬────────┘      └─────────────┘  │  │
│  │                                     │                                 │  │
│  └─────────────────────────────────────┼─────────────────────────────────┘  │
└────────────────────────────────────────┼────────────────────────────────────┘
                                         │
                                         │ WebSocket Connection
                                         │ (Persistent, Bidirectional)
                                         │
┌────────────────────────────────────────┼────────────────────────────────────┐
│                          YOUR LOCAL MACHINE                                 │
│  ┌─────────────────────────────────────┼─────────────────────────────────┐  │
│  │                                     ▼                                 │  │
│  │   ┌─────────────────────────────────────────────────────────────┐    │  │
│  │   │                    TUNNELRICK CLIENT                        │    │  │
│  │   │                       (CLI Tool)                            │    │  │
│  │   │                                                             │    │  │
│  │   │   - Maintains WebSocket connection to server                │    │  │
│  │   │   - Receives incoming HTTP requests                         │    │  │
│  │   │   - Forwards requests to local server                       │    │  │
│  │   │   - Sends responses back through tunnel                     │    │  │
│  │   │                                                             │    │  │
│  │   └──────────────────────────┬──────────────────────────────────┘    │  │
│  │                              │                                        │  │
│  │                              │ HTTP Forward                           │  │
│  │                              ▼                                        │  │
│  │   ┌─────────────────────────────────────────────────────────────┐    │  │
│  │   │              YOUR LOCAL DEV SERVER                          │    │  │
│  │   │                                                             │    │  │
│  │   │              http://localhost:3000                          │    │  │
│  │   │              (React, Express, Django, etc.)                 │    │  │
│  │   │                                                             │    │  │
│  │   └─────────────────────────────────────────────────────────────┘    │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

---

Prerequisites

Before setting up TunnelRick, ensure you have the following installed:

• Node.js (v16 or higher)
• npm or yarn
• MySQL (v8.0 or higher) - for the server
• A VPS/Cloud server with a public IP and domain (for production)
• Linux or macOS - Windows users need WSL or Git Bash

---

Server Setup

The server is the central hub that receives requests from the internet and routes them to connected clients.

1. Navigate to the server directory

cd server

2. Install dependencies

npm install

3. Set up the MySQL database

Create a MySQL database and user:

CREATE DATABASE tunnelrick;
CREATE USER 'tunnel_user'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON tunnelrick.* TO 'tunnel_user'@'localhost';
FLUSH PRIVILEGES;

The required tables will be created automatically when the server starts.

4. Configure environment variables

Copy the example environment file and edit it:

cp .env.example .env

Edit .env with your settings:

PORT=3000
DOMAIN=tunnel.yourdomain.com
NODE_ENV=production
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=tunnel_user
MYSQL_PASSWORD=your_secure_password
MYSQL_DATABASE=tunnelrick

5. Build and run

Development:

npm run dev

Production:

npm run build
npm start

With PM2 (recommended for production):

npm install -g pm2
pm2 start ecosystem.config.js

6. Initialize the database

Run the migration to create the required tables:

mysql -u tunnel_user -p tunnelrick < migrations/001_init.sql

7. Generate API keys

Insert API keys into the database for client authentication:

USE tunnelrick;
INSERT INTO api_keys (key_value, name) VALUES ('your-secret-api-key', 'My API Key');

---

Client Setup

The client runs on your local machine and creates a tunnel to expose your local server.

Option 1: Portable Installation (Recommended)

The client comes pre-built and ready to use. Just extract and install:

# Extract the client package
unzip tunnelrick-client.zip
cd client

# Run the installer
./install.sh

The installer will:

• Copy files to ~/.tunnelrick
• Set up the tunnelrick command
• Add to your PATH (optional)

After installation, restart your terminal or run:

source ~/.bashrc  # or ~/.zshrc

Option 2: Build from Source

If you prefer to build from source:

cd client
npm install
npm run build
./install.sh

---

Usage

Running the Client

Basic usage:

tunnelrick -s wss://tunnel.yourdomain.com -k your-api-key -p 3000

All options:

tunnelrick [options]

Options:
  -s, --server <url>      Tunnel server WebSocket URL (required)
  -k, --key <apiKey>      API key for authentication (required)
  -p, --port <port>       Local port to forward traffic to (required)
  -t, --tunnel-id <id>    Custom tunnel ID (optional, auto-generated if not provided)
  -H, --host <host>       Local host to forward to (default: "localhost")
  -h, --help              Display help

Examples:

# Expose local React app running on port 3000
tunnelrick -s wss://tunnel.example.com -k my-api-key -p 3000

# Use a custom tunnel ID
tunnelrick -s wss://tunnel.example.com -k my-api-key -p 8080 -t myapp

# Forward to a different local host
tunnelrick -s wss://tunnel.example.com -k my-api-key -p 3000 -H 192.168.1.100

Accessing Your Tunnel

Once connected, you'll receive a public URL like:

https://tunnel.yourdomain.com/t/abc12345/

Any requests to this URL will be forwarded to your local server.

---

How It Works

Connection Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                           CONNECTION PHASE                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   1. Client starts and connects to server via WebSocket                     │
│                                                                             │
│   2. Client sends AuthMessage:                                              │
│      ┌──────────────────────────────────────────┐                          │
│      │ {                                        │                          │
│      │   "type": "auth",                        │                          │
│      │   "apiKey": "your-api-key",              │                          │
│      │   "tunnelId": "custom-id" (optional)     │                          │
│      │ }                                        │                          │
│      └──────────────────────────────────────────┘                          │
│                                                                             │
│   3. Server validates API key against MySQL database                        │
│                                                                             │
│   4. Server responds with AuthSuccessMessage:                               │
│      ┌──────────────────────────────────────────┐                          │
│      │ {                                        │                          │
│      │   "type": "auth_success",                │                          │
│      │   "tunnelId": "abc12345",                │                          │
│      │   "url": "https://domain.com/t/abc12345" │                          │
│      │ }                                        │                          │
│      └──────────────────────────────────────────┘                          │
│                                                                             │
│   5. Tunnel is now active and ready for requests!                           │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

Features

• Secure Authentication - API key-based authentication stored in MySQL
• Custom Tunnel IDs - Use your own tunnel ID or let the system generate one
• All HTTP Methods - Supports GET, POST, PUT, DELETE, PATCH, etc.
• HTML Asset Rewriting - Automatically rewrites relative URLs in HTML responses
• Request Timeout - 60-second timeout for pending requests
• Colorful CLI Output - Rick and Morty themed terminal output

---

License

MIT