TunnelMC

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.

What's New in 1.3.0

Java 25 & Build Modernization

- Upgraded to Java 25 — compiled with Java 25 bytecode for the latest JVM performance and language features. - Gradle 9.5.1 — build system upgraded from Gradle 8.x to 9.5.1 for native Java 25 support. - Virtual thread executor — 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

- CSRF protection — all mutating API endpoints now require an X-TM-Request header. - Brute-force login protection — lockout after 5 failed attempts with 500ms delay per failure. - Timing-safe password comparison — login now uses MessageDigest.isEqual() to prevent timing attacks. - CSP headers — 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

- `volatile` singleton — static plugin instance is now volatile and nulled on disable to prevent classloader leaks during reloads. - Config bounds checking — 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.2.x — compiled against Paper 1.21.1 API, which is forward-compatible with all Paper versions through 26.2.x. Existing configs remain fully compatible — no config changes required.

What's New in 1.2.0

Cloudflared Support

Every tunnel now has its own provider field. Choose ngrok or cloudflared per tunnel, or mix them in the same config. Cloudflared quick tunnels — zero account setup, random *.trycloudflare.com URL, HTTP only. Great for dashboards and web services. Cloudflared named tunnels — paste a Cloudflare Zero Trust token and your custom hostname. Persistent URL, any protocol you've configured in Cloudflare.

Multiple ngrok Accounts

Each ngrok tunnel now has its own authtoken field (required for ngrok v3). Authtokens are passed as a CLI flag instead of writing to the global ngrok config, so you can run tunnels from completely different ngrok accounts at the same time.

Per-Tunnel Region

Each ngrok tunnel can set its own region, overriding the global default.

Web Dashboard

A full browser-based management dashboard on port 8090 (local only). From it you can: - View all tunnels — status, URL, uptime, restarts - Start / stop / restart tunnels individually - Create, edit, and delete tunnels live — no server restart needed - Download ngrok and cloudflared binaries with one click - Edit all global settings

Auto-Expose on First Run

If no tunnels are configured, TunnelMC automatically downloads cloudflared and creates a quick tunnel to the dashboard on first startup so you can access it from anywhere right away.

Per-Tunnel Auto-Start

Each tunnel has its own auto-start field. Set it to true to start a tunnel on server boot even when global auto-start is off. The default dashboard tunnel ships with auto-start: true.

What's new in 1.1.0

Auto-Restart & Crash Loop Protection

Tunnels now restart automatically if the ngrok process exits unexpectedly. Crash loop protection kicks in if a tunnel fails too many times within a configurable time window, stopping the retry cycle to prevent runaway restarts. Both the restart delay and failure threshold are fully configurable.

Health Checks

TunnelMC now periodically verifies each tunnel is still alive by querying ngrok's local API. If a tunnel silently dies without crashing, the health check catches it and triggers an automatic restart. The check interval is configurable, or can be disabled entirely.

/tunnel download Command

You can now trigger the ngrok binary download manually at any time from in-game or console with /tunnel download. Useful if the initial download failed or you want to re-fetch the binary without restarting your server.

NodeRunner & PyRunner Integration

If [NodeRunner](https://modrinth.com/plugin/noderunner) or [PyRunner](https://modrinth.com/plugin/pyrunner) is installed and one of your configured tunnel ports matches their dashboard port, TunnelMC will print a helpful suggestion in console. This is purely informational — these bot runners are never auto-started by TunnelMC. ---

Config changes

Four new options have been added to config.yml:

auto-restart: true
restart-delay-seconds: 10
max-restarts: 5
crash-window-seconds: 60
health-check-interval-seconds: 30

integrations:
  noderunner-suggestion: true
  pyrunner-suggestion: true

Existing configs remain fully compatible — all new keys will use their defaults if not present.

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](https://modrinth.com/plugin/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](https://ngrok.com) and copy your authtoken from the [dashboard](https://dashboard.ngrok.com/get-started/your-authtoken) 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](https://ngrok.com/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](https://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](https://modrinth.com/plugin/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](https://github.com/Spider2742)