Hytale Server Config Files: config.json, Permissions, Whitelist and Bans

The files and what each one is for

The purposes in that table come straight from Hytale's Server Manual. The detail below, such as individual key names, comes from Hytale's Javadoc for the server config class or from community guides, and is labelled where it matters. In the standard layout the server folder is the one called Server, which is where community guides place these files.

The overwrite rule: why timing matters

The Server Manual states that the server reads these files at startup and writes them during in-game actions. That means the copy in memory is the truth while the server is running. If you change a file by hand and the server later saves its own state, your edit can be silently replaced.

The manual does not list which actions cause a write, but permission, ban and whitelist changes are the obvious candidates. Commands are the safer route while the server is up, because the server then makes the change itself, but the manual does not spell this out.

A safe editing routine

1. Back up

   Copy the files you are about to change, or take a full backup. On ChicagoServers, open the Backups tab and use Back up now if your plan includes backups. Choose World and settings for saves and configs.

2. Stop the server

   Click Stop at the top of the server page and wait for it to stop. Stop saves the world and shuts the game down properly.

3. Open the file

   Use the Files tab and click the file to open it in the editor, or connect over SFTP with the Host, Port and Username from the blue SFTP bar. The password is your panel password.

4. Make one change at a time

   Edit a single setting, keep the double quotes and commas intact, and save. Small changes are easier to undo.

5. Check the JSON

   Make sure every opening bracket has a closing one and that no entry ends with a trailing comma. Invalid JSON is a common reason a server fails to read its config.

6. Start and watch the console

   Click Start and read the Console tab. If the server complains about the file, restore your copy.

The panel's own guidance matches the game's rule: stop the server before replacing a file the game rewrites. Hytale's manual says the server rewrites these four files, so the same rule applies to them.

config.json: the server configuration

This is the file most owners need. Hytale's Javadoc for the server config class lists the settings the server understands, and community guides show how they appear in the JSON. The table combines the two, so key spellings are the community's and should be checked against your own file.

{
  "ServerName": "My Hytale Server",
  "MOTD": "Welcome. Be kind.",
  "Password": "",
  "MaxViewRadius": 12,
  "Defaults": {
    "World": "default",
    "GameMode": "Adventure"
  }
}

Several other entries exist (Modules, Mods, LogLevels, RateLimit, connection timeouts and storage providers). Hytale's Javadoc lists them, but neither it nor community guides explain them well. Leave them alone unless you have a specific reason. The Javadoc also lists a setting that requires players to hold the hytale.server.join permission before they can connect, which is a way to gate joining through permissions rather than a password.

The Update block in config.json

This block is documented in Hytale's Server Manual, so its names and defaults are reliable. Full context is in the updates and versions guide.

permissions.json, whitelist.json and bans.json

Hytale's manual names these files and their purposes but does not document their internal format. The safest approach is to let the game write them and use commands for day-to-day changes.

Command names have varied between Early Access builds, and one community guide notes that its commands differ from another's. Run /help on your server to confirm what your build uses before copying a command from any guide, including this one.

If you do edit whitelist.json by hand with the server stopped, one community guide describes an enabled setting plus a bracketed list of player UUIDs, each in quotes and separated by commas. The key name for that list is not given, so open your own file and follow its structure rather than guessing.

Per-world config.json

Each world has a config.json in universe/worlds/<world name>/. The server manual confirms the location. For the contents, one community guide documents these keys, which is a single source, so confirm them in your own file:

When the server will not start after an edit

• Read the Console tab and the files in logs/. A message that the server failed to read its config usually points to a formatting mistake or a damaged file.
• Look for trailing commas, missing quotes and unbalanced brackets.
• Restore your backup copy and re-apply your change a line at a time.
• If a config.json.bak file exists, that is a backup of an earlier version, and editing it changes nothing.
• As a last resort, a community guide suggests deleting the broken file so the server regenerates a clean one. Back up first, because you will lose your settings.

The panel's Troubleshoot tab lists recent crashes and failed starts with likely causes, which is a quick way to confirm the edit is to blame.

Running this on ChicagoServers

On a ChicagoServers Hytale server you edit these files from the Files tab or over SFTP, and you can give a helper edit access with Sub-users and the Files permission. Stop the server first, and see the setup guide for the rest of the layout.

Frequently asked questions