TunnelMC 🌐

Expose any port on your Minecraft server to the internet via ngrok tunnels — no extra port allocations needed.

TunnelMC is a Bukkit/Spigot/Paper plugin that automatically downloads and manages ngrok as a child process, creates tunnels for any local port, and broadcasts the public URL to console and online OPs the moment the tunnel is ready. Perfect for exposing web dashboards (like NodeRunner's WebUI) when you don't have a spare port allocation on shared or Pterodactyl hosting.

---

✨ Features

⚡ Zero-Touch ngrok Setup

No ngrok installed? No problem. TunnelMC automatically detects your OS and CPU architecture and downloads the correct ngrok v3 binary on first launch. Downloaded once, cached forever.

🔌 HTTP & TCP Protocol Support

Use http protocol for web dashboards and APIs — gets you a public https:// URL instantly. Use tcp for game servers, SSH, databases, or any other TCP traffic — gets you a tcp:// address. Note: UDP is not supported by ngrok.

🔀 Multiple Tunnels

Define as many tunnels as you need in config, each with its own name, port, and protocol. Each tunnel runs as an independent ngrok process.

🔔 Instant URL Broadcast

The public ngrok URL is printed to console and sent to all online OPs the moment the tunnel comes online — no need to dig through logs.

🎮 Full In-Game Control

Start, stop, restart, and check tunnel status from in-game or the console via /tunnel. Tab completion included.

🐋 Pterodactyl Compatible

Fully tested on Pterodactyl panels. No extra port allocation needed — that's the whole point. If your host throttles the ngrok download, TunnelMC will warn you after 30 seconds with manual install instructions.

⚙️ Auto-Start

Optionally start all tunnels automatically on server boot with a configurable startup delay.

---

📥 Installation

1. Drop TunnelMC.jar into your plugins/ folder
2. Start the server once to generate the config
3. Sign up free at ngrok.com and copy your authtoken from the dashboard
4. Paste your authtoken into plugins/TunnelMC/config.yml
5. Restart or run /tunnel start

---

⚙️ Configuration

authtoken: "your-ngrok-token-here"
auto-start: true
startup-delay-seconds: 0
region: "us"   # us, eu, ap, au, sa, jp, in
notify-ops: true

tunnels:
  - name: "dashboard"
    port: 8080
    protocol: "http"   # https:// URL

  - name: "gameserver"
    port: 25565
    protocol: "tcp"    # tcp:// URL

---

🎮 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 status of all tunnels
/tunnel reload	Reload config and restart tunnels

---

⚠️ ngrok Free Plan Limitations

• 1 tunnel at a time — Free accounts cannot run multiple simultaneous tunnels. Multiple tunnels require a paid ngrok plan.
• Random URLs — Free accounts get a new random URL on every restart. Paid plans support fixed custom domains.
• Bandwidth limits — Free accounts have monthly bandwidth limits. See ngrok's pricing.
• UDP not supported — ngrok only supports TCP-based protocols.

---

🐋 Pterodactyl Notes

No extra port allocation needed — TunnelMC handles that. However, some hosts throttle downloads from bin.equinox.io. If that happens, TunnelMC warns you after 30 seconds and you can install ngrok manually instead:

1. Download ngrok from ngrok.com/download on your PC — pick Linux → 64-bit
2. Extract the archive — you get a single file called ngrok
3. Upload it to plugins/TunnelMC/ngrok/ngrok via the file manager (the second ngrok is the file name itself)
4. Restart — TunnelMC detects it automatically and skips the download

---

📊 Compatibility

Platforms	Bukkit, Spigot, Paper, Purpur
Minecraft	1.13+
Java	11+ (21 recommended)
OS	Linux, macOS, Windows
Architectures	x64, ARM64
Hosting	Self-hosted, Pterodactyl, any VPS

⚠️ Java Version Note: Although the plugin API is compatible with 1.13+, the JAR is compiled with Java 21 which means your server must be running Java 21 or higher regardless of Minecraft version. Older Minecraft versions (1.13–1.16) typically run on Java 8 or 11 and will fail to load this plugin with an UnsupportedClassVersionError. In practice, Java 21 + Paper 1.21.x is the recommended and fully tested setup.

---

🔗 Related

NodeRunner — Run a Node.js Discord bot directly inside your Minecraft server. TunnelMC pairs perfectly with NodeRunner to expose its web dashboard without needing an extra port.

---

📄 License

All Rights Reserved — This plugin and its source code are proprietary. You may not copy, redistribute, modify, or decompile this software without explicit written permission from the author.

---

Developed by Spider