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.4.0: playit.gg Support

A static address, right protocol per tunnel. playit.gg is the pick for Bedrock/Geyser — TCP for Java Edition, UDP for Bedrock (Bedrock/RakNet is UDP-only), both with an address that survives restarts. Neither ngrok's free tier nor cloudflared quick tunnels can do that, and the official playit.gg plugin doesn't support UDP either. Combined TCP+UDP and TCP-only custom tunnels are also available (require playit premium); UDP-only and the two Minecraft presets work on the free tier.

No token to paste. Link an account from the dashboard's Settings tab — click Link, open the generated claim link, approve it in your browser, and the dashboard flips to linked automatically.

One shared agent. playit's model is one agent per machine (accounts have a limited agent quota), so TunnelMC runs a single playitd process shared by every playit tunnel you add. Every claim provisions a fresh agent identity — there's no API to target an existing one — so Unlink deletes this server's tunnels from your playit.gg account before clearing the secret, and a re-link recreates them fresh with new addresses. That keeps tunnels from piling up on your account; the one thing that still needs manual cleanup is the old agent record itself at playit.gg/account/agents, since playit has no API to delete an agent at all.

Clean up leftovers without leaving the dashboard. A "Check for Other Tunnels" button in Settings finds any tunnel on your playit agent that TunnelMC isn't tracking and lets you delete it in place. Deleting a tunnel from the Tunnels tab deletes it on playit's side too.

macOS: playit.gg publishes no official Mac binary. The dashboard offers a TunnelMC-compiled build (SHA-256 verified) or self-build instructions — ngrok and cloudflared are unaffected and work normally on macOS.

---

✨ 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"

  # 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)

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 download playit	Download playit binary
/tunnel playit claim	Print a link to link a playit.gg account
/tunnel playit status	Show playit.gg link status
/tunnel playit unlink	Unlink playit.gg and stop its tunnels
/tunnel dashboard	Show dashboard port info
/tunnel reload	Reload config and restart tunnels

---

📋 Provider Comparison

	ngrok	Cloudflared Quick	Cloudflared Named	playit.gg
Account required	✅ free	❌ none	✅ free	✅ free
HTTP tunnels	✅	✅	✅	✅ (via TCP)
TCP tunnels	✅	❌	✅	✅ (Java preset free; custom TCP-only needs premium)
UDP tunnels	❌	❌	❌	✅ (free — Bedrock preset and custom UDP)
Persistent URL	paid only	❌	✅	✅
Multiple accounts	✅ per-tunnel	—	—	—
macOS build	✅	✅	✅	⚠️ TunnelMC-built

---

⚠️ 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

Platforms	Bukkit, Spigot, Paper, Purpur
Minecraft	1.21.x – 26.2.x
Java	25+ (compiled with Java 25)
OS	Linux, macOS, Windows
Arch	x64, ARM64

⚠️ 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