Egg Creation

Eggs are the core configuration format for defining how servers are installed, started, and managed in Pterodactyl. This guide covers creating custom eggs from scratch.

What is an Egg?

An Egg is a JSON configuration file that defines:

Server installation process
Docker images to use
Startup commands and parameters
Environment variables
Configuration file parsing
Stop commands
Features and behavior

Egg Structure

Eggs use the export version PTDL_v2 format:

{
  "_comment": "Pterodactyl Egg Configuration",
  "meta": {
    "version": "PTDL_v2",
    "update_url": null
  },
  "exported_at": "2026-03-04T12:00:00+00:00",
  "name": "My Custom Server",
  "author": "[email protected]",
  "description": "Description of the server type",
  "features": null,
  "docker_images": {
    "Default": "ghcr.io/pterodactyl/yolks:debian"
  },
  "file_denylist": [],
  "startup": "./start.sh",
  "config": {
    "files": "{}",
    "startup": "{}",
    "logs": "{}",
    "stop": "^C"
  },
  "scripts": {
    "installation": {
      "script": "#!/bin/bash\n# Installation script",
      "container": "debian:12",
      "entrypoint": "bash"
    }
  },
  "variables": []
}

Core Fields

Basic Information

name (string, required): Display name for the egg

"name": "Minecraft Java Edition"

author (string, required): Email of the egg author

"author": "[email protected]"

description (string, optional): Description shown to users

"description": "Vanilla Minecraft server running on Java"

Docker Configuration

docker_images (object, required): Available Docker images for this egg

"docker_images": {
  "Java 8": "ghcr.io/pterodactyl/yolks:java_8",
  "Java 11": "ghcr.io/pterodactyl/yolks:java_11",
  "Java 17": "ghcr.io/pterodactyl/yolks:java_17",
  "Java 21": "ghcr.io/pterodactyl/yolks:java_21"
}

Users can select which image to use when creating servers. force_outgoing_ip (boolean, optional): Force servers to use their allocation IP for outgoing connections

"force_outgoing_ip": false

Startup Configuration

startup (string, required): Command to start the server

"startup": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}"

Supports variables:

{{VARIABLE_NAME}} - User-defined variables
{{SERVER_MEMORY}} - Allocated memory
{{SERVER_IP}} - Server IP
{{SERVER_PORT}} - Server port

File Deny List

file_denylist (array, optional): Files/directories that cannot be modified or deleted by users

"file_denylist": [
  "server.properties",
  "config/important.yml"
]

Features

features (array, optional): Special features to enable

"features": ["eula", "fastdl"]

Available features:

eula - Shows EULA acceptance popup (Minecraft)
fastdl - FastDL support (Source games)

Configuration Files

config.files

Defines how to parse and modify configuration files:

"config": {
  "files": {
    "server.properties": {
      "parser": "properties",
      "find": {
        "server-ip": "0.0.0.0",
        "server-port": "{{server.build.default.port}}",
        "max-players": "{{server.build.env.MAX_PLAYERS}}"
      }
    },
    "config.yml": {
      "parser": "yaml",
      "find": {
        "database.host": "{{config.docker.interface}}"
      }
    }
  }
}

Supported parsers:

properties - Java properties files
yaml - YAML configuration
file - Plain text replacement
json - JSON configuration
xml - XML configuration

config.startup

Defines how to detect server state from console output:

"config": {
  "startup": {
    "done": "Done (",
    "userInteraction": []
  }
}

done: String to detect when server has fully started

config.logs

Defines custom log parsing (optional):

"config": {
  "logs": {}
}

config.stop

Command to stop the server:

"config": {
  "stop": "stop"
}

Common values:

^C - Send SIGINT (Ctrl+C)
stop - Send “stop” command
end - Send “end” command
quit - Send “quit” command

Installation Script

The installation script runs in a separate container to set up the server:

