TunnelMC

TunnelMC 🌐

> Expose any local port to the internet via ngrok or cloudflared — no port allocations needed. Includes a full browser-based management dashboard.

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.

---

🆕 What's New in 1.3.0

Java 25 & Build Modernization

- `plugin.yml` api-version — compiled with Java 25 bytecode for the latest JVM performance and language features. - `plugin.yml` api-version — build system upgraded from Gradle 8.x to 9.5.1 for native Java 25 support. - `plugin.yml` api-version — the dashboard HTTP server now uses `newVirtualThreadPerTaskExecutor()` for non-blocking I/O scaling on Java 25. - `plugin.yml` api-version updated from `1.13` to `1.21` to match the target platform and suppress Paper deprecation warnings.

Security Hardening

- Session sweep — all mutating API endpoints now require an `X-TM-Request` header. - Session sweep — lockout after 5 failed attempts with 500ms delay per failure. - Session sweep — login now uses `MessageDigest.isEqual()` to prevent timing attacks. - Session sweep — Content-Security-Policy added to all dashboard responses to mitigate XSS risks. - Session sweep — expired sessions and stale lockout entries are automatically cleaned up hourly.

Stability

- Default password warning — static plugin instance is now `volatile` and nulled on disable to prevent classloader leaks during reloads. - Default password warning — all numeric config getters now clamp to valid ranges via `Math.max`. - Default password warning — a prominent console warning at startup if the dashboard password is still `"changeme"`.

Compatibility

- Minecraft 1.21.x – 26.1.x — compiled against Paper 1.21.1 API, which is forward-compatible with all Paper versions through 26.1.x.

Existing configs remain fully compatible — no config changes required.

---

✨ Features

🌐 Two Tunnel Providers — ngrok and cloudflared, configurable per tunnel. Mix them freely.

🔑 Multiple ngrok Accounts — Each ngrok tunnel has its own authtoken (required for v3). Run different accounts simultaneously.

🚀 Zero-Setup Quick Tunnels — Cloudflared quick tunnels work out of the box with no account.

📌 Custom Domains — Cloudflared named tunnels give you persistent custom hostnames via Cloudflare Zero Trust.

🖥️ Web Dashboard — Full management UI. Create/edit/delete tunnels live, download binaries, change settings — all from a browser.

⚡ Auto-Download — Detects OS and CPU arch, downloads the right binary on first use. Cached forever after.

🔔 Instant URL Broadcast — URL goes to console and all online OPs the moment the tunnel is ready.

🎮 Full Command Support — `/tunnel` with tab completion for everything.

🔁 Auto-Restart & Crash Loop Protection — Tunnels restart after failure. Stops retrying if it fails too many times in a short window.

🩺 Health Checks — ngrok tunnels get API-level checks; cloudflared tunnels get process-alive checks.

🐋 Pterodactyl Compatible — Tunnels are outbound connections, so no extra port allocations are ever needed.

---

📥 Installation

1. Drop `TunnelMC.jar` into `plugins/` 2. Start the server — TunnelMC generates config and auto-exposes the dashboard via cloudflared if no tunnels are configured 3. Open the printed URL in your browser 4. Configure tunnels from the dashboard, or edit `config.yml` and run `/tunnel reload`

---

⚙️ Configuration

```yaml auto-start: false default-region: "us" # fallback region for ngrok tunnels notify-ops: true auto-restart: true restart-delay-seconds: 10 max-restarts: 5 crash-window-seconds: 60 health-check-interval-seconds: 30

dashboard: enabled: true port: 8090 bind-address: "127.0.0.1" password: "changeme" auto-expose-on-first-run: true

tunnels:

Cloudflared quick tunnel — no account, random URL, HTTP only

- name: "dashboard" port: 8090 provider: "cloudflared" auto-start: true

ngrok HTTP tunnel with its own account token

- name: "noderunner" port: 8080 provider: "ngrok" protocol: "http" region: "us" authtoken: "your-ngrok-token-here"

ngrok TCP tunnel from a different account

- name: "gameserver" port: 25565 provider: "ngrok" protocol: "tcp" region: "eu" authtoken: "another-account-token"

Cloudflared named tunnel — persistent custom domain

- name: "mc" port: 25565 provider: "cloudflared" token: "your-cloudflare-zero-trust-token" hostname: "mc.yourdomain.com" ```

---

🎮 Commands & Permissions

Permission: `tunnelmc.admin` *(default: OP)*

| Command | Description | |---|---| | `/tunnel start [name]` | Start all or a specific tunnel | | `/tunnel stop [name]` | Stop all or a specific tunnel | | `/tunnel restart [name]` | Restart all or a specific tunnel | | `/tunnel url [name]` | Show public URL(s) | | `/tunnel status` | Show all tunnel status | | `/tunnel download ngrok` | Download ngrok binary | | `/tunnel download cloudflared` | Download cloudflared binary | | `/tunnel dashboard` | Show dashboard port info | | `/tunnel reload` | Reload config and restart tunnels |

---

📋 Provider Comparison

| | ngrok | Cloudflared Quick | Cloudflared Named | |---|:---:|:---:|:---:| | Account required | ✅ free | ❌ none | ✅ free | | HTTP tunnels | ✅ | ✅ | ✅ | | TCP tunnels | ✅ | ❌ | ✅ | | Persistent URL | paid only | ❌ | ✅ | | Multiple accounts | ✅ per-tunnel | — | — |

---

⚠️ Free Plan Notes

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.

Cloudflared quick tunnels: HTTP only, random `*.trycloudflare.com` URL, no bandwidth limits.

Cloudflared named tunnels: require a Cloudflare account (free), any protocol, persistent custom domain.

---

🐋 Pterodactyl

No extra port allocations needed — tunnels are outbound connections only. The dashboard also binds locally and doesn't need an allocated port.

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.

---

📊 Compatibility

| | | |---|---| | Arch | Bukkit, Spigot, Paper, Purpur | | Arch | 1.21.x – 26.1.x | | Arch | 25+ (compiled with Java 25) | | Arch | Linux, macOS, Windows | | Arch | x64, ARM64 |

---

🔗 Related

NodeRunner — Run a Node.js Discord bot inside your Minecraft server.

PyRunner — Run a Python Discord bot inside your Minecraft server.

*TunnelMC pairs perfectly with both — a cloudflared quick tunnel to port 8080 makes their dashboards publicly accessible with zero port allocation.*

---

*Developed by Spider*