# TunnelMC \ud83c\udf10<\/p>\n
> Expose any local port to the internet via ngrok or cloudflared \u2014 no port allocations needed. Includes a full browser-based management dashboard.<\/p>\n
TunnelMC is a Bukkit\/Spigot\/Paper plugin that automatically downloads and manages ngrok and\/or cloudflared, creates tunnels for any local port, and broadcasts the public URL to console and online OPs the moment the tunnel is ready.<\/p>\n
—<\/p>\n
## \ud83c\udd95 What’s New in 1.3.0<\/p>\n
### Java 25 & Build Modernization
\n– **Upgraded to Java 25** \u2014 compiled with Java 25 bytecode for the latest JVM performance and language features.
\n– **Gradle 9.5.1** \u2014 build system upgraded from Gradle 8.x to 9.5.1 for native Java 25 support.
\n– **Virtual thread executor** \u2014 the dashboard HTTP server now uses `newVirtualThreadPerTaskExecutor()` for non-blocking I\/O scaling on Java 25.
\n– **`plugin.yml` api-version** updated from `1.13` to `1.21` to match the target platform and suppress Paper deprecation warnings.<\/p>\n
### Security Hardening
\n– **CSRF protection** \u2014 all mutating API endpoints now require an `X-TM-Request` header.
\n– **Brute-force login protection** \u2014 lockout after 5 failed attempts with 500ms delay per failure.
\n– **Timing-safe password comparison** \u2014 login now uses `MessageDigest.isEqual()` to prevent timing attacks.
\n– **CSP headers** \u2014 Content-Security-Policy added to all dashboard responses to mitigate XSS risks.
\n– **Session sweep** \u2014 expired sessions and stale lockout entries are automatically cleaned up hourly.<\/p>\n
### Stability
\n– **`volatile` singleton** \u2014 static plugin instance is now `volatile` and nulled on disable to prevent classloader leaks during reloads.
\n– **Config bounds checking** \u2014 all numeric config getters now clamp to valid ranges via `Math.max`.
\n– **Default password warning** \u2014 a prominent console warning at startup if the dashboard password is still `”changeme”`.<\/p>\n
### Compatibility
\n– **Minecraft 1.21.x \u2013 26.1.x** \u2014 compiled against Paper 1.21.1 API, which is forward-compatible with all Paper versions through 26.1.x.<\/p>\n
Existing configs remain fully compatible \u2014 no config changes required.<\/p>\n
—<\/p>\n
## \u2728 Features<\/p>\n
**\ud83c\udf10 Two Tunnel Providers** \u2014 ngrok and cloudflared, configurable per tunnel. Mix them freely.<\/p>\n
**\ud83d\udd11 Multiple ngrok Accounts** \u2014 Each ngrok tunnel has its own authtoken (required for v3). Run different accounts simultaneously.<\/p>\n
**\ud83d\ude80 Zero-Setup Quick Tunnels** \u2014 Cloudflared quick tunnels work out of the box with no account.<\/p>\n
**\ud83d\udccc Custom Domains** \u2014 Cloudflared named tunnels give you persistent custom hostnames via Cloudflare Zero Trust.<\/p>\n
**\ud83d\udda5\ufe0f Web Dashboard** \u2014 Full management UI. Create\/edit\/delete tunnels live, download binaries, change settings \u2014 all from a browser.<\/p>\n
**\u26a1 Auto-Download** \u2014 Detects OS and CPU arch, downloads the right binary on first use. Cached forever after.<\/p>\n
**\ud83d\udd14 Instant URL Broadcast** \u2014 URL goes to console and all online OPs the moment the tunnel is ready.<\/p>\n
**\ud83c\udfae Full Command Support** \u2014 `\/tunnel` with tab completion for everything.<\/p>\n
**\ud83d\udd01 Auto-Restart & Crash Loop Protection** \u2014 Tunnels restart after failure. Stops retrying if it fails too many times in a short window.<\/p>\n
**\ud83e\ude7a Health Checks** \u2014 ngrok tunnels get API-level checks; cloudflared tunnels get process-alive checks.<\/p>\n
**\ud83d\udc0b Pterodactyl Compatible** \u2014 Tunnels are outbound connections, so no extra port allocations are ever needed.<\/p>\n
—<\/p>\n
## \ud83d\udce5 Installation<\/p>\n
1. Drop `TunnelMC.jar` into `plugins\/`
\n2. Start the server \u2014 TunnelMC generates config and auto-exposes the dashboard via cloudflared if no tunnels are configured
\n3. Open the printed URL in your browser
\n4. Configure tunnels from the dashboard, or edit `config.yml` and run `\/tunnel reload`<\/p>\n
—<\/p>\n
## \u2699\ufe0f Configuration<\/p>\n
“`yaml
\nauto-start: false
\ndefault-region: “us” # fallback region for ngrok tunnels
\nnotify-ops: true
\nauto-restart: true
\nrestart-delay-seconds: 10
\nmax-restarts: 5
\ncrash-window-seconds: 60
\nhealth-check-interval-seconds: 30<\/p>\n
dashboard:
\n enabled: true
\n port: 8090
\n bind-address: “127.0.0.1”
\n password: “changeme”
\n auto-expose-on-first-run: true<\/p>\n
tunnels:
\n # Cloudflared quick tunnel \u2014 no account, random URL, HTTP only
\n – name: “dashboard”
\n port: 8090
\n provider: “cloudflared”
\n auto-start: true<\/p>\n
# ngrok HTTP tunnel with its own account token
\n – name: “noderunner”
\n port: 8080
\n provider: “ngrok”
\n protocol: “http”
\n region: “us”
\n authtoken: “your-ngrok-token-here”<\/p>\n
# ngrok TCP tunnel from a different account
\n – name: “gameserver”
\n port: 25565
\n provider: “ngrok”
\n protocol: “tcp”
\n region: “eu”
\n authtoken: “another-account-token”<\/p>\n
# Cloudflared named tunnel \u2014 persistent custom domain
\n – name: “mc”
\n port: 25565
\n provider: “cloudflared”
\n token: “your-cloudflare-zero-trust-token”
\n hostname: “mc.yourdomain.com”
\n“`<\/p>\n
—<\/p>\n
## \ud83c\udfae Commands & Permissions<\/p>\n
**Permission:** `tunnelmc.admin` *(default: OP)*<\/p>\n
| Command | Description |
\n|—|—|
\n| `\/tunnel start [name]` | Start all or a specific tunnel |
\n| `\/tunnel stop [name]` | Stop all or a specific tunnel |
\n| `\/tunnel restart [name]` | Restart all or a specific tunnel |
\n| `\/tunnel url [name]` | Show public URL(s) |
\n| `\/tunnel status` | Show all tunnel status |
\n| `\/tunnel download ngrok` | Download ngrok binary |
\n| `\/tunnel download cloudflared` | Download cloudflared binary |
\n| `\/tunnel dashboard` | Show dashboard port info |
\n| `\/tunnel reload` | Reload config and restart tunnels |<\/p>\n
—<\/p>\n
## \ud83d\udccb Provider Comparison<\/p>\n
| | ngrok | Cloudflared Quick | Cloudflared Named |
\n|—|:—:|:—:|:—:|
\n| Account required | \u2705 free | \u274c none | \u2705 free |
\n| HTTP tunnels | \u2705 | \u2705 | \u2705 |
\n| TCP tunnels | \u2705 | \u274c | \u2705 |
\n| Persistent URL | paid only | \u274c | \u2705 |
\n| Multiple accounts | \u2705 per-tunnel | \u2014 | \u2014 |<\/p>\n
—<\/p>\n
## \u26a0\ufe0f Free Plan Notes<\/p>\n
**ngrok free:** one active tunnel at a time, random URL on each restart, bandwidth limits. Authtoken is required for all ngrok v3 tunnels. Per-tunnel authtokens let you use multiple free accounts to work around the one-tunnel limit.<\/p>\n
**Cloudflared quick tunnels:** HTTP only, random `*.trycloudflare.com` URL, no bandwidth limits.<\/p>\n
**Cloudflared named tunnels:** require a Cloudflare account (free), any protocol, persistent custom domain.<\/p>\n
—<\/p>\n
## \ud83d\udc0b Pterodactyl<\/p>\n
No extra port allocations needed \u2014 tunnels are outbound connections only. The dashboard also binds locally and doesn’t need an allocated port.<\/p>\n
**Slow download?** TunnelMC will warn after 30 seconds with manual install steps. Place the binary at `plugins\/TunnelMC\/ngrok\/ngrok` or `plugins\/TunnelMC\/cloudflared\/cloudflared` and restart.<\/p>\n
—<\/p>\n
## \ud83d\udcca Compatibility<\/p>\n
| | |
\n|—|—|
\n| **Platforms** | Bukkit, Spigot, Paper, Purpur |
\n| **Minecraft** | 1.21.x \u2013 26.1.x |
\n| **Java** | 25+ (compiled with Java 25) |
\n| **OS** | Linux, macOS, Windows |
\n| **Arch** | x64, ARM64 |<\/p>\n
—<\/p>\n
## \ud83d\udd17 Related<\/p>\n
**NodeRunner** \u2014 Run a Node.js Discord bot inside your Minecraft server.<\/p>\n
**PyRunner** \u2014 Run a Python Discord bot inside your Minecraft server.<\/p>\n
*TunnelMC pairs perfectly with both \u2014 a cloudflared quick tunnel to port 8080 makes their dashboards publicly accessible with zero port allocation.*<\/p>\n
—<\/p>\n
*Developed by Spider*<\/p>\n","protected":false},"excerpt":{"rendered":"
Expose any server port to the internet via ngrok and cloudflared tunnels \u2014 no extra port allocations needed.<\/p>\n","protected":false},"featured_media":160614,"template":"","meta":{"_minecraft_slug":"tunnelmc","_minecraft_project_id":"cEYrTBi3","_minecraft_author":"spider2742","_minecraft_license":"LicenseRef-All-Rights-Reserved","_minecraft_downloads":28,"_minecraft_follows":0,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"tunnelmc.zip","_minecraft_size_bytes":212530,"_minecraft_version_count":4,"_minecraft_updated_at":"2026-05-15T22:19:33.919674Z","_minecraft_date_created":"2026-04-14T00:08:02.183978Z","_minecraft_date_modified":"2026-05-14T12:26:59.738487Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/tunnelmc","_minecraft_icon_attachment_id":160614,"_minecraft_imported_at":"2026-06-09T14:59:23+00:00","_minecraft_import_hash":"b5383300636d57a59bf19eb60fcc826c","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[124,125,126,127,128,129,123,92],"mod_loader":[130,131,132,133,134],"minecraft_version":[62,37,40,41,73,74,38,78,79,80,81,82,83,167,163],"class_list":["post-160613","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-bukkit","mod_category-folia","mod_category-management","mod_category-paper","mod_category-purpur","mod_category-spigot","mod_category-technology","mod_category-utility","mod_loader-bukkit","mod_loader-folia","mod_loader-paper","mod_loader-purpur","mod_loader-spigot","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9","minecraft_version-26-1","minecraft_version-26-1-1","minecraft_version-26-1-2"],"yoast_head":"\n