Hytale Server Backup and Migration Guide
Back up, restore, and move Hytale worlds, configuration, permissions, mods, and authentication files safely.
Last updated: 2026-08-01
The dedicated server stores world and player data under universe/. Protect the complete server state, stop manual writes during a migration, and verify restoration before deleting the source copy.
What should be backed up?
| Data | Path or file |
|---|---|
| Worlds and player data | universe/ |
| Main settings | config.json |
| Permissions | permissions.json |
| Access controls | whitelist.json and bans.json |
| Installed mods | mods/ |
| Authentication | auth.enc and auth.key, stored with restricted access |
| JVM tuning | jvm.options, when used |
The server JAR, assets, caches, and launcher scripts can usually be downloaded again. Worlds, configuration, permissions, and authentication state are the irreplaceable parts.
Enable automatic backups
The server supports these launch options:
--backup
--backup-dir backups
--backup-frequency 30
The official wrapper scripts use a 30-minute backup interval by default. Confirm that the backup directory exists, receives new backups, and is included in an off-machine backup process.
An automatic backup on the same disk does not protect against disk failure, theft, or loss of the entire virtual machine.
Make a manual backup
- Notify players and wait for important activity to finish.
- Stop the server cleanly.
- Confirm the Java process has exited.
- Copy
universe/, configuration, permissions, access-control files, mods, and required authentication files to a dated destination. - Restrict access to the copy containing authentication files.
- Start the server and confirm that the live world still loads.
Do not publish a full backup as part of a support request.
Move to another server
- Install the same Hytale patchline and compatible Java runtime on the destination.
- Stop both source and destination servers.
- Back up both installations.
- Copy the source
universe/, configuration, permissions, whitelist, bans, and compatible mods. - Transfer authentication state only through a protected channel, or authenticate the destination again.
- Review bind addresses, paths, memory settings, and firewall rules that differ between hosts.
- Start the destination privately and inspect logs before opening it to players.
- Verify player data, worlds, permissions, mods, and backups.
Keep the source server stopped but recoverable until the destination has run successfully through a normal play session and backup cycle.
Updates and rollback
The update system can back up worlds and configuration before applying an update. Useful settings under Update include RunBackupBeforeUpdate and BackupConfigBeforeUpdate.
Treat automatic update backups as one layer, not the only recovery plan. Before a major release or patchline change, create a separate offline copy and record the exact server version. Client and server protocol versions currently need to match, but that does not guarantee that every mod or world change can safely roll back.
Restore test
A backup is not proven until it restores. Periodically restore a copy into a separate directory, start it on a non-public port, and verify the expected worlds, players, permissions, and mods without touching the production installation.