What Are Eggs in Pterodactyl and How Do They Work?

An Egg is Pterodactyl's portable recipe for a game server: it bundles the Docker image the server runs in, the startup command, and the configurable variables a user fills in when creating the server. You use one by installing it from the community library or writing your own, then the panel runs that game inside an isolated Docker container. This matters if you want to host multiple different games on one panel without hand-building each environment.

What an Egg actually contains

An Egg is a JSON definition. The panel reads it to know how to launch and configure a server. The core fields are:

• Docker image — the container the server runs in, so the runtime (Java, a game binary, etc.) is reproducible.
• Startup command — the exact command the panel executes to boot the server.
• Variables — configurable inputs like memory, jar file, or version, which the panel substitutes into the startup command.

Because the recipe is declarative, the same panel can run any game that has an Egg, without changing panel code.

The Paper Minecraft Egg, step by step

The site's example Egg shows how the pieces fit together:

{
  "name": "Paper Minecraft",
  "docker_image": "ghcr.io/pterodactyl/yolks:java_21",
  "startup": "java -Xmx{{SERVER_MEMORY}}M -jar {{JARFILE}}",
  "variables.SERVER_JARFILE": "server.jar",
  "variables.MINECRAFT_VERSION": "latest",
  "features": ["eula", "java_version", "pid_limit"]
}

Reading it:

1. Input — the Docker image ghcr.io/pterodactyl/yolks:java_21 provides a Java 21 runtime.
2. Action — the startup command launches Java with -Xmx{{SERVER_MEMORY}}M, where {{SERVER_MEMORY}} is filled from the server's allocated memory, and -jar {{JARFILE}} points at the jar named by the SERVER_JARFILE variable.
3. Expected result — the panel starts a Paper Minecraft server inside its own container, with memory and jar file controlled by the variables you set.

The features list (eula, java_version, pid_limit) tells the panel to apply those standard behaviors during setup.

Getting an Egg vs. writing your own

The panel lists many games that run this way, including Minecraft, Rust, ARK: Survival, Counter-Strike 2, Garry's Mod, Valheim, Terraria, Palworld, FiveM, Project Zomboid, Discord Bots, Teamspeak, SCP: SL, Factorio, and Satisfactory.

Why the container matters

Every server an Egg defines is sealed in its own Docker container with hard CPU, memory, and disk limits. The site's framing: one server can "throw the loudest party on the node, and the rest of the street sleeps through it." In practice this means a misbehaving or overloaded game server can't starve the others on the same machine.

Extending without forking

If you need to add behavior, Pterodactyl's Extensions SDK plugs into versioned panel APIs rather than core files. Extensions survive updates, and a broken one is skipped instead of taking the panel down. This is separate from Eggs — Eggs define how a game runs, extensions change panel behavior.

Practical notes before you start

• Pterodactyl is described as free, open-source, and MIT licensed, with no seats, no feature gates, and no monthly bill. That covers the panel software itself; it does not mean hosting, hardware, or bandwidth are free.
• In production since 2015, used by both small realms and large game hosts.
• Security features include bcrypt and 2FA at login, scoped tokens through Wings, and the locked-down Docker container.

To begin, install the panel, then either import an Egg from the community library or author your own JSON with the image, startup command, and variables your game needs.