Hytale Server Permissions, Whitelist and Bans: Admin Setup Guide

The three files and how they behave

The manual's file listing for a server directory describes the access files like this:

The manual states that config files are read when the server starts and rewritten when in-game actions run, so manual changes made while the server is running are likely to be overwritten. The practical rules that follow:

• To change access while the server is running, use commands, not file edits.
• To edit a file by hand, click Stop first, edit on the Files tab, save, then Start.
• JSON is strict. A missing comma or bracket can stop the file from loading, so make a copy of the file before you edit it.
• Before a Hytale update, the manual notes the updater can back up config.json, permissions.json, bans.json and whitelist.json (the BackupConfigBeforeUpdate option, default true). That still does not replace your own backup. Back up the access files before updating, because file layouts and command names can change between Early Access builds.

Become an operator

Operators are administrators. Community documentation describes them as members of a built-in administrator group, named hytale:Admin in recent sources and written OP or op in older ones. One provider says the old OP name is still read as hytale:Admin. You do not need to memorise that to use the commands.

1. Join the server once

   Start the server on the panel and join with your Hytale account so the server knows who you are. One guide documents /op add for online players, so have the person connected when you run it.

2. Open the Console tab

   On panel.chicagoservers.co, open your server and click Console. Console input runs with full rights (hosting guides describe it as having full server permissions).

3. Add yourself

   Type the command below, replacing the placeholder with your exact player name, and press Send.

   Copy

   /op add YourPlayerName

4. Check that it worked

   Run a command that needs admin rights in game, or use the permission test command described below. Remove someone later with /op remove followed by the name.

   Copy

   /op remove SomePlayerName

The server also has a launch flag, --allow-op, which appears in the manual's --help list with no description. Community guides report it enables /op self, a command that needs no permission, so while the flag is on any player who joins could promote themselves. Use it, if at all, only for a few minutes of initial setup on a private server, and never on a public one.

Admin access can also be given through permissions.json directly. One provider's example adds a user by UUID with the administrator group:

{
  "users": {
    "00000000-0000-0000-0000-000000000000": {
      "groups": ["hytale:Admin"]
    }
  }
}

Permission groups and nodes

Permissions are organised as groups that hold permission nodes, and users (keyed by UUID) that belong to groups or hold nodes directly. A wildcard, written * in one provider's example, grants everything, which is what you give an administrator group and no one else.

Hosting documentation lists these /perm commands. They work on UUIDs, not names, so the player has to tell you theirs (one source says the in-game command /whoami shows it):

Permission node names are where sources disagree most. Several guides describe command nodes as hytale.command.<command>, while another lists nodes such as hytale.accesscontrolmodule.command.ban and hytale.system.command.kick. Both may reflect different builds, so do not copy a node from a guide without testing it: run /perm test with the node, then check the behaviour using a test account.

Give a moderator limited access

The goal is a moderator who can remove troublemakers without being able to wipe the world or change the server. Do this with a custom group that has only the nodes you choose, not with the operator group.

1. Create the group by giving it nodes

   Add a few moderation nodes to a new group name. The example uses moderator; the nodes shown are illustrative placeholders for the kick, ban and unban nodes in your build. Confirm real names with the permission test command and your own server's help output.

   Copy

   /perm group add moderator <kick-node> <ban-node> <unban-node>

2. Look up the moderator's UUID

   Ask them to run /whoami in game (one provider documents it). If they have been given permissions before, their UUID will also appear in permissions.json.

3. Put them in the group

   Add the player by UUID.

   Copy

   /perm user group add <uuid> moderator

4. Test from their account

   Have the moderator try a kick and a command they should not have, such as changing the game mode. The second should be refused. Adjust the group and run /perm reload if you edited the file by hand.

A hand-edited version of the same idea uses the file structure that community examples show: a groups section where each group has a permissions list, and a users section where each UUID has a groups list. Edit it only with the server stopped.

{
  "groups": {
    "moderator": {
      "permissions": ["<kick-node>", "<ban-node>", "<unban-node>"]
    }
  },
  "users": {
    "<moderator-uuid>": { "groups": ["moderator"] }
  }
}

Inheritance between groups, for example a moderator group that also gets everything a normal player has, is mentioned by community guides but without agreed syntax, so use /perm --help or the in-game help before relying on it.

Panel sub-users are separate from in-game permissions

Two completely different systems control what a helper can do, and it is worth keeping them apart:

A moderator who only needs to keep order in game needs no panel access at all. Give them an in-game group and stop there. Panel access is for people who help run the server itself.

To add panel access, click Sub-users in the left menu, then under Add someone enter their email (a login is created and the password is shown once) or an existing username, tick the servers, tick their permissions under What they can do there, and click Give access. The panel shows a sub-user only the tabs their permissions allow.

• Console lets them type server commands. Because the console runs with full rights, treat Console as equivalent to being an administrator.
• Files includes SFTP, and lets them edit permissions.json, replace mods and touch world data. Treat it the same way.
• Backups is a reasonable permission for a trusted co-owner who looks after restore points.
• Leave off anything the person does not need, especially reinstall permission, which erases the server's files.

Run a whitelist without locking yourself out

The whitelist is the simplest way to keep a private server private. The commands, as hosting guides describe them, are:

1. Add yourself and your staff first

   Run /whitelist add for each person, starting with you.

2. Check the list

   Run /whitelist list and /whitelist status to confirm the entries and the current state.

3. Enable it

   Run /whitelist enable.

4. Test a join

   Join with a whitelisted account, and with a spare account that is not on the list if you can. If you get locked out, use the Console tab to run /whitelist disable and fix the list.

Check how your build stores it. Older documentation describes whitelist.json as a file with an enabled flag and a list of players. Two providers say that from roughly Update 6 onward the whitelist became a permission (named hytale.server.join), that an existing whitelist.json was renamed to whitelist.json.migrated, and that the whitelist is now driven by the permission system rather than the file. The official manual still lists whitelist.json as the whitelisted players file. Because this is still moving, rely on the commands and on /whitelist status rather than on the file, and ask in the console with /help whitelist for the syntax your build expects.

Handle bans

Bans are stored in bans.json and managed with three commands:

• /ban <name or UUID> bans a player. One provider documents that everything after the name becomes the reason, and that an online player is disconnected straight away; other sources list no reason argument, so check /help ban on your build.
• /unban <name> lifts a ban.
• /kick <player> removes someone without banning them.

The built-in ban reportedly has no duration; it lasts until you unban. If you need temporary bans, a plugin that replaces ban handling is the usual route, and one provider notes plugins can do that through a ban provider interface. That means a plugin choice, so read the mods guide before installing one.

A few habits keep moderation clean. Write the reason every time, so a later moderator knows why. Prefer banning by UUID when you can get it, because a name is easier to change than an account. Keep a copy of bans.json in your backups, so a restore does not quietly bring banned players back, and note that restoring an older backup will restore the older ban list too.

Running this on ChicagoServers

On a ChicagoServers Hytale server you run these commands from the Console tab, edit the files on the Files tab with the server stopped, and share the panel with Sub-users. Before changing permissions in bulk, take a quick backup from the Backups tab; the backups guide explains the options. If a command is not recognised on your build, 24/7 support can help.

Frequently asked questions