Tunnely - Free Multiplayer Hosting Platform

A comprehensive, Essentials-like system for hosting Minecraft servers without port forwarding

Version: 1.4.6 | Minecraft: 1.20.1 | Loaders: Fabric, Forge | Requires: Architectury API

⚠️ CurseForge Update Status

CurseForge is currently blocking updates for this mod due to moderation concerns.

The mod has been rejected multiple times with claims about "using local browsers and running executables which is not allowed." However, these claims are based on misunderstandings of standard industry practices:

• OAuth Authentication: We use the standard OAuth 2.0 localhost callback flow (RFC 8252) - the same method used by VS Code, GitHub Desktop, Discord, and thousands of other applications
• Security Scanning: We scan uploaded world files to BLOCK executables (so viruses cannot be shared on our world distribution system), we don't run them
• Sequential Port Fallbacks: Multiple ports are tried one-at-a-time as fallbacks (like trying different doors), not run simultaneously

If you want to see updates on CurseForge, please contact their support team at https://support.curseforge.com or message them on Discord at https://discord.gg/DkWwUgw7cS and let them know you'd like Tunnely approved.

In the meantime, you can find the latest updates on Modrinth where the mod continues to receive regular updates.

We've provided detailed technical documentation to CurseForge explaining these standard practices, but the appeals process has not resolved the issue. The mod uses the same security patterns as other approved mods and major software applications.

Technical Note: CurseForge's concerns are about OAuth authentication (industry-standard login) and security scanning (blocking malware). These are completely separate from the game networking features described below.

What's New in Version 1.4.6

Multi-Port Forwarding System

This is a standard game networking feature, unrelated to CurseForge's moderation concerns.

Tunnely now supports forwarding additional ports beyond Minecraft, enabling voice chat mods and other services to work seamlessly through the tunnel. This system includes:

• Automatic Mod Detection - Detects installed mods like Simple Voice Chat and Plasmo Voice
• UDP Protocol Support - Full UDP forwarding for voice chat and other real-time services
• Per-Port Rate Limiting - Optimized bandwidth allocation (100 packets/sec for voice, 50 for others)
• Packet Size Validation - Prevents fragmentation and bandwidth abuse (2KB limit)
• Auto-Retry Logic - Automatic recovery from transient socket failures with exponential backoff
• Port Conflict Detection - Validates port availability before starting to prevent startup failures
• Graceful Failure Handling - Main Minecraft connection continues even if additional ports fail
• Status Indicators - Visual UI feedback showing which services are active and any port conflicts

Supported services include:

• Simple Voice Chat (port 24454/UDP) - Auto-enabled by default
• Plasmo Voice (configurable port, auto-detected from config)
• Any mod requiring additional TCP/UDP port forwarding

Increased Player Capacity

Integrated servers (singleplayer worlds opened to LAN) now support up to 20 players, up from the vanilla limit of 8. Perfect for hosting larger community events and friend group sessions without needing a dedicated server.

Enhanced Error Messages

Port forwarding now provides detailed, actionable error messages with solutions:

• Clear identification of which port is in use
• Specific guidance for administrator permissions
• Firewall configuration suggestions
• Automatic conflict resolution recommendations

Support the Project

Love Tunnely? Here's how you can help keep it running:

Tunnely is completely free to use, but running relay servers isn't free for us! Each relay server costs $20-30/month depending on the region to keep online and accessible for everyone. Your support helps us maintain and expand the infrastructure that makes free multiplayer hosting possible.

Ways to Support:

Financial Support

Support us on Ko-fi - Every contribution helps cover relay server costs and keeps Tunnely free for everyone. Whether it's a one-time coffee or monthly support, it makes a real difference!

Non-Financial Support

Can't contribute financially? No problem! You can still help:

