TunnelMC 🌐

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

TunnelMC is a Bukkit/Spigot/Paper plugin that automatically downloads and manages ngrok, cloudflared, and/or playit.gg, 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.5.0: Reliability & Security Fixes

A maintenance release from a systematic audit, plus one addition to keep pace with an ngrok change:

• Added: ngrok tunnels can now use a reserved/static domain. ngrok moved domain selection to their own dashboard ("Choose your URL") — pick one there, drop it into the new hostname field, and it's passed along with --url. Leave it blank for a random domain each start, same as before.
• Fixed: editing a tunnel could silently wipe its saved authtoken/cfToken. The edit form correctly never sends secrets back to the browser, but saving an unrelated change (like toggling auto-start) was overwriting the stored token with blank — breaking the tunnel on its next start. Blank secret fields on save now keep the existing value; only an actual new value overwrites it.
• Fixed: a tunnel name containing an apostrophe broke every action button on that tunnel's card. Start/Stop/Restart/Delete/Copy buttons are now correctly escaped for names, URLs, and IDs containing ', ", or \.
• Fixed: renaming a tunnel to an existing tunnel's name silently orphaned the old one. The old tunnel's process kept running with nothing left tracking it, and it disappeared from config.yml entirely. Renaming to a name already in use is now rejected instead.
• Fixed: clicking Stop immediately after Start could leave an untracked tunnel process running, and later resurrect it as "running" in the dashboard even though you'd explicitly stopped it. A start/stop race no longer lets a launch that lost the race adopt its process.
• Fixed: playit.gg's "Try Again" button could hand back a dead claim session for up to ~11 minutes after a rejected or cancelled link attempt, instead of issuing a fresh code.
• Fixed: an unsanitized tunnel name could write ngrok's per-tunnel config file outside the intended directory. Tunnel names are now restricted to letters, numbers, _, and -.
• Fixed: editing any tunnel could silently wipe a saved ngrok reserved domain back to blank, since the persistence path rebuilt every tunnel's entry from scratch on every save.
• Fixed: a malformed dashboard API request could return an empty, unexplained server error with nothing in the log. Bad requests now get a clear JSON error and the real cause is logged server-side.
• Improved: error logging for playit/ngrok/cloudflared download and connection failures now always includes the exception type (and throw site when there's no message), instead of sometimes printing a bare "null".

✨ Features

🌐 Three Tunnel Providers — ngrok, cloudflared, and playit.gg, configurable per tunnel. Mix them freely.

📡 UDP + Static Addresses (playit.gg) — the only provider here with a stable UDP address, built for Bedrock/Geyser. TCP-only and combined TCP+UDP tunnels are also available (require playit premium).

🔑 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

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"

  # ngrok tunnel with a reserved/static domain (picked from ngrok's dashboard)
  - name: "stable-mc"
    port: 25565
    provider: "ngrok"
    protocol: "tcp"
    authtoken: "your-ngrok-token-here"
    hostname: "your-reserved-domain.ngrok-free.dev"

  # Cloudflared named tunnel — persistent custom domain
  - name: "mc"
    port: 25565
    provider: "cloudflared"
    token: "your-cloudflare-zero-trust-token"
    hostname: "mc.yourdomain.com"

  # playit.gg — link an account from the dashboard first (Settings tab); Bedrock is UDP-only
  - name: "bedrock"
    port: 19132
    provider: "playit"
    playit-type: "minecraft-bedrock"
    auto-start: true

🎮 Commands & Permissions

Permission: tunnelmc.admin (default: OP)

📋 Provider Comparison

⚠️ 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, plugins/TunnelMC/cloudflared/cloudflared, or plugins/TunnelMC/playit/playitd and restart.

📊 Compatibility

⚠️ macOS + playit.gg: ngrok and cloudflared ship official macOS builds and work normally. playit.gg does not — the dashboard's Settings tab offers a TunnelMC-compiled build (SHA-256 verified) or self-build instructions.

🔗 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~~~~