MinePanel

Self-hosted Minecraft server management, the right way.

A single docker compose up brings up the stack on your own machine. No cloud lock-in. Full control.

Get Started Open Web App

Hosted dashboard for your self-hosted MinePanel instance.

Source Code Roadmap

[ Project Status ]

Usable today. Still being built.

[ EARLY ACCESS ]

MinePanel is already running.

You can self-host the panel today on your own hardware. The hosted dashboard is a client for self-hosted instances; MinePanel does not host your Minecraft servers for you.

  • Docker deployment with PostgreSQL and Caddy HTTPS
  • Account authentication, sessions, TOTP 2FA, and optional Google sign-in
  • Create, start, stop, restart, and delete Minecraft servers
  • Per-server OPEN, REQUEST, and PRIVATE access controls
  • Admin host metrics over authenticated WebSocket connections

[ ACTIVE DEVELOPMENT ]

More operations are on the roadmap.

The foundation is usable, while the operational surface is still expanding. Committed roadmap work includes:

  • Richer real-time events and server console operations
  • Backups and scheduled tasks
  • File and plugin management

[ What it does ]

Core Features

⚡

One-Command Deploy

The full stack - backend, database and MC servers - runs on your hardware with a single command. No required hosted control plane, no cloud lock-in.

🐳

Docker-Native

Each Minecraft server runs in its own isolated container, controlled through a local Docker socket (rootful by default; rootless via DOCKER_SOCKET).

🔗

Multi-Backend

The hosted PWA discovers independent self-hosted backends. Cross-origin auth uses HttpOnly CHIPS Partitioned cookies coordinated with Web Locks on supported browsers; PKCE remains only a possible future compatibility option.

🛡️

Role System

Three roles: ADMIN, MOD, USER. MODs get granular per-server permissions without full admin access - built-in PBAC.

📡

Real-Time Events

Host metrics (CPU, RAM, disk) pushed to admins via WebSocket. Live per-server stats, console logs, and player events land in later phases.

🔒

Security First

JWT via HttpOnly cookies, rate limiting, Helmet security headers, input validation, and Docker socket guardrails.

[ Future phases ]
📱

Mobile App

KMP app for iOS and Android. Not just for admins - players get their own portal: server status, access requests, push notifications, and profile.

👤

Player Portal

Unlike other MC panels, MinePanel is built for players too. Server discovery and access requests already exist; the richer player portal - Minecraft profile, playtime, and notifications - arrives in later phases.

[ Built with ]

Tech Stack

TypeScript 5NestJS v11Bun 1.3PostgreSQL 16Drizzle ORMDocker / DockerodeCaddy (auto-HTTPS)JWT · HttpOnly Cookies2FA · TOTPSocket.IO (WebSocket)Helmet · ThrottlerRCON via docker exec (rcon-cli)GitHub Actions CI/CD

[ Quick Deploy ]

# Download deployment assets for the current edge channel
curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/MinePanelProject/minepanel-backend/master/docker-compose.yml
curl -fsSLo .env.example https://raw.githubusercontent.com/MinePanelProject/minepanel-backend/master/.env.example
curl -fsSLo Caddyfile https://raw.githubusercontent.com/MinePanelProject/minepanel-backend/master/Caddyfile
cp .env.example .env

# Set required values in .env, then use pre-stable edge
sed -i 's|^MINEPANEL_IMAGE=.*|MINEPANEL_IMAGE=ghcr.io/minepanelproject/minepanel-backend:edge|' .env
docker compose pull
docker compose up -d

Edge is the current pre-stable channel; no stable release is published yet. Requires Docker Engine with Compose, a domain, open ports 80/443, configured secrets, and Minecraft data storage.

[ Full deployment guide ]

[ Who we are ]

Team

[ Development Progress ]

Roadmap

  • Completed
  • In Progress
  • Planned
  • Future

[ Backend / Core API ]

1

