Using the Hytale Server Whitelist
How to enable and manage the Hytale server whitelist to restrict who can join your server.
Using the Hytale Server Whitelist
The Hytale server whitelist lets you restrict access so that only approved players can join. This is useful for private servers, friend groups, or development environments.
Enabling the Whitelist
Whitelist enforcement is controlled by the whitelist boolean in config.json:
{
"whitelist": true
}
Set this to true and restart the server. Once enabled, any player not present in whitelist.json will be denied entry with a "You are not whitelisted on this server" message.
To disable the whitelist without removing your list, simply set the value back to false.
The whitelist.json File
The whitelist is stored as a JSON array in whitelist.json in your server root directory. Each entry is a player object containing the player's UUID and display name:
[
{
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "JaneDoe"
},
{
"uuid": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
"name": "PlayerTwo"
}
]
The name field is for human readability only — access is determined by UUID. Keep names up to date for easier management.
Adding a Player to the Whitelist
- Find the player's UUID. You can get this from the server log when they attempt to connect, or from
universe/players/after a first login. - Open
whitelist.json. - Add a new object to the array:
[
{
"uuid": "existing-uuid-here",
"name": "ExistingPlayer"
},
{
"uuid": "new-player-uuid-here",
"name": "NewPlayer"
}
]
- Save the file and restart the server.
Removing a Player from the Whitelist
Delete the player's object from the array in whitelist.json, save, and restart. The player will be kicked on their next connection attempt if they are currently online.
Whitelist vs. Permissions
The whitelist controls whether a player can connect at all. The permissions system (permissions.json) controls what players can do once they are connected. These two systems are independent — a whitelisted player without an admin rank is still a regular player.
Empty Whitelist Warning
If whitelist is set to true but whitelist.json is empty or contains only an empty array [], no players will be able to join — including you. Always add yourself before enabling the whitelist.
Viewing the Current Whitelist
Because whitelist.json is plain JSON, you can read it directly:
cat /opt/hytale-server/whitelist.json