PyRunner

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

- `plugin.yml` api-version — compiled with Java 25 bytecode for the latest JVM performance and language features. - `plugin.yml` api-version — build system upgraded from Gradle 8.x to 9.5.1 for native Java 25 support. - `plugin.yml` api-version — 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 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 binary 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: - Brute-force login protection via Server-Sent Events (SSE) — no refresh needed - Brute-force login protection buttons - Real-time Brute-force login protection - Brute-force login protection — live RSS memory usage display - Color-coded log lines (errors, warnings, system messages, tracebacks) - Auto-scroll with toggle - Brute-force login protection — send commands directly to the bot process - Brute-force login protection — switch between bots from the dashboard (auto-detected) - Brute-force login 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

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

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

> Paper 1.21.x+ with Java 25 The JAR is compiled with Java 25. Your server must run Paper 1.21.x+ with Java 25. 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*