How to Create Custom Pterodactyl Eggs for Any Game or Application

Published on | Updated

Pterodactyl Panel 1.15.2 ships 14 default Eggs; most apps need a custom one. This guide covers the egg JSON, Docker images, variables and install scripts.

A data center aisle with server racks on both sides and a technician holding a tablet

Pterodactyl manages game servers through configuration files called Eggs. Each Egg defines what the panel and Wings need to run one application: which Docker image to use, how to install and start the software, which config files to adjust before each start, how to tell that the server has finished starting, and which variables users can change in the web interface.

Panel 1.15.2, the current stable release, seeds 14 default Eggs in four Nests: Minecraft (Paper, Vanilla Minecraft, Forge Minecraft, Bungeecord and Sponge), Source Engine (Ark: Survival Evolved, Counter-Strike: Global Offensive, Garrys Mod, Insurgency, Team Fortress 2 and a Custom Source Engine Game egg), Voice Servers (Mumble and Teamspeak3) and Rust. Counter-Strike 2 is not among them. The moment you want to host something not on that list, or a fork that behaves differently from the standard version, you need an Egg from elsewhere or your own.

Leave the default Eggs as they are: the Pterodactyl docs warn that a panel update may override changes to them. To start from one, export it and import the copy into a Nest of your own.

This guide explains the full structure and walks through creating a working custom Egg from scratch.


Getting a Feel for the Format

Eggs are JSON files. Export any existing Egg from your panel to see the structure:

Go to Admin > Nests > Select a nest > Select an egg > Export.

Open the downloaded JSON in a text editor. You will see these top-level keys:

{
    "_comment": "...",
    "meta": { "version": "PTDL_v2", "update_url": null },
    "exported_at": "...",
    "name": "My Custom App",
    "author": "admin@example.com",
    "description": "...",
    "features": null,
    "docker_images": { ... },
    "file_denylist": [],
    "startup": "...",
    "config": { ... },
    "scripts": { ... },
    "variables": [ ... ]
}

The panel exports PTDL_v2 and imports both PTDL_v1 and PTDL_v2 files. features switches on panel helpers: the official Paper egg lists eula, java_version and pid_limit there, and null is fine for your own app.


The Docker Image

The docker_images key specifies which container image to run the application in. Each key is the display name shown in the panel and each value is the full image reference. These are the first three entries of the official Paper egg:

"docker_images": {
    "Java 25": "ghcr.io/pterodactyl/yolks:java_25",
    "Java 21": "ghcr.io/pterodactyl/yolks:java_21",
    "Java 17": "ghcr.io/pterodactyl/yolks:java_17"
}

In the panel's Docker Images field you enter the same pairs one per line, as Java 21|ghcr.io/pterodactyl/yolks:java_21.

Pterodactyl's Yolks repository is "a curated collection of core images" for eggs, with runtimes such as Java, Node.js, Python and Go, published as ghcr.io/pterodactyl/yolks:<tag>. Use these when the runtime matches your application, and check that the tag exists first: on 31 October 2026 the newest Node.js image was nodejs_20, and the registry had no nodejs_22 tag.

If you need something custom, you point to any accessible Docker image:

"docker_images": {
    "Custom App": "docker.io/username/my-app-image:latest"
}

The Pterodactyl docs ask for a user named container with the home directory /home/container in every image, and for WORKDIR /home/container. For a private registry, add its login under docker.registries in /etc/pterodactyl/config.yml on each node, then restart Wings:

docker:
  registries:
    registry.example.com:
      username: "registryusername"
      password: "registrypassword"

The Startup Command

The startup key is the command that runs when a user presses the Start button. You reference variables using double curly braces. This is the startup command of the official Paper egg:

"startup": "java -Xms128M -XX:MaxRAMPercentage=95.0 -Dterminal.jline=false -Dterminal.ansi=true -jar {{SERVER_JARFILE}}"

{{SERVER_JARFILE}} is a variable you define yourself in the variables array. Wings also hands every server a set of default variables, such as SERVER_MEMORY (the memory limit in megabytes), SERVER_IP and SERVER_PORT, so {{SERVER_MEMORY}} works without a definition. The panel refuses those names for your own variables.

Wings runs the container with the user and group ID of its own system user (pterodactyl by default), not as root, and mounts the server's files at /home/container. The Yolks images work from that folder, and their entrypoint swaps each {{VARIABLE}} for the matching environment variable before it runs the command.


Defining User Variables

Variables give end-users control over startup parameters through the panel's web interface, without them needing to edit configuration files or touch the console.

"variables": [
    {
        "name": "Server Jar File",
        "description": "The name of the jar file to launch the server with.",
        "env_variable": "SERVER_JARFILE",
        "default_value": "server.jar",
        "user_viewable": true,
        "user_editable": true,
        "rules": "required|string|max:20",
        "field_type": "text"
    },
    {
        "name": "Server Version",
        "description": "The version to download and install.",
        "env_variable": "MC_VERSION",
        "default_value": "latest",
        "user_viewable": true,
        "user_editable": true,
        "rules": "required|string|max:20",
        "field_type": "text"
    }
]

Key fields:

  • env_variable: the environment variable name. Write it as {{MC_VERSION}} in the startup command, as $MC_VERSION or ${MC_VERSION} in the install script, and as {{env.MC_VERSION}} in config file entries. The docs ask for uppercase letters, numbers and underscores.
  • user_viewable: whether the user sees the variable and its value in their server's settings (Users Can View in the panel)
  • user_editable: whether they can change it (Users Can Edit)
  • rules: Laravel validation rules. The panel suggests required|string|max:20 for a new variable; required|integer|min:1|max:65535 suits a port number
  • field_type: Panel 1.15.2 writes text for every variable when it exports an egg, and its variable form has no field type setting. There is no password type: turning off user_viewable hides a value in the panel, but the Pterodactyl docs warn that it is not truly secret, because it sits in the server's environment.