"scripts": {
  "installation": {
    "script": "#!/bin/bash\n\n## Install script here\ncd /mnt/server\n\n# Download server files\ncurl -sSL https://example.com/server.jar -o server.jar\n\necho \"Installation complete\"",
    "container": "ghcr.io/pterodactyl/installers:debian",
    "entrypoint": "bash"
  }
}

Available Variables

Installation scripts have access to:

${STARTUP} - Startup command
${SERVER_MEMORY} - Allocated memory
${SERVER_IP} - Server IP
${SERVER_PORT} - Server port
All user-defined variables

Installation Container

Use appropriate container for installation:

ghcr.io/pterodactyl/installers:debian - Debian-based
ghcr.io/pterodactyl/installers:alpine - Alpine-based
node:18-alpine - For Node.js apps
Custom containers as needed

Best Practices

Always use absolute paths (/mnt/server)
Check for errors and exit with non-zero code on failure
Provide progress output for user feedback
Clean up temporary files after installation
Validate downloads with checksums when possible

Variables

Variables allow users to customize their servers:

"variables": [
  {
    "name": "Server Version",
    "description": "The version of the server to install",
    "env_variable": "SERVER_VERSION",
    "default_value": "latest",
    "user_viewable": true,
    "user_editable": true,
    "rules": "required|string|max:20",
    "field_type": "text"
  },
  {
    "name": "Max Players",
    "description": "Maximum number of players",
    "env_variable": "MAX_PLAYERS",
    "default_value": "20",
    "user_viewable": true,
    "user_editable": true,
    "rules": "required|integer|min:1|max:100",
    "field_type": "text"
  },
  {
    "name": "Enable PVP",
    "description": "Enable player vs player combat",
    "env_variable": "PVP",
    "default_value": "true",
    "user_viewable": true,
    "user_editable": true,
    "rules": "required|boolean",
    "field_type": "text"
  }
]

Variable Fields

name (string): Display name description (string): Help text for users env_variable (string): Environment variable name (uppercase, alphanumeric + underscore) default_value (string): Default value user_viewable (boolean): Can users see this variable? user_editable (boolean): Can users edit this variable? rules (string): Laravel validation rules Common validation rules:

required - Must have a value
string - Must be a string
integer - Must be an integer
boolean - Must be true/false
min:N - Minimum value/length
max:N - Maximum value/length
in:A,B,C - Must be one of the listed values
regex:/pattern/ - Must match regex pattern

field_type (string): UI field type (currently always “text”)

Example: Custom Game Server Egg

Here’s a complete example for a custom game server:

{
  "_comment": "Custom Game Server Egg",
  "meta": {
    "version": "PTDL_v2",
    "update_url": null
  },
  "exported_at": "2026-03-04T12:00:00+00:00",
  "name": "Custom Game Server",
  "author": "[email protected]",
  "description": "A custom game server implementation",
  "features": null,
  "docker_images": {
    "Default": "ghcr.io/pterodactyl/yolks:debian"
  },
  "file_denylist": [
    "config.ini"
  ],
  "startup": "./gameserver -port={{SERVER_PORT}} -maxplayers={{MAX_PLAYERS}}",
  "config": {
    "files": {
      "config.ini": {
        "parser": "ini",
        "find": {
          "server.port": "{{server.build.default.port}}",
          "server.maxplayers": "{{server.build.env.MAX_PLAYERS}}"
        }
      }
    },
    "startup": {
      "done": "Server started successfully"
    },
    "logs": {},
    "stop": "^C"
  },
  "scripts": {
    "installation": {
      "script": "#!/bin/bash\nset -e\n\ncd /mnt/server\n\n# Download server\necho \"Downloading server files...\"\ncurl -sSL https://example.com/gameserver-${VERSION}.tar.gz -o server.tar.gz\n\n# Extract\necho \"Extracting files...\"\ntar -xzf server.tar.gz\nrm server.tar.gz\n\n# Set permissions\nchmod +x gameserver\n\necho \"Installation complete!\"",
      "container": "ghcr.io/pterodactyl/installers:debian",
      "entrypoint": "bash"
    }
  },
  "variables": [
    {
      "name": "Server Version",
      "description": "Version of the game server to install",
      "env_variable": "VERSION",
      "default_value": "1.0.0",
      "user_viewable": true,
      "user_editable": true,
      "rules": "required|string|max:10",
      "field_type": "text"
    },
    {
      "name": "Max Players",
      "description": "Maximum number of concurrent players",
      "env_variable": "MAX_PLAYERS",
      "default_value": "32",
      "user_viewable": true,
      "user_editable": true,
      "rules": "required|integer|min:1|max:128",
      "field_type": "text"
    }
  ]
}

