Getting started

Deploy Multi Minecraft
in three variables.

Import one egg file, create a server, set SERVER_TYPE and MINECRAFT_VERSION, and the launcher handles Java, flags, configs and installs on boot.

Import the egg

Download egg-minecraft-multi.json and import it into your panel:

Pterodactyl / Jexactyl: Admin → Nests → select or create a Minecraft nest → Import Egg.
Pelican: Admin → Eggs → Upload Egg.
Feather / Wisp / plain Docker: fully compatible with Wings and Pterodactyl v2 egg specifications; use image ghcr.io/potenfyr-studios/minecraft-eggs:latest.

The egg is format PTDL_v2 and self-updates by default, so after the first import you rarely need to re-upload it (see Egg self-update).

Create the server

Nest Minecraft, egg Multi Minecraft, then pick resources:

Setting	Minimum	Recommended
Memory	2048 MB	4096 MB+ for Paper / Purpur, 6144 MB+ for modpacks
Port (Java engines)	Allocate `25565` (or any free port; the egg patches configs to match)
Port (Bedrock engines)	Allocate `19132` UDP for `bedrock`, `nukkit`, `pocketmine`
Docker image	`ghcr.io/potenfyr-studios/minecraft-eggs:latest`

Set the core variables

Two variables drive almost every install. The full reference of all 34 variables lives in the Egg Catalog.

SERVER_TYPE       paper      # engine (see Server Types page)
MINECRAFT_VERSION 1.21.4     # or latest / latest-snapshot
BUILD_NUMBER      latest     # optional pin (Paper, Purpur, Folia, Velocity…)

If a value is missing or invalid the egg never fails silently: an interactive console wizard appears in the panel log, offers the valid choices (120 s timeout) and saves the answer to .multi-mc.conf. Panel variables always take priority over saved wizard answers.

Panel features & EULA

The egg declares three panel features: eula, java_version and pid_limit. Accept the Minecraft EULA when the panel prompts. On fresh or missing files the launcher self-heals by triggering the installer automatically, so you usually never need to press Reinstall by hand.

Java & memory guidance

The container pairs each Minecraft release with the JVM it needs and provisions missing runtimes on demand (no Docker rebuild). Leave JAVA_VERSION empty for auto-selection, or override it with 8, 11, 17, 21, 25 or 26. The default JAVA_FLAGS are Aikar's tuned G1GC set; for 8 GB+ nodes clear them and set GC_TYPE=zgc.

Memory sizing: SERVER_MEMORY drives the heap: 2048 MB is the floor, 4096 MB+ suits Paper/Purpur, 6144 MB+ suits modpacks. AlwaysPreTouch and safe-heap calculation are applied automatically.

Reinstalls & safe switching

AUTO_UPDATE=1 (default) refreshes the selected software on reinstall; 0 skips installation when files already exist.
KEEP_BACKUP=1 keeps the previous jar as <name>.old when updating.
Changing engine or jumping major Minecraft lines never deletes data: the previous install is moved to archive/<type>-<version>-<timestamp>/ and the new engine installs clean. Same-line updates (1.21.1 → 1.21.4) refresh in place, touching nothing.

Stop behavior

Wings and Feather-style daemons often deliver stop as console text instead of an OS signal: the built-in panel stop watcher (PANEL_STOP_WATCHER=auto) intercepts stop, end and ^C, forwards all other lines to the server, translates stop → end for Velocity/BungeeCord, and force-sweeps hung processes after the grace window. SIGTERM/SIGINT traps let the JVM save world chunks before exit.

Troubleshooting

DEBUG=1: installer runs with bash -x and prints a resolved-environment dump at start.
SHOW_VERSIONS=1 + Reinstall: prints every upstream version available for the selected engine without changing files.
Delete .multi-mc.conf to reset saved wizard answers.
Still stuck? Bring the console log to the support Discord.

Egg Catalog