How it works

CraftPanel consists of two processes that share one data directory.

 Browser ──HTTP/WebSocket──▶ Dashboard (API + web UI)
                                  │
                     local socket / named pipe, authenticated
                                  │
                                  ▼
                            Runtime service ──▶ Java ──▶ Minecraft servers

Dashboard

The dashboard serves the web interface and the API: accounts, permissions, server configuration, downloads, backups, schedules, notifications and updates. It stores its state in a SQLite database in the data directory and applies database migrations on start.

Runtime

The runtime owns the Minecraft processes. It starts and stops servers, forwards console input and output, keeps a bounded console history and collects metrics.

The dashboard talks to it over a private Unix socket (Linux, macOS) or a Windows named pipe, authenticated with a random token only the two can read. Because the runtime is a separate service:

• Restarting, updating or even crashing the dashboard doesn’t stop your games. Players stay connected.
• When the dashboard comes back, it reconnects to the actual state of every server and replays the console it missed.
• Commands are never replayed blindly. If the dashboard can’t tell whether a command arrived, it reports that instead of sending it twice.

On a host shutdown, the runtime saves and stops every server gracefully. At boot it starts the servers with Start with CraftPanel enabled.

Every server under its own account (Linux)

On a Linux service install, each Minecraft server runs under its own system account (craftpanel-game-00, craftpanel-game-01, …). A plugin or mod therefore can’t read CraftPanel’s database (passwords, sessions, API keys), its runtime token, your backups or the files of your other servers, and anything it starts in the background is stopped together with its server. You don’t need to do anything: the installer creates 32 accounts, and each server keeps the one it got on its first start.

• Need more than 32 servers? Run the installer again with CRAFTPANEL_GAME_ACCOUNTS=64 (or more).
• A server directory outside /var/lib/craftpanel needs execute permission for others on every parent folder (chmod o+x); the start message says which folder is missing it.
• To turn it off, add CRAFTPANEL_ISOLATION=off to /etc/craftpanel/craftpanel.env and restart craftpanel-runtime.

On Windows, macOS and when you run CraftPanel by hand, servers still run under CraftPanel’s own account.

Resource limits

Under Performance → Resource limits each server has a memory cap, a CPU limit and a limit on processes and threads, enforced by the system (Linux service installs and Windows):

• Memory cap (Automatic by default): the server’s memory plus at least 1 GB for Java itself. If the server goes beyond it, it is stopped and shows as crashed with “Memory limit reached”. On Linux the cap never spills into swap, which would only make the game crawl. On Windows, Java can also keep running but slow down; the console says when the server reached its cap.
• CPU (Unlimited by default): at most this many cores. Minecraft’s main thread needs a whole core; much less makes it lag.
• Processes and threads (4,096 by default): enough for large modpacks, and it stops a plugin that starts processes without end. Windows counts processes only.

Changes apply to a running server at once. On a Raspberry Pi whose kernel has no memory controller, add cgroup_enable=memory to /boot/firmware/cmdline.txt and reboot; the card tells you when this is the case. CRAFTPANEL_LIMITS=off in /etc/craftpanel/craftpanel.env (Linux) or config.env in the install folder (Windows) turns limits off. On Windows, CraftPanel builds a small helper for this with the C# compiler that is part of Windows the first time a limited server starts.

Data directory

Everything CraftPanel manages lives in one folder:

Path	Contents
craftpanel.db	Accounts, settings, servers, schedules, activity
servers/	One folder per Minecraft server
backups/	Server backups (unless you set another destination)
runtimes/	Downloaded Java versions
runtime/	The runtime’s registry and private token
logs/	CraftPanel logs (Windows)

Technology

A pnpm monorepo in TypeScript: a Fastify API, a Next.js dashboard exported as static files, SQLite through Node’s built-in node:sqlite with Drizzle, and no native add-ons, so one release archive runs on every OS and CPU. Details for contributors are in docs/architecture on GitHub.