• Download and use the mod - More users means a stronger community
• Suggest modpacks - Recommend that your favorite modpack creators include Tunnely
• Spread the word - Tell friends and communities about Tunnely
• Report bugs - Help us improve by reporting issues on GitHub
• Contact CurseForge - Let them know you want Tunnely updates approved

Every bit of support, whether financial or not, helps Tunnely grow and stay free for everyone. Thank you! ❤️

What is Tunnely?

Tunnely is a free, open-source alternative to paid hosting services and server management solutions. Similar to how Essentials provides essential server features at no cost, Tunnely provides essential multiplayer connectivity features that are typically locked behind paywalls or require complex technical setup.

The goal of Tunnely is simple: Make multiplayer hosting accessible to everyone. No subscription fees, no port forwarding knowledge required, no router configuration needed.

Intelligent Mesh Relay Network

Tunnely operates a global mesh relay network that ensures low-latency connections worldwide. Multi-region relay servers communicate directly with each other - if you're hosting in NA and your friend connects from EU, traffic is automatically routed through the optimal relay-to-relay path for the best possible latency. The system automatically selects the fastest relay for your location and falls back to alternatives if needed.

Why Tunnely?

Traditional multiplayer hosting requires one of the following:

• Port forwarding (complex, requires router access)
• Static IP addresses (expensive, not always available)
• Paid tunneling services like Ngrok ($8-20/month)
• Paid server hosting ($10-30/month per server)
• Technical networking expertise

Tunnely provides all of this for free:

