# NodeRunner \ud83d\ude80<\/p>\n
> **Run your Node.js Discord bot directly inside your Minecraft server \u2014 no VPS, no extra hosting, no SSH.**<\/p>\n
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 \u2014 all from one `config.yml`.<\/p>\n
—<\/p>\n
## \ud83c\udd95 What’s new in 1.4.0<\/p>\n
### Java 25 & Build Modernization
\n– **Upgraded to Java 25** \u2014 compiled with Java 25 bytecode for the latest JVM performance and language features.
\n– **Gradle 9.5.1** \u2014 build system upgraded from Gradle 8.x to 9.5.1 for native Java 25 support.
\n– **Virtual thread executor** \u2014 the dashboard HTTP server now uses `newVirtualThreadPerTaskExecutor()` for non-blocking I\/O scaling on Java 25.
\n– **`plugin.yml` api-version** updated to `1.21` to match the target platform.<\/p>\n
### Compatibility
\n– **Minecraft 1.21.x \u2013 26.1.x** \u2014 compiled against Paper 1.21.1 API, which is forward-compatible with all Paper versions through 26.1.x.<\/p>\n
Existing configs remain fully compatible \u2014 no config changes required.<\/p>\n
—<\/p>\n
## \u2728 Features<\/p>\n
### \u26a1 Zero-Touch Node.js Setup
\nNo 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.<\/p>\n
### \ud83d\udce6 Automatic Dependency Installation
\nGot a `package.json`? NodeRunner runs `npm install` automatically before launch whenever `node_modules` is missing. No manual intervention needed.<\/p>\n
### \ud83d\udd01 Crash Recovery & Loop Protection
\nYour 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 \u2014 no infinite restart spam.<\/p>\n
### \ud83d\udda5\ufe0f Live Web Dashboard
\nA built-in, password-protected control panel accessible from any browser:
\n– **Live log streaming** via Server-Sent Events (no page refresh)
\n– **Start \/ Stop \/ Restart \/ npm install** buttons
\n– Real-time status, uptime, PID, restart count, and **memory usage**
\n– **stdin input bar** \u2014 send commands directly to the bot process
\n– **Multi-bot selector** \u2014 switch between bots from the dashboard (auto-detected)
\n– Color-coded log output with auto-scroll toggle
\n– **CSRF protection** on all mutating endpoints
\n– **Brute-force login protection** \u2014 lockout after 5 failed attempts<\/p>\n
### \ud83d\udd14 Discord Webhook Notifications
\nGet pinged in Discord when your bot starts, stops, crashes, or when npm install runs \u2014 via a standard webhook URL. No bot token required. Every event type is individually toggleable.<\/p>\n
### \ud83c\udfae In-Game Commands
\nFull control from the Minecraft console or in-game via `\/nodebot`. No SSH session needed just to restart your bot.<\/p>\n
### \ud83e\udd16 Multiple Bot Support ### \ud83d\udccc Node.js Version Pinning ### \ud83d\udcbb stdin Passthrough ### \ud83d\udcca Memory Monitoring ### \ud83d\udd17 TunnelMC Integration ### \ud83d\udc0b Pterodactyl Compatible —<\/p>\n ## \ud83d\udce5 Installation<\/p>\n 1. Drop `NodeRunner.jar` into your `plugins\/` folder NodeRunner handles the rest \u2014 Node.js download, `npm install`, and bot launch all happen automatically.<\/p>\n —<\/p>\n ## \ud83d\udcc2 File Structure —<\/p>\n ## \ud83c\udfae Commands & Permissions<\/p>\n **Permission:** `noderunner.admin` *(default: OP)*<\/p>\n | Command | Description | —<\/p>\n ## \ud83c\udf10 Web Dashboard<\/p>\n Access at `http:\/\/ Password protection is enabled by default \u2014 **change the default password in `config.yml` before going public.**<\/p>\n > **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.<\/p>\n —<\/p>\n ## \ud83d\udd14 Discord Webhook Setup<\/p>\n 1. Go to your Discord channel \u2192 **Edit Channel \u2192 Integrations \u2192 Webhooks \u2192 New Webhook** —<\/p>\n ## \ud83d\udc0b Pterodactyl Notes<\/p>\n NodeRunner is fully tested on Pterodactyl. Keep in mind:<\/p>\n – The plugin uses `.tar.gz` for Node.js to avoid the `xz` dependency missing in most container images —<\/p>\n ## \ud83d\udcca Compatibility<\/p>\n | | | > **\u26a0\ufe0f 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.<\/p>\n —<\/p>\n ## \ud83d\udd17 Related<\/p>\n **TunnelMC** \u2014 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.<\/p>\n **PyRunner** \u2014 The Python equivalent of this plugin. Run a Python Discord bot alongside your Minecraft server.<\/p>\n —<\/p>\n ## \ud83d\udcc4 License<\/p>\n **All Rights Reserved** \u2014 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.<\/p>\n —<\/p>\n *Developed by Spider*<\/p>\n","protected":false},"excerpt":{"rendered":" Run your Node.js Discord bot directly alongside your Minecraft server! Features auto-setup, live web dashboard, and in-game controls<\/p>\n","protected":false},"featured_media":112973,"template":"","meta":{"_minecraft_slug":"noderunner","_minecraft_project_id":"YL9bPIyR","_minecraft_author":"spider2742","_minecraft_license":"LicenseRef-All-Rights-Reserved","_minecraft_downloads":19,"_minecraft_follows":1,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"noderunner.zip","_minecraft_size_bytes":297480,"_minecraft_version_count":5,"_minecraft_updated_at":"2026-05-15T22:42:11.908525Z","_minecraft_date_created":"2026-04-10T23:52:35.534595Z","_minecraft_date_modified":"2026-05-14T12:28:19.667092Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/noderunner","_minecraft_icon_attachment_id":112973,"_minecraft_imported_at":"2026-06-06T15:34:30+00:00","_minecraft_import_hash":"1127801a69a2c957be419935d6b0b4df","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[124,125,126,127,128,129,123,92],"mod_loader":[130,131,132,133,134],"minecraft_version":[62,37,40,41,73,74,38,78,79,80,81,82,83,167,163],"class_list":["post-112972","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-bukkit","mod_category-folia","mod_category-management","mod_category-paper","mod_category-purpur","mod_category-spigot","mod_category-technology","mod_category-utility","mod_loader-bukkit","mod_loader-folia","mod_loader-paper","mod_loader-purpur","mod_loader-spigot","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9","minecraft_version-26-1","minecraft_version-26-1-1","minecraft_version-26-1-2"],"yoast_head":"\n
\nRun more than one Node.js bot simultaneously \u2014 each with its own process, log file, and independent crash recovery. Control each bot individually with `\/nodebot start
\nPin 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.<\/p>\n
\nSend input directly to the bot process from the web dashboard without restarting it \u2014 useful for bots that accept console commands via stdin.<\/p>\n
\nThe web dashboard shows live memory usage (RSS) of the bot process, read directly from `\/proc\/
\nIf TunnelMC is installed and has an active tunnel on the dashboard port, NodeRunner will print the public URL to console when the bot starts \u2014 purely informational, TunnelMC is never auto-started.<\/p>\n
\nFully 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.<\/p>\n
\n2. Start the server once to generate config files
\n3. Place your bot code in `plugins\/NodeRunner\/bot\/` (needs `index.js` + `package.json`)
\n4. Set your bot token and any other secrets under `env:` in `config.yml`
\n5. Restart, or run `\/nodebot start`<\/p>\n
\n“`text
\nplugins\/
\n NodeRunner\/
\n config.yml \u2190 All plugin settings
\n bot\/ \u2190 Your bot code goes here
\n index.js
\n package.json
\n logs\/
\n bot.log \u2190 Live output (rotates at 5MB, keeps 3 backups)
\n bot-
\n nodejs\/ \u2190 Auto-downloaded Node.js binary (don’t touch)
\n“`<\/p>\n
\n| :— | :— |
\n| `\/nodebot start [name]` | Start the bot (or a specific bot by name) |
\n| `\/nodebot stop [name]` | Stop the bot (or a specific bot by name) |
\n| `\/nodebot restart [name]` | Restart the bot (or a specific bot by name) |
\n| `\/nodebot status [name]` | Show status of all bots or a specific one |
\n| `\/nodebot install [name]` | Force re-run `npm install` |
\n| `\/nodebot reload` | Reload `config.yml` |<\/p>\n
\n2. Copy the Webhook URL
\n3. Paste it into `config.yml` under `discord.webhook.url`
\n4. Set `discord.webhook.enabled: true`
\n5. Restart or run `\/nodebot reload`<\/p>\n
\n– If a previous install failed, delete `plugins\/NodeRunner\/nodejs\/` and restart to re-download
\n– Set your bot token and other secrets via `env:` in `config.yml` \u2014 do **not** hardcode them in your bot files
\n– The dashboard needs a separate allocated port \u2014 ask your host to add one<\/p>\n
\n| :— | :— |
\n| **Minecraft** | Paper 1.21.x \u2013 26.1.x |
\n| **Java** | 25+ (compiled with Java 25) |
\n| **OS** | Linux, macOS, Windows |
\n| **Architectures** | x64, ARM64 |
\n| **Hosting** | Self-hosted, Pterodactyl, any VPS |<\/p>\n