Skip to Content
BytePanelBytePanel

Migrating from Pterodactyl

Move a Pterodactyl panel and its Wings nodes to BytePanel, keeping users, passwords and server files.

A migration has two parts:

  1. Panel: import the Pterodactyl database into BytePanel with migrate:pterodactyl.
  2. Nodes: on each node, replace Wings with the BytePanel agent using bytepanel-daemon import-wings.

Server files stay where they are and are never copied, so servers come back with their worlds, configs and backups. Plan a maintenance window: each node's servers are offline from when you stop them until the agent starts them again, usually a few minutes per node.

Before you start

  • A running BytePanel with its database migrated. See Installation.
  • BETTER_AUTH_SECRET and DATABASE_URL set in apps/web/.env, with the same BETTER_AUTH_SECRET as the running panel. The import uses it to encrypt the new node tokens.
  • Bun 1.3.13 or newer on the machine running the import, with a checkout of the BytePanel repository and bun install done.
  • Access to the Pterodactyl database, either directly or as a dump.
  • Root SSH access to every node.
  • A fresh backup of the Pterodactyl database and of /etc/pterodactyl on each node.

Part 1: import the panel

Choose a source

The importer reads the live Pterodactyl database:

--source mysql://pterodactyl:[email protected]:3306/panel

Or a dump file (.sql or .sql.gz), which helps when BytePanel can't reach MySQL:

mysqldump -u pterodactyl -p panel > panel.sql

To keep the dump small, add --ignore-table=panel.activity_logs --ignore-table=panel.activity_log_subjects. Dumps need their table structure, which is the default. If your tables use a prefix (DB_PREFIX in Pterodactyl's .env), pass it with --prefix.

Do a dry run

From apps/web:

bun run migrate:pterodactyl --source panel.sql --dry-run

A dry run does the whole import and then rolls it back. It prints how many of each thing it would import, any egg features BytePanel can't represent, and the tables it skips.

Run the import

bun run migrate:pterodactyl --source panel.sql

The import runs in one transaction, so it either fully succeeds or changes nothing. It's safe to run again, for example with a newer dump: existing rows are matched by email, UUID, location code, nest name or egg name and updated.

What's imported

PterodactylBytePanelNotes
UsersUsersPasswords carry over. Root admins become admins.
Locations, nodes, allocationsLocations, nodes, allocationsNodes get new agent tokens.
Nests, eggs, egg variablesNests, eggs, egg variablesEggs that copy config or scripts from another egg are resolved.
Servers, server variablesServers, server variablesUUIDs are kept, so files on the node line up. Extra allocations are kept.
BackupsBackupsThe archives move in part 2.
SubusersServer membersRead-only permissions become viewer, user management becomes admin, everything else member.

What isn't

Pterodactyl dataWhy
Two-factor (TOTP) secretsBytePanel uses passkeys instead.
API keys, SSH keys, recovery tokensDifferent formats. Users recreate them.
Database hosts and databasesBytePanel doesn't manage databases yet. The databases themselves are untouched.
SchedulesBytePanel doesn't have schedules yet.
MountsRecreate them as extraMounts on the eggs that need them.
Activity, audit and API logsHistory only.
Sessions, settings and other runtime dataSet up panel settings again in Admin → Settings.

Egg config-file rules that BytePanel can't express, such as conditional values or the XML parser, are dropped with a warning. Check those eggs afterwards.

Part 2: switch each node

Do one node at a time. Nothing on the node is deleted, so you can roll back at any point.

Stop the node's servers

Stop every server on the node from Pterodactyl while Wings is still running, so each one shuts down cleanly.

Install and configure the agent

Install the agent, then run the configure command from the node's page in BytePanel. Don't start the agent yet, because Wings still holds ports 8080 and 2022.

Import the Wings setup

bytepanel-daemon import-wings --dry-run
bytepanel-daemon import-wings

This reads /etc/pterodactyl/config.yml, then:

  • stops and disables Wings,
  • removes Wings' containers and its Docker network,
  • moves backup archives into the agent's backup folder,
  • reuses Wings' SFTP host key, so SFTP clients don't warn about a changed key,
  • keeps Wings' data folder, file owner, timezone, DNS servers and certificate paths.

Start the agent

systemctl enable --now bytepanel-daemon
journalctl -u bytepanel-daemon -f

Start one server from BytePanel and check its console, files, SFTP and a backup restore. Then start the rest.

FlagDefaultUse
--dry-runoffPrint the plan without changing anything.
--stop-runningoffStop servers that are still running instead of refusing.
--forceoffContinue even if the Wings config belongs to a different node.
--wings-config/etc/pterodactyl/config.ymlPath to the Wings config.
--wings-servicewingsName of the Wings service.
--config/etc/bytepanel/daemon.jsonPath to the agent config.

Running configure again later resets the imported settings, including the file owner, which breaks permissions on migrated servers. If you run configure again, run import-wings straight after it.

Once the node has run well for a while, remove Wings:

rm /usr/local/bin/wings /etc/systemd/system/wings.service
rm -rf /etc/pterodactyl /var/lib/pterodactyl/archives /var/lib/pterodactyl/.sftp

Leave /var/lib/pterodactyl/volumes alone: your server files are still there.

Signing in afterwards

  • With BytePay billing: customers sign in with BytePay, which links to their imported account by email. Staff sign in with their password or a passkey.
  • With any other billing option: everyone signs in with their Pterodactyl email and password.

Imported admins become admins, not super admins. Promote the accounts that need it. SFTP uses a separate password in BytePanel, which each user sets in their account settings.

Rolling back a node

Until you remove Wings, you can bring it back:

systemctl disable --now bytepanel-daemon
docker ps -a --filter label=bytepanel.server -q | xargs -r docker rm -f
systemctl enable --now wings

Move backup archives from /var/lib/bytepanel/backups back to /var/lib/pterodactyl/backups if Wings needs them. The Pterodactyl panel and database aren't changed by the import.

Troubleshooting

ProblemFix
Table ... is not in the dump (wrong --prefix?)Pass --prefix, or dump the whole database.
INSERT into ... has no column listRe-dump with table structure, or with --complete-insert.
Wings is node ... but the agent is configured for node ...Use the configure command from this node's page.
server(s) are still running under WingsStop them from Pterodactyl, or pass --stop-running.
Servers fail with permission errorsCheck system.user in /etc/bytepanel/daemon.json against id pterodactyl, or run import-wings again.
Servers have no filesCheck the node's system.data points at the Wings volumes.
Timestamps are a few hours offDates are read as UTC. If Pterodactyl's APP_TIMEZONE wasn't UTC, created and backup dates shift by that much.
Edit on GitHub

On this page