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

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

Live log streaming via Server-Sent Events (no page refresh)
Start / Stop / Restart / npm install buttons
Real-time status, uptime, PID, restart count, and memory usage
stdin input bar — send commands directly to the bot process
Multi-bot selector — switch between bots from the dashboard (auto-detected)
Color-coded log output with auto-scroll toggle
CSRF 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

Drop NodeRunner.jar into your plugins/ folder
Start the server once to generate config files
Place your bot code in plugins/NodeRunner/bot/ (needs index.js + package.json)
Set your bot token and any other secrets under env: in config.yml
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)
      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 TunnelMC or a Cloudflare Tunnel to expose it without one.

🔔 Discord Webhook Setup

Go to your Discord channel → Edit Channel → Integrations → Webhooks → New Webhook
Copy the Webhook URL
Paste it into config.yml under discord.webhook.url
Set discord.webhook.enabled: true
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


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

⚠️ Java 25 Required: The JAR is compiled with Java 25 and uses virtual threads. Your server must run Java 25 or higher. 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

Developed by Spider

NodeRunner

📖About NodeRunner