# PyRunner \ud83d\udc0d<\/p>\n
> **Run your Python Discord bot directly alongside your Minecraft server \u2014 no external hosting, no VPS, no hassle.**<\/p>\n
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 \u2014 all configured from a single `config.yml`.<\/p>\n
—<\/p>\n
## \ud83c\udd95 What’s new in 1.3.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
### \ud83d\udc0d Zero-Touch Python Setup
\nNo 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.<\/p>\n
### \ud83d\udce6 Automatic Dependency Installation
\nIf 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.<\/p>\n
### \ud83d\udd01 Crash Recovery & Loop Protection
\nThe 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 \u2014 preventing infinite restart spam while alerting you.<\/p>\n
### \ud83d\udda5\ufe0f Live Web Dashboard
\nA built-in HTTP server hosts a sleek, password-protected control panel accessible from any browser. Features include:
\n– **Live log streaming** via Server-Sent Events (SSE) \u2014 no refresh needed
\n– **Start \/ Stop \/ Restart \/ pip install** buttons
\n– Real-time **status, uptime, PID, and restart count**
\n– **Memory monitoring** \u2014 live RSS memory usage display
\n– Color-coded log lines (errors, warnings, system messages, tracebacks)
\n– Auto-scroll with toggle
\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– **CSRF protection** on all mutating API endpoints
\n– **Brute-force login protection** \u2014 lockout after 5 failed attempts<\/p>\n
### \ud83d\udd14 Discord Webhook Notifications
\nGet notified in a Discord channel when your bot starts, stops, crashes, or when pip install runs \u2014 all via a standard Discord webhook URL. No bot token required for notifications. Each event type is individually toggleable.<\/p>\n
### \ud83c\udfae In-Game Commands
\nFull control from the Minecraft console or in-game with the `\/pybot` command. No need to SSH into your server just to restart the bot.<\/p>\n
### \ud83e\udd16 Multiple Bot Support ### \ud83d\udccc Python Version Pinning ### \ud83d\udcbb stdin Passthrough ### \ud83d\udcca Memory Monitoring ### \ud83d\udd17 TunnelMC Integration —<\/p>\n ## \ud83d\udce5 Installation<\/p>\n 1. Download `PyRunner.jar` and place it in your `plugins\/` folder PyRunner will handle the rest \u2014 Python download, `pip install`, and bot launch happen automatically.<\/p>\n —<\/p>\n ## \ud83d\udcc2 File Structure<\/p>\n “`text —<\/p>\n ## \ud83c\udfae Commands & Permissions<\/p>\n **Permission node:** `pyrunner.admin` *(default: OP)*<\/p>\n | Command | Description | —<\/p>\n ## \ud83c\udf10 Web Dashboard<\/p>\n Open `http:\/\/ The dashboard is password protected. Change the default password in `config.yml`.<\/p>\n —<\/p>\n ## \ud83d\udd14 Discord Webhook Setup<\/p>\n 1. Open the Discord channel you want notifications in —<\/p>\n ## \ud83d\udcca Compatibility<\/p>\n | | | > **\u26a0\ufe0f 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.<\/p>\n —<\/p>\n ## \ud83d\udd17 Related Projects<\/p>\n **NodeRunner** \u2014 The Node.js equivalent of this plugin. Run a Node.js Discord bot alongside your Minecraft server.<\/p>\n **TunnelMC** \u2014 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.<\/p>\n —<\/p>\n ## \ud83d\udcc4 License<\/p>\n **All Rights Reserved** \u2014 This plugin and its source code are proprietary.<\/p>\n —<\/p>\n *Developed by Spider*<\/p>\n","protected":false},"excerpt":{"rendered":" Run your Python Discord bot directly alongside your Minecraft server! Features auto-setup, live web dashboard, and in-game controls<\/p>\n","protected":false},"featured_media":127199,"template":"","meta":{"_minecraft_slug":"pyrunner","_minecraft_project_id":"GZQD4lHs","_minecraft_author":"spider2742","_minecraft_license":"LicenseRef-All-Rights-Reserved","_minecraft_downloads":12,"_minecraft_follows":1,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"pyrunner.zip","_minecraft_size_bytes":257524,"_minecraft_version_count":4,"_minecraft_updated_at":"2026-05-15T22:59:18.505235Z","_minecraft_date_created":"2026-04-15T00:51:36.730923Z","_minecraft_date_modified":"2026-05-14T12:29:22.979509Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/pyrunner","_minecraft_icon_attachment_id":127199,"_minecraft_imported_at":"2026-06-07T11:33:58+00:00","_minecraft_import_hash":"6ceaeaae2f084af0413c1be7e0d07201","_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-127198","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 Python bot simultaneously \u2014 each with its own process, log file, and independent crash recovery. Control each bot individually with `\/pybot start
\nPin a specific Python minor version (e.g. `”3.11″`, `”3.12″`) instead of always downloading the latest release.<\/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, PyRunner will print the public URL to console when the bot starts \u2014 purely informational, TunnelMC is never auto-started.<\/p>\n
\n2. Start the server once to generate config files
\n3. Place your bot code in `plugins\/PyRunner\/bot\/` (should include `requirements.txt` for dependencies)
\n4. Edit `plugins\/PyRunner\/config.yml` \u2014 at minimum set your bot token under `env:`
\n5. Restart the server, or run `\/pybot start`<\/p>\n
\nplugins\/
\n PyRunner\/
\n config.yml \u2190 All plugin settings
\n bot\/ \u2190 Your bot code goes here
\n main.py
\n requirements.txt
\n .pyrunner_deps_installed \u2190 Created after successful pip install
\n logs\/
\n bot.log \u2190 Live bot output (rotates at 5MB, keeps 3 backups)
\n bot-
\n python\/ \u2190 Auto-downloaded Python binary (do not edit)
\n python.properties \u2190 Cached binary paths
\n“`<\/p>\n
\n|—|—|
\n| `\/pybot start [name]` | Start the bot (or a specific bot by name) |
\n| `\/pybot stop [name]` | Stop the bot (or a specific bot by name) |
\n| `\/pybot restart [name]` | Restart the bot (or a specific bot by name) |
\n| `\/pybot status [name]` | Show status of all bots or a specific one |
\n| `\/pybot install [name]` | Force re-run pip install |
\n| `\/pybot reload` | Reload config.yml |<\/p>\n
\n2. Go to **Edit Channel \u2192 Integrations \u2192 Webhooks \u2192 New Webhook**
\n3. Copy the Webhook URL
\n4. Paste it into `config.yml` under `discord.webhook.url`
\n5. Set `discord.webhook.enabled: true`
\n6. Restart the server or run `\/pybot reload`<\/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