Self-hosted Minecraft Java server management for Windows and Linux.
BlockPilotMC is a self-hosted web panel for Minecraft Java servers. It handles server setup, imports, power controls, live console access, file editing, plugins, mods, modpacks, backups, users, audit records, and host monitoring from one browser window. The panel runs on your own Windows or Linux machine, and your worlds, configuration files, account data, and backups stay on that host.
BlockPilotMC is intended for people who want a practical way to manage one or more Minecraft servers without switching between terminal windows, file explorers, and separate backup tools.
Host load, Minecraft process usage, panel status, and server shortcuts are shown on the overview page.
See which servers are running and use the main power controls without opening each server first.
Review saved archives, their contents, size, location, and restore options.
Create Paper, Purpur, Vanilla, Fabric, Folia, Forge, NeoForge, or Velocity servers with guided settings.
Search Modrinth and choose a server-compatible modpack version from the panel.
Upload an .mrpack or Server Pack ZIP, or provide a direct download URL.
Add an existing server directory and let BlockPilotMC help detect its launch command.
- Create and import Minecraft Java servers, including Paper, Purpur, Vanilla, Fabric, Folia, Forge, NeoForge, Velocity, and custom launch commands.
- Use a live WebSocket console with command input, reconnect handling, color modes, search, and complete session logs.
- Browse and edit server files, manage
server.properties, and control installed plugins, mods, and manually added JAR files. - Search Modrinth, install supported
.mrpackpackages, and import author-provided Server Pack archives. - Create full or world-only backups manually or on a schedule, choose the backup storage folder from Settings, then download or restore archives from the panel.
- Monitor host CPU and memory together with Java PID, Minecraft CPU, RSS memory, JVM limit, and uptime.
- Manage administrator and operator accounts, session limits, idle sign-out, login protection, and audit records.
- Choose a light or dark interface, upload a background, edit sign-in text, and configure the panel port or optional bind IP.
- Integrate Discord Webhooks and Bots for notifications, bidirectional chat, channel status topics, and restricted remote commands.
- Run from source on Windows or Linux, or use the included systemd and Docker examples.
BlockPilotMC v1.0.5 provides per-server Discord integration with both Webhook notifications and a Discord Bot bridge.
Each server can use its own Webhook URL and display name, with selectable events:
- Server state: starting, startup completed, stopped, and abnormal results.
- Player join / leave events.
- Player chat forwarding.
- Optional warnings and errors summaries.
- Webhook URLs are encrypted in the API backend and are not returned in plaintext by normal settings reads.
Bot Tokens are encrypted in the API backend. Enable Message Content Intent in the Discord Developer Portal. The target channel needs View Channel, Send Messages, and Read Message History; automatic topic updates also require Manage Channels.
The integration supports:
- Discord guild and channel IDs.
- Discord → Minecraft chat through
tellraw. - Restricted remote commands controlled by player roles, administrator roles, and individually allowed users.
- A configurable command prefix; the default is
!bp. - Automatic channel topic updates with server state, runtime details, and player information.
BlockPilotMC analyzes launch files, JARs, Forge / NeoForge libraries, installed mods, and live help output to build the Discord command catalog. If spark is detected, TPS / MSPT lookup can also be exposed.
Each command has separate Admin allowed and Player allowed switches. Administrator roles and individually allowed users receive the administrator command set, while player roles only receive commands explicitly enabled for players. Administrator permission wins when both apply.
See docs/DISCORD.md for setup and security details.
- Node.js
22to26 - npm
10or later - Java compatible with the Minecraft version you plan to run
- A modern browser such as Chrome, Edge, Firefox, or Safari
- SQLite is embedded; no separate database server is required
Choose the launcher language:
Start-BlockPilot-EN.bat English
Start-BlockPilot-TW.bat Traditional Chinese
Start-BlockPilot-ZH.bat Simplified Chinese
Start-BlockPilot.bat Language selection menu
All three language launchers check for npm, install Node.js LTS through winget when needed, install the locked project dependencies, and build the project. Windows then opens two consoles: a WEB startup window with the panel address, and a separate API window for service messages. Routine successful dashboard polling is hidden so the API console remains readable.
BlockPilotMC v1.0.5 uses better-sqlite3 13.0.2, which includes Windows x64 prebuilt files. Python and Visual Studio Build Tools are therefore not expected for a normal supported Windows x64 installation. If npm has to fall back to native compilation, the launcher stores the full output in runtime/install/npm-install.log and shows concise instructions for Python 3 and Visual Studio 2022 Build Tools with the Desktop development with C++ workload. A production-dependency audit is saved separately as runtime/install/npm-audit.log; findings are reported without applying an automatic breaking update.
The first startup creates .env and prints a randomly generated administrator password. Save it and change the password after signing in.
Ubuntu and Debian can install BlockPilotMC as a systemd service with one command:
curl -fsSL https://raw.githubusercontent.com/BlockPilotDev/BlockPilotMC/v1.0.5/scripts/install-ubuntu.sh | sudo bashAfter installation, open http://<server-ip>:8787. The installer prints the initial administrator password once and enables automatic startup.
To run directly from a cloned source folder instead:
npm ci
chmod +x start-linux.sh
./start-linux.shstart-linux.sh creates .env when it is missing, installs platform-specific dependencies when required, builds the project, and starts the panel. For firewall, systemd, and manual package instructions, see Installation.
Run these commands from the BlockPilotMC project directory containing package.json:
npm ci
npm run setup-env
npm run build
npm startThe default local address is:
http://127.0.0.1:8787
For access from another device on the same network, set HOST=0.0.0.0, allow the selected port through the host firewall, and open the panel with the host LAN address.
A sample Dockerfile and docker-compose.yml are included. Read Docker deployment before using them, especially the volume paths for runtime/ and Server/.
Common settings are stored in .env:
PORT=8787
HOST=0.0.0.0
WEB_ORIGINS=http://localhost:8787,http://127.0.0.1:8787The panel Settings page can update the port and optional bind IP. Network changes take effect after restarting BlockPilotMC.
Do not commit .env, runtime data, server files, credentials, or API keys. See Configuration for the public-source checklist.
- Release notes
- Installation
- Configuration
- Discord integration
- Docker
- Architecture
- Troubleshooting
- Upgrade guide
- Privacy and external connections
- CurseForge official API live search
- Security policy
- Contributing
- Third-party notices
npm install
npm run lint
npm run check:i18n
npm run check:ui
npm run check:network
npm run check:source
npm run buildRun every project check with:
npm run verifyMain directories:
apps/api/ Fastify API, SQLite, process control, backups, and file services
apps/web/ React interface and translations
scripts/ Build, validation, diagnosis, and maintenance tools
docs/ Installation, deployment, security, and project documents
runtime/ Panel runtime data; only .keep belongs in Git
Server/ Minecraft server root; only .keep belongs in Git
BlockPilotMC can start Java processes, edit server files, and accept administrative commands. Do not expose it directly to an untrusted public network. Use HTTPS behind a trusted reverse proxy, a VPN, or another access-control layer for remote administration.
Report security issues privately according to SECURITY.md.
Bug reports and focused pull requests are welcome. Please read CONTRIBUTING.md before submitting changes. New interface text must include English, Traditional Chinese, and Simplified Chinese translations.
Important: forks and derivative projects must not reuse the CurseForge API key of BlockPilotMC's maintainer or any other third party.
CurseForge states that each Developer is issued a unique API Key and that the key is non-transferable and may not be shared with third parties. Every fork, modified distribution, commercial deployment, or other derivative project that enables CurseForge integration must apply for and use an API Key approved for that Developer or organization.
Public BlockPilotMC releases do not ship a maintainer API key in source code, .env, GitHub, or release archives. An administrator-provided key is stored locally in SQLite and protected at rest with AES-256-GCM. Encryption does not make a shared key compliant with CurseForge's terms; derivative projects must still obtain their own key.
Failure to replace a third-party key can expose the credential and pool API quota across unrelated users. CurseForge's terms allow API access to be declined when quotas are exceeded and allow termination for qualifying breaches; after termination, API use must stop and API Key copies must be deleted.
Read before enabling CurseForge integration:
- CurseForge 3rd Party API Terms and Conditions
- About the CurseForge API and How to Apply for a Key
- BlockPilotMC CurseForge API policy
- Fork / derivative-project requirements
BlockPilotMC is licensed under the Apache License 2.0. The repository also includes a project NOTICE and third-party notices.
Minecraft and related trademarks belong to their respective owners. BlockPilotMC is not an official product of Mojang Studios, Microsoft, CurseForge, Overwolf, or Modrinth, and is not endorsed by them.
The original BlockPilot Minecraft Panel project has been approved for access to the CurseForge 3rd Party API.
The official BlockPilotMC public build retains the original project's CurseForge API credential using AES-256-GCM encrypted local storage. The Key is not stored in .env, exposed to the frontend, or returned by normal API responses.
Forks, derivative projects, mirrors, Docker derivatives, and redistributed builds may not reuse the original BlockPilotMC CurseForge API Key. They must remove the original credential and apply for/use their own CurseForge API Key.
Apache-2.0 covers BlockPilotMC source code; it does not grant a right to reuse or sublicense the CurseForge API credential.
See:
PUBLIC_RELEASE_CURSEFORGE_NOTICE.mddocs/CURSEFORGE_API_POLICY.mddocs/CURSEFORGE_DERIVATIVE_PROJECT_REQUIREMENTS.md
If startup detects database disk image is malformed, BlockPilot preserves the original SQLite database and any WAL/SHM sidecars under runtime/recovery/database-corrupt-<timestamp>/ before creating a clean database and continuing startup. Keep the recovery folder until the new panel is confirmed working.
GitHub Actions and local CI can run:
npm run verifyThis runs TypeScript/lint verification followed by the production build.
The Minecraft resource trend now scales its RSS axis using the combined configured JVM maximum memory of all currently running servers. For example, two running servers configured for 4 GB each produce an 8 GB baseline. The scale updates automatically when servers start or stop, and still expands if actual RSS exceeds the configured total.