?
Host a server
Modrinth App
Sign in
ModsPluginsData PacksShadersResource PacksModpacksServers
Settings
NodeRunner

NodeRunner

Run your Node.js Discord bot directly alongside your Minecraft server! Features auto-setup, live web dashboard, and in-game controls

41
1
41
1

Compatibility

Minecraft: Java Edition

26.1.x
1.21.x

Platforms

Links

Report issues

Tags

Creators

Details

Licensed ARR
Published 2 months ago

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

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

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

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