The current NestJS foundation: authentication, authorization, server lifecycle, Docker deployment, host metrics, and release automation.

  • JWT auth via HttpOnly cookies
  • Register & login endpoints
  • Token refresh & logout
  • Session management (list & revoke)
  • Password change and forced recovery
  • Rate limiting and security validation
  • Health and protocol-1 capability endpoints
  • Transactional first-admin bootstrap
  • Roles, account status, and MOD PBAC
  • 2FA — TOTP with backup codes
  • Admin user management and last-admin protection
  • Docker service and managed-container guardrails
  • Server lifecycle and graceful RCON stop
  • Resource admission and startup reconciliation
  • Server visibility and access request workflow
  • Requestable server discovery
  • Host metrics via WebSocket
  • Unit + PostgreSQL e2e tests
  • CI/CD pipeline + GHCR edge/stable release channels
  • Docker deployment (Compose + Caddy + boot migrations)

100% complete

2

Stable-v1 hardening is implemented and gated by unit, build, migration, e2e, and trusted real-Docker lifecycle checks. Its required seven-item scope is complete.

  • Stable API error envelope, machine codes, and request IDs
  • Resolve password semantics and bcrypt UTF-8 byte limits
  • Delete or wire dead login-throttle environment variables
  • Progressive login-abuse throttling using account + source context
  • Minecraft CPU quota and PIDs limit
  • Reproducible Minecraft image strategy
  • Trusted real-Docker lifecycle CI

100% complete (7/7 required items)

3

The required identity and onboarding scope is complete: Google authentication and linking, server visibility and access workflows, requestable discovery, and MOD granular permissions.

  • Google OAuth with challenge-bound local verification
  • Google account linking with explicit confirmation
  • Server visibility: OPEN / REQUEST / PRIVATE
  • Access request and approval workflow
  • Requestable server discovery
  • MOD granular permissions (PBAC per server)

100% complete

4

The next backend milestone: framework-neutral foundations required by core operations and later integrations.

  • Append-only audit log
  • Framework-neutral system-event model

Next planned milestone

5

The core Minecraft operations suite, built in dependency order on top of the stable backend and Phase 2A foundations.

  • RCON / console command broker (Docker-exec default)
  • Real-time server logs, stats, and player events
  • Backup and restore
  • Scheduler foundation when scheduled operations first require it
  • Scheduled tasks
  • Controlled filesystem-write architecture
  • File manager
  • Player management
  • Microsoft Minecraft account linking for player-management consumers
  • Offline player UUID linking with explicit offline-mode identity rules
  • Plugin and mod management
  • Notifications

Planned after Phase 2A

6

External consumers of the platform foundations. These remain secondary to the core Minecraft management path.

  • API keys
  • Outbound webhooks
  • External integrations
  • System-event consumers
7

Optional account-access features that may be added after the core management experience is established.

  • [Optional] GitHub OAuth
  • [Optional] Invitation and alternate registration modes
  • [Optional] Magic-link authentication when SMTP is deliberately enabled
8

Later product capabilities whose detailed architecture will be defined only when they become active development targets.

  • Creation presets and server wizard
  • Mod-loader and mod selection
  • Velocity networking
  • Geyser / Bedrock support
  • Mobile app and player portal
9

Post-feature-completion, parity-first migration from NestJS when the final feature baseline is frozen and Elysia 2 with its required Bun ecosystem is production-ready.

  • Complete and freeze the final NestJS feature baseline
  • Document deferred functionality and synchronize all docs
  • Establish stable API/error contracts
  • Establish black-box HTTP/WS conformance
  • Add trusted real-Docker lifecycle coverage
  • Verify Elysia 2 ecosystem reliability on the selected Bun runtime
  • Port with route, status, body, auth, cookie, DB, Docker, and WS parity
10

Post-Elysia, thin client-agnostic MCP server adapter over MinePanel's application/domain layer — never direct Docker, filesystem, or database access.

  • Shared contracts and schemas where appropriate
  • Scoped MCP auth, including per-server restrictions
  • Read / control / destructive permission separation
  • Server state, logs, metrics, players, backups, and node resources
  • Lifecycle and console operations through existing MinePanel authorization and orchestration
  • Structured diagnostics and higher-level tools (diagnose_server, safe_restart)
  • Audit attribution for agent-triggered mutations
  • Generic MCP clients — Hermes as an example integration

[ live data - last updated: 2026-09-09 ]