NodeRunner

What's new in 1.3.0

Dashboard — Settings & Bot Management

The web dashboard has been completely overhauled. It is no longer just a log viewer — it now gives you full control over the plugin without ever touching config.yml or SSHing into the server. New Settings tab — every config value is editable live from the browser: - Process behaviour: auto-restart toggle, restart delay, max restarts, crash window, startup delay - Node.js runtime: version pin and custom executable path - Discord webhook: URL, enable/disable, and individual toggles for each event type (start, stop, crash, log lines) - Dashboard: log history line count and password (changing the password immediately invalidates all active sessions) New Bots tab — full bot instance management with TunnelMC-style modal dialogs: - Add a new bot (name, entry file, env vars) — starts automatically - Edit an existing bot — stops it, applies the new config, and restarts - Delete a bot — stops it and removes it from config.yml - All changes persist to disk immediately Download logs — a new button on the sidebar downloads the current bot.log as a file attachment. SSE push-based streaming — log lines are now pushed directly to the browser the moment they are written, rather than polled. This eliminates latency and CPU overhead. Log counter fix — the line counter now reflects what is actually visible in the DOM (capped at 3000) rather than a stale incrementing integer that could exceed the cap. `switchBot()` race fixed — historical logs are now fully loaded before the SSE stream connects, preventing out-of-order or duplicate lines when switching bots.

Bug Fixes

- `failedAttempts` map unbounded growth — the brute-force attempt tracker is now swept hourly alongside the session map, preventing unbounded accumulation of stale IP entries. - JSON injection in status/bots API — bot names and entry file paths are now serialised with Gson instead of string concatenation, preventing malformed JSON if a name contains quotes or backslashes. - `setsid` path now covers Alpine Linux / Pterodactyl — checks /usr/bin/setsid, /bin/setsid, and /usr/local/bin/setsid before falling back gracefully. Previously only /usr/bin/setsid was checked, so process group killing silently did nothing on Alpine-based containers. - `FileReader` platform charset — /proc/<pid>/status is now read with explicit UTF-8 instead of the JVM default charset. - `FileUtils.deleteDir()` now returns `boolean` — failures are logged per-file instead of silently swallowed. - GET endpoints reject non-GET requests — /api/status, /api/bots, /api/logs/recent, /api/logs/stream now return 405 for wrong-method requests. - Log timestamps include the date — entries now use MM-dd HH:mm:ss format so logs spanning midnight are unambiguous. - Content-Security-Policy header added to all dashboard responses. - Gradle performance flags — parallel, caching, and G1GC JVM args added to gradle.properties for faster local builds. - Fixed state race condition — BotState is now managed via AtomicReference instead of a plain volatile field, eliminating a class of bugs where background threads could set the state back to RUNNING after a stop was already requested. - Fixed child process orphaning on stop — NodeRunner now launches the bot with setsid on Linux/macOS and sends kill -TERM -<pgid> on stop, matching PyRunner's behaviour. Previously, any subprocesses spawned by the bot (workers, shell scripts, etc.) were left running after the parent was killed. - Fixed `extractTar` double-reading the archive — The extracted directory is now located by diffing the folder listing before and after extraction. The old approach ran tar tf on the archive file a second time, which could fail if the archive had already been deleted. - Fixed `restart()` busy-wait — The polling loop (Thread.sleep(200) in a while loop) has been replaced with a CountDownLatch, so restarts are both more reliable and use zero CPU while waiting. - Fixed `HttpClient` created per request — A single shared HttpClient instance is now reused across all Node.js version and download requests, rather than constructing a new one (with its own thread pools and connection pool) for each call. - Fixed config values not validated — All numeric config getters (restart-delay-seconds, max-restarts, crash-window-seconds, startup-delay-seconds) now clamp to valid ranges, preventing Thread.sleep(-N) exceptions from negative values. - Fixed log-history cap not enforced — getDashboardLogHistory() is now capped at 500 (matching LogManager's ring buffer size), so requesting more lines than the buffer holds no longer silently returns a truncated result without warning. - Fixed static `instance` not `volatile` — The singleton is now declared volatile for safe cross-thread visibility, and is nulled out in onDisable() to prevent classloader leaks on plugin reload. - Fixed Discord embed JSON escaping — Webhook embeds now use Gson's toJson() for string serialisation instead of a manual replace() chain, correctly escaping all Unicode control characters (\u0000–\u001F) that could cause Discord to reject payloads. - Fixed malformed bot entries crashing plugin load — Each entry in the bots: YAML list is now parsed inside a try-catch; a bad entry logs a warning and is skipped rather than throwing a ClassCastException that aborts the whole enable sequence. - Added default password warning — A prominent console warning is now printed at startup if the dashboard is enabled and the password is still set to "changeme". - Improved `getBotDir()` fallback — When entry-file has no directory component (e.g. index.js instead of bot/index.js), the plugin now derives the directory from the actual file path and logs a descriptive warning, rather than silently assuming "bot". - Fixed dashboard SSE exhausting the HTTP thread pool — The server now uses Java 21 virtual threads (newVirtualThreadPerTaskExecutor) instead of a fixed 8-thread pool. Previously, 8+ simultaneous SSE log-stream connections (e.g. multiple open tabs or reconnect storms) would fill the pool and cause all other API requests — status polls, button clicks — to hang indefinitely. - Fixed `DashboardServer.jsonString()` unsafe escaping — Dashboard log API responses now use GSON.toJson() instead of a manual replace() chain. Log lines containing Unicode control characters (\u0000–\u001F) could previously produce malformed JSON that failed to parse in the browser. - Fixed memory cache non-atomic reads — The three separate volatile fields (cachedMemKb, cachedMemPid, cachedMemTime) have been replaced with a single volatile MemCache record, swapped atomically. A thread could previously observe a new timestamp alongside stale memory values from the previous cycle. - Fixed SSE handler busy-polling — The while (!heartbeatFuture.isDone()) Thread.sleep(1000) loop is replaced with heartbeatFuture.get(), eliminating the 1-second wake-up overhead while waiting for clients to disconnect. - Fixed session map growing without bound — A ScheduledExecutorService now sweeps expired sessions every hour. Previously, repeated logins without a server restart would accumulate stale entries in the map indefinitely. - Fixed dashboard password using string equality — The login check now uses MessageDigest.isEqual() for constant-time comparison, preventing theoretical timing attacks on the password. - Fixed duplicate `deleteDir()` logic — A new shared util/FileUtils.deleteDir() (NIO-based) replaces the identical recursive-delete method that was duplicated across NodeBotCommand and DashboardServer. - Fixed `plugin.yml` `api-version` outdated — Updated from '1.13' to '1.21' to match the actual target platform and suppress Paper's de

