How to Create a Custom Pterodactyl Egg

What Is a Pterodactyl Egg?

An egg is a JSON blueprint that tells Pterodactyl how to install and run a specific type of server. The default nest ships with eggs for Minecraft, Rust, and other popular games, but you can create a custom Pterodactyl egg whenever you need to host software that is not included out of the box. Each egg defines a Docker image, an install script, startup command, and configuration variables.

Egg Structure Overview

A custom Pterodactyl egg JSON file contains several top-level keys:

• meta: version info and export date
• name / description: what appears in the panel UI
• docker_image: the container image Wings pulls
• startup: the command template, e.g. java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar server.jar
• config: stop command, log path, and file parser rules
• scripts > installation: the Bash script that runs inside a temporary container to download and prepare files
• variables: user-editable fields like version, build flags, or extra JVM args

Step 1: Create the Nest

Go to Admin > Nests and create a new nest if none fits your use case. Nests are just folders for organizing eggs.

Step 2: Create the Egg in the Panel

Inside the nest, click Create New Egg. Fill in the name, description, and Docker image. For a Node.js app, you might use ghcr.io/parkervcp/yolks:nodejs_18.

Step 3: Write the Install Script

The install script runs once when a server is created. It typically downloads files and sets permissions. Here is a minimal example:

#!/bin/bash
cd /mnt/server
curl -Lo app.tar.gz https://example.com/releases/latest.tar.gz
tar -xzf app.tar.gz
rm app.tar.gz

Pick an appropriate container for the install phase. Most eggs use ghcr.io/parkervcp/installers:alpine.

Step 4: Define Variables

Variables let server owners customize their instance without editing files. For example, you could add a NODE_ENV variable with a default of production. Each variable has a name, description, environment variable key, default value, and validation regex.

Step 5: Export and Share

Once your custom Pterodactyl egg works, export it as JSON from Admin > Nests > Egg > Export. You can import this JSON on any other panel or share it with the community.

Tips for Reliable Eggs

• Pin your Docker image tags instead of using :latest so builds are reproducible.
• Validate user variables with regex to prevent broken startup commands.
• Include a proper stop command so Pterodactyl can gracefully shut down the process.
• Test the install script on a fresh server to catch missing dependencies.

Building a custom Pterodactyl egg is the best way to extend your panel beyond the default game list. Pair it with resource limits to control how much CPU and RAM each instance can consume.

See a professionally hosted server: Astroworld MC, IP play.astroworldmc.com, Java + Bedrock.