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.

---

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

• Live log streaming via Server-Sent Events (no page refresh)
• Start / Stop / Restart / npm install buttons
• Real-time status, uptime, PID, and restart count
• Color-coded log output with auto-scroll toggle

🔔 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.

🐋 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

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)
    nodejs/          ← Auto-downloaded Node.js binary (don't touch)

---

🎮 Commands & Permissions

Permission: noderunner.admin (default: OP)

Command	Description
/nodebot start	Start the bot process
/nodebot stop	Stop the bot process
/nodebot restart	Restart the bot process
/nodebot status	Show state, uptime, PID, restart count
/nodebot install	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 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

---

📊 Compatibility

Primary Target	Paper 1.21.1
Backwards Compatible	Paper / Spigot 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

TunnelMC — Expose any server port to the internet via ngrok tunnels. If your host doesn't provide multiple port allocations (common on Pterodactyl shared hosting), TunnelMC pairs perfectly with NodeRunner to make the web dashboard publicly accessible 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