Migrating from Pterodactyl
Move a Pterodactyl panel and its Wings nodes to BytePanel, keeping users, passwords and server files.
A migration has two parts:
- Panel: import the Pterodactyl database into BytePanel with
migrate:pterodactyl. - 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_SECRETandDATABASE_URLset inapps/web/.env, with the sameBETTER_AUTH_SECRETas 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 installdone. - 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/pterodactylon each node.
Part 1: import the panel
Choose a source
The importer reads the live Pterodactyl database:
--source mysql://pterodactyl:[email protected]:3306/panelOr a dump file (.sql or .sql.gz), which helps when BytePanel can't reach MySQL:
mysqldump -u pterodactyl -p panel > panel.sqlTo 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-runA 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.sqlThe 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
| Pterodactyl | BytePanel | Notes |
|---|---|---|
| Users | Users | Passwords carry over. Root admins become admins. |
| Locations, nodes, allocations | Locations, nodes, allocations | Nodes get new agent tokens. |
| Nests, eggs, egg variables | Nests, eggs, egg variables | Eggs that copy config or scripts from another egg are resolved. |
| Servers, server variables | Servers, server variables | UUIDs are kept, so files on the node line up. Extra allocations are kept. |
| Backups | Backups | The archives move in part 2. |
| Subusers | Server members | Read-only permissions become viewer, user management becomes admin, everything else member. |
What isn't
| Pterodactyl data | Why |
|---|---|
| Two-factor (TOTP) secrets | BytePanel uses passkeys instead. |
| API keys, SSH keys, recovery tokens | Different formats. Users recreate them. |
| Database hosts and databases | BytePanel doesn't manage databases yet. The databases themselves are untouched. |
| Schedules | BytePanel doesn't have schedules yet. |
| Mounts | Recreate them as extraMounts on the eggs that need them. |
| Activity, audit and API logs | History only. |
| Sessions, settings and other runtime data | Set 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-wingsThis 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 -fStart one server from BytePanel and check its console, files, SFTP and a backup restore. Then start the rest.
| Flag | Default | Use |
|---|---|---|
--dry-run | off | Print the plan without changing anything. |
--stop-running | off | Stop servers that are still running instead of refusing. |
--force | off | Continue even if the Wings config belongs to a different node. |
--wings-config | /etc/pterodactyl/config.yml | Path to the Wings config. |
--wings-service | wings | Name of the Wings service. |
--config | /etc/bytepanel/daemon.json | Path 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/.sftpLeave /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 wingsMove 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
| Problem | Fix |
|---|---|
Table ... is not in the dump (wrong --prefix?) | Pass --prefix, or dump the whole database. |
INSERT into ... has no column list | Re-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 Wings | Stop them from Pterodactyl, or pass --stop-running. |
| Servers fail with permission errors | Check system.user in /etc/bytepanel/daemon.json against id pterodactyl, or run import-wings again. |
| Servers have no files | Check the node's system.data points at the Wings volumes. |
| Timestamps are a few hours off | Dates are read as UTC. If Pterodactyl's APP_TIMEZONE wasn't UTC, created and backup dates shift by that much. |