The Install Script

The scripts.installation section defines a script that runs when the server is created and again on every reinstall. Use it to download the application, run initial setup, or write default files.

"scripts": {
    "installation": {
        "script": "#!/bin/bash\nmkdir -p /mnt/server\ncd /mnt/server || exit 1\ncurl -fLo server.jar.new \"https://example.com/download/${MC_VERSION}/server.jar\" && mv server.jar.new server.jar",
        "container": "ghcr.io/pterodactyl/installers:debian",
        "entrypoint": "bash"
    }
}

Wings runs the script in a separate installer container, with the entrypoint you set (bash here) and the server's files mounted at /mnt/server. It writes the script to disk as it is, apart from turning Windows line endings into Unix ones, so a {{MC_VERSION}} in it stays literal text: variables reach the script only as environment variables, written $MC_VERSION or ${MC_VERSION}. Start with cd /mnt/server, as the official eggs do, because Wings sets no working directory for the installer and only what lands in /mnt/server stays with the server. The ghcr.io/pterodactyl/installers:debian image already contains curl, wget and git, so the script needs no apt-get install for them.

Packages you install in the script stay in the installer container. The server's own Docker image has to contain everything the server needs at runtime.

Write install scripts defensively. Check if files already exist before downloading them. A reinstall should not corrupt an existing server: in the example, curl -f fails on an HTTP error, and the old server.jar is only replaced after a complete download.


Config Files, Startup Detection and Stop

The config section tells Wings how to handle the running server: which config files to change before each start, which console line means the server has started, and how to stop it. In the exported file, files, startup and logs are JSON written as a string, as in this shortened copy of the Paper egg:

"config": {
    "files": "{\"server.properties\": {\"parser\": \"properties\", \"find\": {\"server-ip\": \"0.0.0.0\", \"server-port\": \"{{server.build.default.port}}\"}}}",
    "startup": "{\"done\": \")! For help, type \"}",
    "logs": "{}",
    "stop": "stop"
}

The panel validates each of those three as a JSON string, so keep them as strings when you write an egg by hand. On the egg's page in the admin area, the same values sit in the Configuration Files, Start Configuration and Log Configuration fields, where you edit them as plain JSON.

  • files: before each start, Wings sets the keys under find in that file, and creates the file if it is missing. {{server.build.default.port}} becomes the server's main port and {{env.MAX_PLAYERS}} the value of a variable. The parsers are properties, ini, yaml, json, xml and file.
  • startup.done: Wings watches the console for this text and marks the server as running once it appears. It matches the text anywhere in a line, or a regular expression when the value starts with regex:, and it fills in no placeholders. That is why the Paper egg uses )! For help, type , the part of Minecraft's start-up line that stays the same, instead of the start-up time that changes every boot.
  • stop: the console command Wings sends when someone presses Stop. The official Minecraft eggs use stop (the Bungeecord egg uses end), and the Rust and Garrys Mod eggs use quit. To send a signal instead, start the value with ^: the panel's help text gives ^C for SIGINT, which the Mumble egg uses, and Wings also accepts ^SIGTERM, ^SIGABRT and ^SIGKILL.
  • logs: leave it as {}, as 13 of the 14 default eggs do (the Teamspeak3 egg names a log file). The Pterodactyl docs say you can leave Log Configuration empty in most cases.

Importing the Egg Into Your Panel

Save your finished JSON as egg-myapp.json. In the Pterodactyl admin panel:

  1. Go to Admin > Nests
  2. Create a new Nest with Create New, or use an existing one; the Nest has to exist before you import
  3. Click Import Egg, pick your file under Egg File and the Nest under Associated Nest, then click Import

You can also build the egg in the panel instead: open the Nest, click New Egg, and fill in the Variables and Install Script tabs after you save it.

After importing, create an Allocation and then a Server using the new Egg to test it. Watch the Wings log during installation and first startup to catch any script errors; Wings also saves each install's output to /var/log/pterodactyl/install/<server uuid>.log on the node.


Testing and Iteration

Egg development is iterative. Errors appear in the Wings log and in the install log on the node.

Common issues:

  • Install script fails to download files: check that the URL resolves from inside a Docker container. Some download links require specific user agents or headers.
  • Server stays on "Installing": Wings waits for the install container to stop before it reports the result to the panel, so an install script that never exits keeps the server there. Our guide to servers stuck on installing shows how to find the install container and read its log.
  • Server does not show as "Running": your startup.done string does not match the actual output. Run the server manually, look at the exact startup message, and leave out anything that changes per boot, such as a timing.
  • Variables not substituting: check the variable name in the variables array matches exactly what you use in {{DOUBLE_BRACES}}. Case matters. In the install script, use ${NAME} instead of double braces.

The community maintains a large collection of pre-built Eggs in the pelican-eggs organization on GitHub (github.com/pelican-eggs), split into repositories such as minecraft and games-steamcmd; the older pelican-eggs/eggs repository is archived. Pterodactyl also lists eggs at eggs.pterodactyl.io, including a Counter-Strike 2 egg, with the import steps for Panel 1.x. Check there before writing from scratch; someone has likely already created an Egg for your target application.

Sources

All opened on 31 October 2026: