Nests and Eggs - Pterodactyl Panel

Nests and Eggs are the core configuration system in Pterodactyl that define how different game servers are installed and run. Understanding this system is crucial for customizing and adding new game types.

Concept Overview

Nests

A Nest is a collection of related eggs, typically grouped by game type or server software:

Minecraft: All Minecraft-related servers
Source Engine: Valve Source games (CS:GO, TF2, Garry’s Mod)
Voice Servers: TeamSpeak, Discord bots
Generic: Generic applications and software

Eggs

An Egg is a specific server configuration within a nest:

Minecraft Nest → Vanilla, Paper, Forge, Spigot eggs
Source Engine Nest → CS:GO, TF2, L4D2 eggs

Eggs define:

Docker images to use
Installation scripts
Startup commands
Configuration files
Environment variables

Nest Structure

From app/Models/Nest.php:38-41:

protected $fillable = [
    'name',
    'description',
];

Nest Validation

From app/Models/Nest.php:43-47:

public static array $validationRules = [
    'author' => 'required|string|email',
    'name' => 'required|string|max:191',
    'description' => 'nullable|string',
];

Egg Structure

Eggs are complex configurations (from app/Models/Egg.php:90-108):

protected $fillable = [
    'name',
    'description',
    'features',             // Array of enabled features
    'docker_images',        // Available Docker images
    'force_outgoing_ip',    // Force container to use node IP
    'file_denylist',        // Files users cannot edit
    'config_files',         // Configuration file parsing rules
    'config_startup',       // Startup configuration
    'config_logs',          // Log file location
    'config_stop',          // Stop command
    'config_from',          // Inherit config from another egg
    'startup',              // Startup command template
    'script_is_privileged', // Run install script as privileged
    'script_install',       // Installation script
    'script_entry',         // Entrypoint script
    'script_container',     // Container for installation
    'copy_script_from',     // Copy scripts from another egg
];

Managing Nests

Creating a Nest

Navigate to Nests

Go to Admin Panel → Nests → Create New

Fill in Details

Nest Information

Name: Descriptive name (e.g., “Minecraft”, “Source Engine”)
Description: Optional description of the nest
Author: Email address of the creator

Create Nest

Click Create to save the nest

Viewing a Nest

Clicking on a nest shows:

All eggs in the nest
Number of servers using each egg
Ability to create new eggs
Import/export functionality

From app/Http/Controllers/Admin/Nests/NestController.php:69-74:

public function view(int $nest): View
{
    return view('admin.nests.view', [
        'nest' => $this->repository->getWithEggServers($nest),
    ]);
}

Deleting a Nest

You cannot delete a nest that has servers using any of its eggs. Delete or migrate all servers first.

Managing Eggs

Creating an Egg

Navigate to Nest

Click on the nest where you want to add an egg

Click Create New Egg

Select Create New Egg button

Basic Information

Egg Details

Name: Egg name (e.g., “Paper”, “Vanilla”)
Description: What this egg provides
Author: Your email address

Docker Configuration

Docker ImagesSpecify available Docker images (one per line):

ghcr.io/pterodactyl/yolks:java_17
Java 8|ghcr.io/pterodactyl/yolks:java_8
Java 11|ghcr.io/pterodactyl/yolks:java_11

Format: Display Name|image:tag or just image:tag

Startup Configuration

Startup CommandDefine the command to start the server:

java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}

Use {{VARIABLE}} for environment variables

Configuration Files

Config Parsing (JSON)Define how config files should be parsed:

{
    "server.properties": {
        "parser": "properties",
        "find": {
            "server-ip": "0.0.0.0",
            "server-port": "{{server.build.default.port}}"
        }
    }
}

Stop Configuration

Define the stop command:

stop

Or for graceful shutdown:

^C

Install Script

Installation Script (Bash)Create a script to install the server:

#!/bin/bash
cd /mnt/server

DOWNLOAD_URL=https://example.com/server.jar
curl -sSL ${DOWNLOAD_URL} -o server.jar

Environment Variables

Add variables users can configure (next section)

Create Egg

Click Create to save the egg

Docker Image Format

From app/Http/Controllers/Admin/Nests/EggController.php:114-127:

protected function normalizeDockerImages(?string $input = null): array
{
    $data = array_map(fn ($value) => trim($value), explode("\n", $input ?? ''));

    $images = [];
    foreach ($data as $value) {
        $parts = explode('|', $value, 2);
        $images[$parts[0]] = empty($parts[1]) ? $parts[0] : $parts[1];
    }

    return $images;
}

Egg Variables

Variables allow users to customize their servers. Each variable has:

Name: Display name
Description: Help text
Environment Variable: The {{VAR_NAME}} used in configs
Default Value: Pre-filled value
User Viewable: Can users see this variable?
User Editable: Can users change this variable?
Validation Rules: Laravel validation rules

Creating a Variable

Navigate to Egg Variables

Click on an egg, then go to Variables tab

Add New Variable

Click New Variable

Configure Variable

Variable Settings

Name: Server Version
Description: Which server version to install
Environment Variable: SERVER_VERSION
Default Value: latest
Validation Rules: required|string|max:20
User Viewable: Yes
User Editable: Yes

Save Variable

Click Create Variable

Variable Usage

Variables can be used in:

Startup Command: java -jar {{SERVER_JARFILE}}
Install Script: VERSION={{SERVER_VERSION}}
Config Files: Parsed and replaced automatically

Configuration Inheritance

Eggs can inherit configuration from other eggs:

Config Inheritance

Set config_from to another egg’s ID to inherit:

Configuration file parsing
Startup configuration
Log configuration
Stop command

From app/Models/Egg.php:197-204:

public function getInheritConfigFilesAttribute(): ?string
{
    if (!is_null($this->config_files) || is_null($this->config_from)) {
        return $this->config_files;
    }

    return $this->configFrom->config_files;
}

Script Inheritance

Set copy_script_from to copy installation scripts from another egg.

Inheritance is useful for creating variations of existing eggs without duplicating configuration.

Egg Features

Special features can be enabled (from app/Models/Egg.php:79-80):

public const FEATURE_EULA_POPUP = 'eula';
public const FEATURE_FASTDL = 'fastdl';

EULA Feature

For Minecraft servers:

{
    "features": ["eula"]
}

Shows a EULA acceptance popup during server creation.

FastDL Feature

For Source Engine servers:

{
    "features": ["fastdl"]
}

Enables FastDL configuration options.

File Denylist

Prevent users from editing sensitive files:

[
    "server.properties",
    "ops.json",
    "whitelist.json"
]

Users can view but not edit these files.

Importing Eggs

You can import eggs from JSON files:

Get Egg JSON

Download egg from:

Pterodactyl Eggs Repo
Export from another Panel
Create custom JSON

Navigate to Nest

Go to the nest where you want to import

Import Egg

Click Import Egg and upload the JSON file

Verify Configuration

Review the imported egg settings and adjust as needed

Exporting Eggs

To share eggs with others:

Navigate to Egg

Click on the egg you want to export

Export

Look for the export option

Save JSON

Download the JSON file

The export version is defined as (from app/Models/Egg.php:68):

public const EXPORT_VERSION = 'PTDL_v2';

Install Script Container

The installation script runs in a separate container:

script_container: Docker image for installation
script_entry: Entrypoint command (usually bash)
script_is_privileged: Run as privileged container

Common install containers:

ghcr.io/pterodactyl/installers:alpine
ghcr.io/pterodactyl/installers:debian

Configuration Parsers

Supported configuration file parsers:

properties: Java .properties files
file: Simple find/replace
yaml: YAML configuration
json: JSON configuration
ini: INI files

Best Practices

Use Inheritance: Don’t duplicate configurations
Validate Variables: Always add validation rules
Clear Descriptions: Help users understand variables
Test Thoroughly: Test eggs before deploying to production
Use Official Images: Prefer pterodactyl/yolks
Version Control: Keep egg JSON files in version control
Document Changes: Add update notes when modifying eggs

Common Eggs Repository

The community maintains eggs at: https://github.com/parkervcp/eggs This includes eggs for:

Minecraft (Vanilla, Paper, Forge, Fabric, Bedrock)
Source Engine (CS:GO, TF2, Garry’s Mod)
Voice Servers (TeamSpeak, Mumble)
Discord Bots
Game Servers (Rust, ARK, Valheim)
And many more

Troubleshooting

Install Failed

Problem: Server installation fails Solutions:

Check install script logs
Verify Docker image is accessible
Test install script locally
Check variable values are correct

Server Won’t Start

Problem: Server starts but immediately stops Solutions:

Check startup command syntax
Verify environment variables
Review server logs
Test Docker image manually

Config Not Updating

Problem: Configuration changes don’t apply Solutions:

Verify config_files JSON is valid
Check file paths are correct
Ensure parser is appropriate for file type
Test parsing rules

Next Steps

Server Creation

Deploy servers using your eggs

Mounts

Share files across servers with mounts

Getting Started

Panel Administration

Server Management

User Guide

Configuration

Advanced

​Concept Overview

​Nests

​Eggs

​Nest Structure

​Nest Validation

​Egg Structure

​Managing Nests

​Creating a Nest

​Viewing a Nest

​Deleting a Nest

​Managing Eggs

​Creating an Egg

​Docker Image Format

​Egg Variables

​Creating a Variable

​Variable Usage

​Configuration Inheritance

​Config Inheritance

​Script Inheritance

​Egg Features

​EULA Feature

​FastDL Feature

​File Denylist

​Importing Eggs

​Exporting Eggs

​Install Script Container

​Configuration Parsers

​Best Practices

​Common Eggs Repository

​Troubleshooting

​Install Failed

​Server Won’t Start

​Config Not Updating

​Next Steps

Server Creation

Mounts

Build docs developers (and LLMs) love

Concept Overview

Nests

Eggs

Nest Structure

Nest Validation

Egg Structure

Managing Nests

Creating a Nest

Viewing a Nest

Deleting a Nest

Managing Eggs

Creating an Egg

Docker Image Format

Egg Variables

Creating a Variable

Variable Usage

Configuration Inheritance

Config Inheritance

Script Inheritance

Egg Features

EULA Feature

FastDL Feature

File Denylist

Importing Eggs

Exporting Eggs

Install Script Container

Configuration Parsers

Best Practices

Common Eggs Repository

Troubleshooting

Install Failed

Server Won’t Start

Config Not Updating

Next Steps