Importing Eggs

Via Admin Panel

Navigate to Nests in the admin area
Select the target nest
Click Import Egg
Upload your JSON file or paste the JSON
Click Import

Via Command Line

php artisan p:egg:import --json=/path/to/egg.json --nest=1

Exporting Eggs

Export existing eggs to use as templates:

php artisan p:egg:export --egg=1

Or export via the admin panel:

Navigate to the egg
Click Export
Save the JSON file

Testing Eggs

Create a test server using the egg
Verify installation completes successfully
Check startup works correctly
Test variables are applied properly
Verify stop command works
Test configuration parsing updates files correctly
Check file deny list prevents editing protected files

Troubleshooting

Installation Fails

Check installation script syntax
Verify download URLs are accessible
Ensure proper permissions on files
Check container has required tools

Server Won’t Start

Verify startup command is correct
Check all variables are defined
Ensure Docker image is appropriate
Review server console output

Configuration Not Updating

Verify parser type matches file format
Check file paths are correct
Ensure find/replace values are valid
Confirm variables exist

Best Practices

Use semantic versioning for egg updates
Document variables clearly
Provide sensible defaults for all variables
Test thoroughly before deploying
Use validation rules to prevent invalid input
Keep installation scripts simple and well-commented
Support multiple Docker images when applicable
Follow naming conventions for variables (UPPERCASE_WITH_UNDERSCORES)

Getting Started

Panel Administration

Server Management

User Guide

Configuration

Advanced

What is an Egg?

Egg Structure

Core Fields

Basic Information

Docker Configuration

Startup Configuration

File Deny List

Features

Configuration Files

config.files

config.startup

config.logs

config.stop

Installation Script

Available Variables

Installation Container

Best Practices

Variables

Variable Fields

Example: Custom Game Server Egg

Importing Eggs

Via Admin Panel

Via Command Line

Exporting Eggs

Testing Eggs

Troubleshooting

Installation Fails

Server Won’t Start

Configuration Not Updating

Best Practices

Build docs developers (and LLMs) love

Getting Started

Panel Administration

Server Management

User Guide

Configuration

Advanced

​What is an Egg?

​Egg Structure

​Core Fields

​Basic Information

​Docker Configuration

​Startup Configuration

​File Deny List

​Features

​Configuration Files

​config.files

​config.startup

​config.logs

​config.stop

​Installation Script

​Available Variables

​Installation Container

​Best Practices

​Variables

​Variable Fields

​Example: Custom Game Server Egg

​Importing Eggs

​Via Admin Panel

​Via Command Line

​Exporting Eggs

​Testing Eggs

​Troubleshooting

​Installation Fails

​Server Won’t Start

​Configuration Not Updating

​Best Practices

Build docs developers (and LLMs) love

What is an Egg?

Egg Structure

Core Fields

Basic Information

Docker Configuration

Startup Configuration

File Deny List

Features

Configuration Files

config.files

config.startup

config.logs

config.stop

Installation Script

Available Variables

Installation Container

Best Practices

Variables

Variable Fields

Example: Custom Game Server Egg

Importing Eggs

Via Admin Panel

Via Command Line

Exporting Eggs

Testing Eggs

Troubleshooting

Installation Fails

Server Won’t Start

Configuration Not Updating

Best Practices