Importing Pterodactyl Eggs

Catalyst can import Pterodactyl eggs as templates, so a library built for Pterodactyl does not have to be rebuilt from scratch. Imports live on the templates page (Admin → Templates), not in the migration center — that page imports whole servers. Both JSON (Pterodactyl) and YAML (Pelican) eggs work.

Prerequisites

• The template.create permission, or full administrator access.
• For From URL, outbound access from the backend to the egg’s host.
• For Import All Pterodactyl Eggs, outbound access from the backend to GitHub.

Import one egg

1. Open Admin → Templates.
2. Select Import.
3. Choose From URL and paste a direct link to the egg file, or From Local File and pick a .json, .yaml, or .yml file.
4. The panel converts the egg and opens the New template form pre-filled. Review the name, nest, runtime images, startup command, variables, ports, and install script.
5. Select Create template.

Selecting several files at once on the local-file route skips the review step and creates each template directly — a single file opens the editable form.

Import the whole Pterodactyl library

1. Open Admin → Templates and select Import.
2. Under Import All Pterodactyl Eggs, select Import All (the button shows how many eggs it will fetch). The panel warns this may take 1–2 minutes while it fetches the eggs from GitHub.
3. The result reports how many templates were imported, skipped (already exist), and failed. Expand Error details to see which eggs failed and why.
4. Nests are created automatically from the egg categories in the repository, so the imported library arrives pre-grouped.

Organize the imported templates

Nests are the template categories, and the batch import creates them from the repository’s egg folders. Add, rename, or delete nests under Manage nests on the Templates page (templates).

What to check by hand

• Ports: the template’s primary port is derived from the egg — an explicit ports array, a literal port in the egg’s own config-file bindings, or a variable pinned to one value by its rules — instead of assuming 25565. Eggs that bind {{server.build.default.port}} pin nothing, because the panel allocates the real port per server; those templates fall back to 25565 as a placeholder, so correct the Ports field before publishing.
• Variables: names, defaults, and validation rules sometimes need renaming to match Catalyst conventions.
• Images: confirm the container image exists and is maintained; repoint to your own registry mirror if you run one.
• Install scripts: read them. Imported scripts run as part of installation with significant privilege — never import eggs from sources you do not trust.
• Paths: document root and config paths occasionally differ; a quick install test exposes this immediately.

Caution

Imported install scripts execute code from the egg author. Review every script before publishing its template to users — this is a supply-chain boundary. See security.

Automation

The batch button calls POST /api/templates/import-pterodactyl-batch; a single egg can be posted as JSON to POST /api/templates/import-pterodactyl. Both require the template.create permission and return structured validation errors (422) for eggs that cannot be converted. Full-panel migrations import nests and templates on their own — see migration.

Related

• Creating and maintaining templates: templates.
• Moving whole servers: migration.
• Why imported install scripts need review: security.