• Zero-configuration networking (no port forwarding)
• Self-hostable infrastructure (no recurring costs)
• Complete social features (friends, invites, server browser)
• Professional security (JWT authentication, encryption)
• Automatic compatibility detection
• Vanilla client compatibility (friends don't need the mod)

Think of it as the "Essentials" of multiplayer connectivity - powerful features that should be accessible to everyone.

Key Features

No Port Forwarding Required

Host Minecraft servers from behind NAT, firewalls, and restrictive networks. The relay-based tunneling system creates a public endpoint without any router configuration.

Three-Tier Visibility System

Control exactly who can join your server:

• Public - Listed in server browser, anyone can discover and join
• Friends Only - Only your accepted friends can see and join
• Invite Only (Default) - Maximum privacy, requires explicit invitation

Complete Social System

• Add and manage friends by email
• Send server invites to specific players
• Browse friends' active servers
• Public server browser with filtering
• Real-time online status tracking

Automatic Compatibility Detection

Prevents version mismatch headaches by automatically detecting:

• Minecraft version (e.g., 1.20.1)
• Mod loader (Fabric, Forge, NeoForge, Quilt, Vanilla)
• Modpack ID and version (CurseForge, Modrinth, custom)

Server browser shows compatibility at a glance with visual indicators.

Secure & Private

• JWT-based authentication via Supabase
• AES-256-GCM token encryption with machine-bound keys
• TLS/WSS encrypted relay connections
• Row-Level Security on database
• Minimal data collection, no gameplay logging
• Open source and auditable

Comprehensive UI

Press U key to access:

• Host Game screen (start/stop, visibility controls)
• Join Friends browser
• Manage Friends interface
• Server Invites panel
• Public Lobbies with filtering
• Settings and configuration

Vanilla Client Compatible

Friends joining your server do not need Tunnely installed. The mod is only required on the host side.

Multi-Regional Relay Network with Intelligent Mesh Routing

Tunnely operates a global relay network with intelligent mesh routing to ensure low-latency connections worldwide:

• NA 1 (Atlanta, USA) - Serving North and South America
• EU 1 (Frankfurt, Germany) - Serving Europe, Middle East, and Africa
• APAC 1 (Singapore) - Serving Asia-Pacific region

Automatic Relay Selection: When you host a server, Tunnely automatically:

• Pings all available relays to measure latency
• Connects to the fastest relay for your location
• Falls back to next-best relay if primary is unavailable
• Displays server region in the public lobby browser

Mesh Network Intelligence: If you're in one region but your friend is in another, Tunnely's mesh network automatically routes traffic through the optimal path. For example, a host in NA can connect to friends in EU through relay-to-relay mesh connections, ensuring the best possible latency for all players.

Players can filter public servers by region to find the best connection. No configuration needed - it just works!

Intelligent Bandwidth Compression

Version 1.4.5+ includes automatic GZIP compression to reduce bandwidth usage by 50-80% without any configuration:

How it works:

• All Minecraft packets are automatically compressed before transmission
• Compression happens at the application layer (after Minecraft generates packets)
• Fully compatible with Minecraft's protocol - no "badly compressed packet" errors
• Relay servers maintain compression efficiency across mesh hops

Benefits:

• 60-80% reduction on chunk data transfers
• 40-60% reduction on gameplay packets
• Lower bandwidth costs if hosting on metered connections
• Smoother gameplay on slower networks
• Scales across multi-hop mesh routes

Performance:

• Minimal CPU overhead (GZIP is highly optimized)
• End-to-end compression maintained across relay mesh
• No configuration required - enabled automatically

This means you can host servers on slower connections and players on limited data plans can enjoy longer play sessions!

Installation

Quick Setup (5 Minutes)

1. Install Dependencies

   • Download and install Architectury API (required dependency)
   • Place in your mods/ folder

2. Install Tunnely

   • Download the appropriate version for your mod loader (Fabric or Forge)
   • Place tunnelyrefab-[fabric/forge]-1.0-SNAPSHOT.jar in your mods/ folder

3. Launch Minecraft

   • Configuration file automatically generated at config/tunnelyrefab.json
   • Default settings connect to public relay server

4. Create Account

   • Press U key to open Tunnely menu
   • Click Login/Register
   • Enter email and password
   • Accept Terms of Service

5. Start Hosting

   • Open any world
   • Press U then Host Game
   • Choose visibility mode
   • Click Start Hosting

Using Default Infrastructure

Tunnely comes pre-configured to use public relay infrastructure, so you can start hosting immediately after creating an account. No additional configuration required.

For complete control and privacy, you can self-host your own relay server and database. See the Self-Hosting section below.

Self-Hosting Guide

Tunnely is designed to be self-hostable, giving you complete control over your infrastructure. This makes it truly free - no recurring costs, no data sharing, no dependency on third-party services.

Why Self-Host?

• Complete Privacy - Your data never leaves your infrastructure
• Zero Costs - Use free-tier cloud services or cheap VPS ($5/month)
• Full Control - Customize, modify, audit all code
• No Vendor Lock-in - Independent of external services
• Community - Run relay for your community/organization

Prerequisites

• Linux VPS (Ubuntu 20.04+ recommended)
• Node.js 18 or higher
• PostgreSQL 14+ (or Supabase account)
• Domain name (optional, recommended for SSL)

Quick Setup Guide

1. Database Setup

Option A - Supabase Cloud (Easiest):

• Create free account at supabase.com
• Create new project
• Run migration files in SQL Editor (in order):
  • schema.sql
  • add-friends-rls.sql
  • add-invites-rls.sql
  • add-visibility-field.sql
  • add-compatibility-fields.sql
  • add-tos-acceptance-tracking.sql
  • fix-tos-rls.sql

Option B - Self-Hosted PostgreSQL:

• Install PostgreSQL 14+
• Create database and user
• Run all migration files from supabase/ directory

2. Relay Server Setup

# Clone repository git clone https://github.com/yourname/tunnelyrefab.git cd tunnelyrefab/relay-server # Install dependencies npm install # Configure environment cp .env.example .env nano .env

Edit .env:

PORT=8080 SUPABASE_URL=https://your-project.supabase.co SUPABASE_SERVICE_KEY=your-service-role-key NODE_ENV=production

3. Start Relay Server

# Install PM2 process manager sudo npm install -g pm2 # Start relay server pm2 start server.js --name tunnely-relay pm2 save pm2 startup # Enable auto-start

4. SSL Setup (Recommended)

# Install Nginx and Certbot sudo apt install nginx certbot python3-certbot-nginx # Get SSL certificate sudo certbot --nginx -d relay.yourdomain.com

Configure Nginx as reverse proxy for WebSocket connections (see full guide in repository).

5. Configure Clients

Users edit config/tunnelyrefab.json:

{ "relayServerUrl": "wss://relay.yourdomain.com", "supabaseUrl": "https://your-project.supabase.co", "supabaseAnonKey": "your-anon-key" }

Health Check:

curl https://relay.yourdomain.com/health

Cost Estimation

• Minimal Setup: $5/month VPS + domain ($10-15/year)
• At Scale (100+ users): $20-40/month

Compare to paid alternatives:

• Ngrok: $8-20/month per host
• Traditional hosting: $10-30/month per server

See full self-hosting documentation in the repository for detailed setup instructions.

Troubleshooting

Authentication Issues

"Not Authenticated" Error

Solutions:

• Login via UI: Press U → Login/Register
• Or use command: /tunnel login <email> <password>
• If token expired, re-login with your credentials

"Token Validation Failed"

Solutions:

• This is expected when token expires - simply re-login
• Check Supabase project status if persistent
• Verify config file has correct supabaseUrl and supabaseAnonKey

"Failed to Decrypt Token"

Causes:

• Hardware changed (new network adapter)
• Config copied from another computer
• OS username changed

Solution:

• Re-login to generate new token (this is security by design)

Connection Issues

"Failed to Connect to Relay Server"

Solutions:

• Check internet connection
• Verify relay server is running: curl https://relay-url/health
• Ensure relayServerUrl in config uses wss:// not ws://
• Check firewall isn't blocking outgoing connections
• Try with VPN if behind corporate firewall

"Connection Timeout"

Solutions:

• Check relay server accessibility from your network
• Verify relay server isn't overloaded (check health endpoint)
• Check for DNS issues: nslookup relay.yourdomain.com

Server Issues

"Failed to Register Server"

Solutions:

• Verify you're authenticated: /tunnel status
• Check Supabase credentials in config
• Check server console for database errors
• Verify Row-Level Security policies in database

"Unauthorized to Join Session"

Solutions:

• Check visibility mode (must be Public or Friends Only for easy access)
• If Invite Only mode, send explicit invite via UI
• Verify friend relationship is accepted: Press U → Manage Friends
• Ensure friend is using correct, current endpoint

Compatibility Issues

"Version Mismatch" or "Incompatible Server"

Solutions:

• Minecraft Version: Must match exactly (both must be 1.20.1)
• Mod Loader: Must match (Fabric vs Forge vs Vanilla)
• Modpack: If both using modpacks, ID and version must match
• Check server's compatibility badge for specific mismatch

Mod Loading Issues

Commands Don't Work / UI Doesn't Open

Solutions:

• Verify Architectury API is installed
• Check Minecraft version is 1.20.1
• Check mod loader matches (Fabric vs Forge)
• Look for errors in logs/latest.log
• Try removing other mods to test for conflicts

Usage Guide

Hosting a Server

Method 1: In-Game UI (Recommended)

1. Open your Minecraft world
2. Press U key to open Tunnely menu
3. Click Host Game
4. Optional: Set custom server name (3-32 characters)
5. Choose visibility mode:
   • Invite Only - Most private (default)
   • Friends Only - Visible only to friends
   • Public - Listed in public browser
6. Click Start Hosting
7. Your endpoint appears on screen
8. Click Copy Endpoint to copy address or Invite Friends to send invites

Method 2: Commands

/tunnel login <email> <password> /tunnel start # Start hosting (Invite Only by default) /tunnel endpoint # Display your public address /tunnel stop # Stop hosting

Joining Servers

Option 1: From Friends List

• Press U → Join Friends
• Browse active servers from your friends
• Click Join to copy endpoint
• Add server in Minecraft multiplayer menu

Option 2: From Invites

• Press U → Invites
• View pending invitations
• Click Accept to copy endpoint
• Add server in Minecraft and connect

Option 3: Public Browser

• Press U → Public Lobbies
• Enable "Show only compatible" filter (optional)
• Browse available public servers
• Click Join to copy endpoint

Option 4: Manual Connection

• Friend shares endpoint (format: IP:PORT/session-id)
• Open Minecraft → Multiplayer → Add Server
• Paste endpoint as server address

Note: Joining players do not need Tunnely installed.

Security & Privacy

Authentication System

JWT-Based Security

• Industry-standard JSON Web Tokens for authentication
• Powered by Supabase Auth (enterprise-grade authentication service)
• Passwords never stored by Tunnely (handled securely by Supabase)
• Cryptographically signed tokens prevent forgery

Token Encryption at Rest

• AES-256-GCM authenticated encryption for stored tokens
• Machine-bound keys derived from hardware identifiers (MAC address, username, OS)
• Config files become useless if copied to another computer
• Automatic re-authentication required if hardware changes

Auto-Logout Detection

• Token validation on screen initialization
• Automatic redirect to login if token expired
• Prevents "false logged in" state with clear error messages

Data Collection & Privacy

What Data is Collected:

Data Type Purpose Duration Visibility Email Address Authentication Permanent Private User UUID Identification Permanent Private Server Name Display in browser While active Public if listed Endpoint Connection address While active Public if listed Compatibility Info Version matching While active Public in browser Friend Relationships Social features Until removed Private

What is NOT Collected:

• Chat messages or conversations
• Player movements or actions
• World data or builds
• Gameplay statistics
• Minecraft protocol data

Data Retention:

• Server records deleted when hosting stops
• Account data persists until account deletion
• No logging of gameplay or packets

Relay Server Security

How It Works:

[Host PC] <--WebSocket (TLS/WSS)--> [Relay Server] <--TCP--> [Client PC] | [Database]

Security Measures:

• TLS/WSS encryption for all relay connections
• JWT authentication required for every connection
• Database-backed authorization checks
• Rate limiting (200 packets/second per connection)
• Maximum 20 clients per server
• Heartbeat monitoring with automatic disconnect
• No packet logging - relay only forwards encrypted data

Database Security

• Row-Level Security (RLS) enforces access control
• Users can only view/modify their own data
• Friends Only servers visible only to accepted friends
• Invite Only servers hidden from all queries

Content Moderation

• Server names: 3-32 characters, profanity filtered
• Client-side filtering for inappropriate content
• Host responsible for server content
• Report system via GitHub Issues

Dedicated Server Support

Tunnely fully supports dedicated servers with all the same features as integrated servers.

Setup Process

1. Install Server Software

   • Set up Fabric or Forge server (Minecraft 1.20.1)
   • Install Architectury API in mods/ folder
   • Install Tunnely in mods/ folder

2. Configure Tunnely

   Create or edit config/tunnelyrefab.json:

{ "relayServerUrl": "wss://relay.example.com", "supabaseUrl": "https://your-project.supabase.co", "supabaseAnonKey": "your-anon-key", "enableTunneling": true, "autoStartTunnel": true, "defaultVisibility": "invite_only" }

1. Authenticate

   In server console:

/tunnel register <email> <password>

Or if already registered:

/tunnel login <email> <password>

1. Start Server

   Tunnel automatically starts when server starts (if autoStartTunnel: true)

   Check status:

/tunnel status /tunnel endpoint

1. Share Endpoint

   Copy the endpoint from console output and share with players

Available Commands

/tunnel status # View tunnel status and connection info /tunnel endpoint # Display public endpoint address /tunnel start # Manually start tunnel /tunnel stop # Stop tunnel /tunnel login <email> <pw> # Authenticate /tunnel register <email> <pw> # Create account /tunnel help # Show command list

Notes

• No port forwarding required
• Works behind firewalls
• Auto-reconnects if relay connection drops
• No GUI available (command-line only)
• Server name defaults to "Minecraft Server"
• Visibility controlled via config file
• Compatible with server management tools (screen, tmux, systemd)

Limitations

Performance:

• Added latency: 20-50ms (mesh routing optimizes multi-region connections)
• Max 20 players per integrated server (increased from vanilla 8 player limit)
• Optimal for 2-15 players
• Works well for community events up to 20 players
• Not ideal for large servers (25+)
• Bandwidth: Significantly reduced with automatic GZIP compression (50-80% savings)

Compatibility:

• Minecraft 1.20.1 only
• Other versions not supported
• May conflict with e4mc or similar mods

Security Considerations:

• Trust relay server operator
• DDoS risk if endpoint publicly shared
• Mitigated by rate limiting & auth

Architecture

System Overview

┌───────────────┐ GZIP Compress ┌─────────────┐ Mesh Routing ┌─────────────┐ │ Minecraft Host│────────────────────→│ Relay NA │◄───────────────────→│ Relay EU │ └───────────────┘ WSS Encrypted └─────────────┘ Binary Frames └─────────────┘ ↓ ↓ ┌─────────────┐ ┌─────────────┐ │ Supabase DB │ │ Client │ └─────────────┘ └─────────────┘ GZIP Decompress

How It Works

1. Host opens to LAN + starts tunnel
2. Mod authenticates via Supabase
3. Connects to fastest relay via encrypted WebSocket
4. GZIP compresses all packets before sending
5. Relay assigns public endpoint
6. Friend queries database for servers
7. Friend connects to relay (or mesh-routed if different region)
8. Relay forwards compressed packets bidirectionally
9. Client decompresses packets before delivery
10. Minecraft sees direct connection with optimal routing!

Security Layers

• TLS/WSS encryption
• JWT authentication
• Row-Level Security (database)
• Visibility authorization
• Rate limiting
• Machine-bound token encryption

Additional Documentation

See GitHub repository for:

• README.md - Full documentation
• QUICKSTART.md - Quick start guide
• DATA-SAFETY.md - Security details
• ENCRYPTION-README.md - Token encryption
• VISIBILITY-SYSTEM.md - Visibility modes
• COMPATIBILITY-SYSTEM.md - Version detection
• UI-GUIDE.md - Complete UI walkthrough
• AUTH-AND-TOS.md - Authentication system
• COMPRESSION-SYSTEM.md - Bandwidth compression system
• MESH-COMPRESSION.md - Mesh network optimization
• MULTI-RELAY-SETUP.md - Multi-relay deployment guide
• MULTI-PORT-IMPROVEMENTS-IMPLEMENTED.md - NEW - Multi-port forwarding implementation details
• PORT-FORWARDING-TIMEOUT-FIX.md - NEW - Critical bug fix documentation

Terms of Service

By using Tunnely, you agree to:

1. Account responsibility & security
2. No harassment, illegal content, or abuse
3. Hosts responsible for server content
4. No uptime guarantees (best effort)
5. Data privacy (see DATA-SAFETY.md)
6. Content moderation applies
7. Must be 13+ or have parental consent

Full terms shown during registration.

Credits

Built with:

• Architectury API - Cross-platform development
• Supabase - Auth & database
• Node.js + ws - Relay server

Inspired by: e4mc, Playit.gg

License: MIT - See LICENSE.txt

Support

• Bug Reports: GitHub Issues
• Feature Requests: GitHub Discussions
• Contact: [email protected]
• Source: Soon
• Discord: https://discord.gg/s87b4APq

Made with ❤️ for the Minecraft community