PyRunner 🐍

Run your Python Discord bot directly alongside your Minecraft server — no external hosting, no VPS, no hassle.

PyRunner is a Paper plugin that manages a Python process (typically a Discord bot) as a child process of your Minecraft server. It handles everything automatically: downloading Python, installing dependencies from requirements.txt, restarting on crash, streaming logs to a live web dashboard, and sending Discord notifications — all configured from a single config.yml.

---

🆕 What's new in 1.3.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.2.x — compiled against Paper 1.21.1 API, which is forward-compatible with all Paper versions through 26.2.x.

Existing configs remain fully compatible — no config changes required.

---

✨ Features

🐍 Zero-Touch Python Setup

No Python installed on your server? No problem. PyRunner automatically detects your OS and CPU architecture and downloads a self-contained Python binary via python-build-standalone on first start. Works on Linux (x64 & ARM64), macOS (x64 & ARM64), and Windows (x64). The binary is downloaded once and cached locally.

📦 Automatic Dependency Installation

If your bot has a requirements.txt, PyRunner will automatically run pip install -r requirements.txt before launching whenever the deps haven't been installed yet. Delete bot/.pyrunner_deps_installed to force a reinstall on next start.

🔁 Crash Recovery & Loop Protection

The bot process is monitored constantly. If it crashes, PyRunner waits a configurable delay then restarts it automatically. If it crashes too many times in a short window, crash-loop protection kicks in and stops retrying — preventing infinite restart spam while alerting you.

🖥️ Live Web Dashboard

A built-in HTTP server hosts a sleek, password-protected control panel accessible from any browser. Features include:

• Live log streaming via Server-Sent Events (SSE) — no refresh needed
• Start / Stop / Restart / pip install buttons
• Real-time status, uptime, PID, and restart count
• Memory monitoring — live RSS memory usage display
• Color-coded log lines (errors, warnings, system messages, tracebacks)
• Auto-scroll with toggle
• stdin input bar — send commands directly to the bot process
• Multi-bot selector — switch between bots from the dashboard (auto-detected)
• CSRF protection on all mutating API endpoints
• Brute-force login protection — lockout after 5 failed attempts

🔔 Discord Webhook Notifications

Get notified in a Discord channel when your bot starts, stops, crashes, or when pip install runs — all via a standard Discord webhook URL. No bot token required for notifications. Each event type is individually toggleable.

🎮 In-Game Commands

Full control from the Minecraft console or in-game with the /pybot command. No need to SSH into your server just to restart the bot.

🤖 Multiple Bot Support

Run more than one Python bot simultaneously — each with its own process, log file, and independent crash recovery. Control each bot individually with /pybot start <n>, /pybot stop <n>, etc.

📌 Python Version Pinning

Pin a specific Python minor version (e.g. "3.11", "3.12") instead of always downloading the latest release.

💻 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, PyRunner will print the public URL to console when the bot starts — purely informational, TunnelMC is never auto-started.

---

📥 Installation

1. Download PyRunner.jar and place it in your plugins/ folder
2. Start the server once to generate config files
3. Place your bot code in plugins/PyRunner/bot/ (should include requirements.txt for dependencies)
4. Edit plugins/PyRunner/config.yml — at minimum set your bot token under env:
5. Restart the server, or run /pybot start

PyRunner will handle the rest — Python download, pip install, and bot launch happen automatically.

---

📂 File Structure

plugins/
  PyRunner/
    config.yml              ← All plugin settings
    bot/                    ← Your bot code goes here
      main.py
      requirements.txt
      .pyrunner_deps_installed  ← Created after successful pip install
    logs/
      bot.log               ← Live bot output (rotates at 5MB, keeps 3 backups)
      bot-<n>.log           ← Per-bot log files when using multiple bots
    python/                 ← Auto-downloaded Python binary (do not edit)
      python.properties     ← Cached binary paths

---

🎮 Commands & Permissions

Permission node: pyrunner.admin (default: OP)

Command	Description
/pybot start [name]	Start the bot (or a specific bot by name)
/pybot stop [name]	Stop the bot (or a specific bot by name)
/pybot restart [name]	Restart the bot (or a specific bot by name)
/pybot status [name]	Show status of all bots or a specific one
/pybot install [name]	Force re-run pip install
/pybot reload	Reload config.yml

---

🌐 Web Dashboard

Open http://<your-server-ip>:<port> in any browser (default port: 8080).

The dashboard is password protected. Change the default password in config.yml.

---

🔔 Discord Webhook Setup

1. Open the Discord channel you want notifications in
2. Go to Edit Channel → Integrations → Webhooks → New Webhook
3. Copy the Webhook URL
4. Paste it into config.yml under discord.webhook.url
5. Set discord.webhook.enabled: true
6. Restart the server or run /pybot reload

---

📊 Compatibility

Minecraft	Paper 1.21.x – 26.2.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. Your server must run Java 25 or higher. Paper 1.21.x+ with Java 25 is the recommended and fully tested setup.

---

🔗 Related Projects

NodeRunner — The Node.js equivalent of this plugin. Run a Node.js Discord bot alongside your Minecraft server.

TunnelMC — Expose any server port to the internet via ngrok tunnels. If your host doesn't provide multiple port allocations, TunnelMC pairs perfectly with PyRunner to make the web dashboard publicly accessible without needing an extra port.

---

📄 License

All Rights Reserved — This plugin and its source code are proprietary.

---

Developed by Spider