What's new in 1.2.0

Per-Bot Environment Variables

Each bot in the bots: list can now have its own env: block that overrides the global environment variables — useful for running multiple bots with different tokens.

Multi-Bot Dashboard Selector

When running multiple bots, the dashboard now shows a bot selector dropdown to switch between bots without leaving the page.

Dashboard Security Hardening

- CSRF protection — All mutating API endpoints now require an X-NR-Request header - Brute-force login protection — Lockout after 5 failed attempts (5 minute cooldown) - Session pruning — Expired sessions are now cleaned up automatically ---

Changes

- Dashboard now uses a bounded thread pool (8 threads) instead of an unbounded cached pool - SSE heartbeats use a shared scheduled executor instead of per-connection threads - NodeDownloader is now a shared singleton — multiple bots no longer trigger duplicate downloads - Webhook shutdown is now handled cleanly on plugin disable - Restart now waits for the process to fully stop before starting again (prevents race conditions)

Bug Fixes

- Fixed stop command not waiting for the process to actually terminate before reporting "stopped" - Fixed auto-restart thread not being interrupted when manually stopping a bot

v1.1.0

New Features

- Multiple Bot Support — Run more than one Node.js bot at the same time. Define a bots: list in config.yml, each with its own name and entry file. Each bot gets its own process, log file (bot-<name>.log), and independent crash recovery. Falls back to single-bot config automatically — no breaking changes. - Node.js Version Pinning — New node-version config option (e.g. "20", "22") lets you pin a specific Node.js major version instead of always downloading the latest LTS. - stdin Passthrough — New input bar at the bottom of the web dashboard lets you send text directly to the bot's stdin without restarting it. - Memory Monitoring — The web dashboard now shows live RSS memory usage of the bot process (Linux only, reads from /proc/<pid>/status). - TunnelMC Integration — If TunnelMC is installed and has an active tunnel on the dashboard port, NodeRunner now prints the public URL to console when the bot starts. Configurable via integrations.tunnelmc-suggestion in config.yml.

Changes

- /nodebot commands now accept an optional [name] argument to target a specific bot when running multiple bots - Bot log files are now named bot-<name>.log per bot when using multi-bot mode; single-bot mode still uses bot.log - Webhook messages now include the bot name in brackets (e.g. Bot [modbot] started) when running multiple bots - Thread names now include the bot name for easier debugging

Bug Fixes

- Fixed npm install failing on Pterodactyl panels due to PATH not being set correctly — node binary directory is now explicitly injected into PATH before running npm

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](https://modrinth.com/plugin/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](https://github.com/Spider2742)