NodeRunner

NodeRunner 🚀

> Run your Node.js Discord bot directly inside your Minecraft server — no VPS, no extra hosting, no SSH.

NodeRunner is a Paper plugin that manages a Node.js process as a child of your Minecraft server. It handles everything automatically: downloading Node.js, installing dependencies, restarting on crash, live log streaming via a web dashboard, and Discord notifications — all from one `config.yml`.

---

🆕 What's new in 1.4.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 to `1.21` to match the target platform.

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

⚡ Zero-Touch Node.js Setup

No Node.js on your server? No problem. NodeRunner auto-detects your OS and CPU architecture and downloads the correct Node.js LTS binary on first launch. Works on Linux (x64 & ARM64), macOS, and Windows. Downloaded once (~30MB), cached forever.

📦 Automatic Dependency Installation

Got a `package.json`? NodeRunner runs `npm install` automatically before launch whenever `node_modules` is missing. No manual intervention needed.

🔁 Crash Recovery & Loop Protection

Your bot is monitored constantly. On crash, NodeRunner waits a configurable delay and restarts it. If it crashes too many times within a short window, crash-loop protection halts retries and alerts you — no infinite restart spam.

🖥️ Live Web Dashboard

A built-in, password-protected control panel accessible from any browser: - Brute-force login protection via Server-Sent Events (no page refresh) - Brute-force login protection buttons - Real-time status, uptime, PID, restart count, and Brute-force login protection - Brute-force login protection — send commands directly to the bot process - Brute-force login protection — switch between bots from the dashboard (auto-detected) - Color-coded log output with auto-scroll toggle - Brute-force login protection on all mutating endpoints - Brute-force login protection — lockout after 5 failed attempts

🔔 Discord Webhook Notifications

Get pinged in Discord when your bot starts, stops, crashes, or when npm install runs — via a standard webhook URL. No bot token required. Every event type is individually toggleable.

🎮 In-Game Commands

Full control from the Minecraft console or in-game via `/nodebot`. No SSH session needed just to restart your bot.

🤖 Multiple Bot Support

Run more than one Node.js bot simultaneously — each with its own process, log file, and independent crash recovery. Control each bot individually with `/nodebot start <name>`, `/nodebot stop <name>`, etc.

📌 Node.js Version Pinning

Pin a specific Node.js major version (e.g. `"22"`) instead of always downloading the latest LTS. Useful if your bot requires a specific runtime version.

💻 stdin Passthrough

Send input directly to the bot process from the web dashboard without restarting it — useful for bots that accept console commands via stdin.

📊 Memory Monitoring

The web dashboard shows live memory usage (RSS) of the bot process, read directly from `/proc/<pid>/status` on Linux.

🔗 TunnelMC Integration

If TunnelMC is installed and has an active tunnel on the dashboard port, NodeRunner will print the public URL to console when the bot starts — purely informational, TunnelMC is never auto-started.

🐋 Pterodactyl Compatible

Fully tested on Pterodactyl panels. Uses `.tar.gz` for Node.js extraction (no `xz` dependency), and correctly injects the node binary into the process PATH for npm compatibility inside containers.

---

📥 Installation

1. Drop `NodeRunner.jar` into your `plugins/` folder 2. Start the server once to generate config files 3. Place your bot code in `plugins/NodeRunner/bot/` (needs `index.js` + `package.json`) 4. Set your bot token and any other secrets under `env:` in `config.yml` 5. Restart, or run `/nodebot start`

NodeRunner handles the rest — Node.js download, `npm install`, and bot launch all happen automatically.

---

📂 File Structure

```text plugins/ NodeRunner/ config.yml ← All plugin settings bot/ ← Your bot code goes here index.js package.json logs/ bot.log ← Live output (rotates at 5MB, keeps 3 backups) bot-<name>.log ← Per-bot log files when using multiple bots nodejs/ ← Auto-downloaded Node.js binary (don't touch) ```

---

🎮 Commands & Permissions

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

| Command | Description | | :--- | :--- | | `/nodebot start [name]` | Start the bot (or a specific bot by name) | | `/nodebot stop [name]` | Stop the bot (or a specific bot by name) | | `/nodebot restart [name]` | Restart the bot (or a specific bot by name) | | `/nodebot status [name]` | Show status of all bots or a specific one | | `/nodebot install [name]` | Force re-run `npm install` | | `/nodebot reload` | Reload `config.yml` |

---

🌐 Web Dashboard

Access at `http://<your-server-ip>:8080` (port is configurable).

Password protection is enabled by default — change the default password in `config.yml` before going public.

> Pterodactyl users: The dashboard needs a second allocated port. Ask your host to add one, or use Pterodactyl users: or a Cloudflare Tunnel to expose it without one.

---

🔔 Discord Webhook Setup

1. Go to your Discord channel → Edit Channel → Integrations → Webhooks → New Webhook 2. Copy the Webhook URL 3. Paste it into `config.yml` under `discord.webhook.url` 4. Set `discord.webhook.enabled: true` 5. Restart or run `/nodebot reload`

---

🐋 Pterodactyl Notes

NodeRunner is fully tested on Pterodactyl. Keep in mind:

- The plugin uses `.tar.gz` for Node.js to avoid the `xz` dependency missing in most container images - If a previous install failed, delete `plugins/NodeRunner/nodejs/` and restart to re-download - Set your bot token and other secrets via `env:` in `config.yml` — do not hardcode them in your bot files - The dashboard needs a separate allocated port — ask your host to add one

---

📊 Compatibility

| | | | :--- | :--- | | Hosting | Paper 1.21.x – 26.1.x | | Hosting | 25+ (compiled with Java 25) | | Hosting | Linux, macOS, Windows | | Hosting | x64, ARM64 | | Hosting | Self-hosted, Pterodactyl, any VPS |

> Paper 1.21.x+ with Java 25 The JAR is compiled with Java 25 and uses virtual threads. Your server must run Paper 1.21.x+ with Java 25. Paper 1.21.x+ with Java 25 is the recommended and fully tested setup.

---

🔗 Related

TunnelMC — Expose any server port to the internet via ngrok tunnels. Pairs perfectly with NodeRunner to make the web dashboard publicly accessible without needing an extra port allocation.

PyRunner — The Python equivalent of this plugin. Run a Python Discord bot alongside your Minecraft server.

---

📄 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*