Hytale launches with proper dedicated server tooling, but it expects you to bring at least a little sysadmin energy. The server is a standalone Java application, it speaks QUIC over UDP instead of the usual TCP, and it leans on a few command-line flags rather than a big graphical wizard.
The good news: once Java 25 is installed and the server files are in place, getting a world online is mostly a matter of running a single command and opening the right port.
Hytale server requirements and what they mean
Hytale’s dedicated server runs on Java 25 on both x64 and arm64. It needs at least 4GB of memory, though practical usage depends heavily on how people play and how much of the world stays loaded at once.
| Component | Baseline | What actually drives usage |
|---|---|---|
| CPU | Modern 64‑bit CPU (x64 or arm64) | Number of active players, mobs/NPCs, and plugins or mods running. |
| RAM | 4GB minimum | View distance and how far apart players roam; large, spread-out exploration pushes RAM up. |
| Storage | Enough for Assets.zip and worlds | Long‑running servers with big universes and backups accumulate data over time. |
Memory tuning hinges on Java’s heap settings. If the heap is too small, the JVM spends more time in garbage collection, which looks like high CPU usage and stutter. Setting an explicit upper bound with -Xmx and then watching how the process behaves under load is the fastest way to find a stable configuration for your player count.
Install Java 25
The server expects Java 25. A typical setup uses the Temurin builds from Adoptium, which are standard OpenJDK distributions. Download the Java 25 JDK from adoptium.net/temurin/releases and install it as you would any other JDK for your platform.
Step 1: Install Java 25 using the installer or package for your OS. On Windows, that means running the MSI; on Linux or macOS, that usually means a package manager or tarball.
Step 2: After installation, open a terminal or command prompt and run:
java --version
You should see an OpenJDK 25.0.x line, confirming that Java 25 is on your PATH and ready for the server.
Get the Hytale server files
Hytale ships server binaries and assets alongside the client. There are two main ways to put those files on the machine that will host your server.
Option 1: Copy server files from the launcher install
This approach is fast for local testing but requires manual updates whenever the game patches.
Step 1: Install the Hytale launcher and let it download the game on a client machine signed into your Hytale account.
Step 2: Navigate to the game install directory for your platform:
- Windows:
%appdata%\Hytale\install\release\package\game\latest - Linux:
$XDG_DATA_HOME/Hytale/install/release/package/game/latest - macOS:
~/Application Support/Hytale/install/release/package/game/latest
Step 3: In that latest directory you’ll see a Client folder, a Server folder, and an Assets.zip file. Copy the entire Server folder and Assets.zip into a separate directory that will act as your dedicated server’s root.
That server root will be the working directory for your Java command and where logs, configs, and world data are created.
Option 2: Use the Hytale Downloader CLI
For anything beyond a quick local world, the Hytale Downloader CLI is the better option. It handles authentication, pulls the latest server and asset builds, and can be scripted into update flows for production servers.
Step 1: Download the CLI archive from downloader.hytale.com/hytale-downloader.zip and extract it into a directory on your server.
Step 2: Open a terminal in that directory and run:
./hytale-downloader
by default on Linux/macOS, or:
hytale-downloader.exe
on Windows. The CLI will authenticate using OAuth2 and download the latest Hytale package (server and assets) into the current folder, or into a specific file if you pass -download-path.
Step 3: Once downloaded, extract the server files into your chosen server root. You should again end up with a Server directory containing HytaleServer.jar and an Assets.zip sitting alongside it or in a path you control.
For scripts or tooling, the CLI exposes flags like -print-version, -check-update, and a -patchline pre-release option to pull from different update channels.
Run the Hytale server for the first time
With Java 25 installed and server files in place, bringing the server up is essentially one Java command. You point it at the server JAR and tell it where to find the assets.
Step 1: Open a terminal or command prompt in your server root directory (the one that contains the Server folder and Assets.zip).
Step 2: Run the basic launch command, updating the assets path if needed:
java -jar HytaleServer.jar --assets Assets.zip
The server will initialize, create its universe and configuration files, and then stop at an authentication step if it hasn’t been authorized yet.
Step 3: To see all launch options, use:
java -jar HytaleServer.jar --help
That prints the full list of flags, including options for authentication mode, binding to specific addresses and ports, enabling automatic backups, and toggling plugin support.
Authenticate your Hytale server
Hytale servers authenticate against Hytale accounts using an OAuth device flow. Without this step, the default authenticated mode will not accept incoming players.
Step 1: Start the server and wait for it to print a device login prompt containing a short code and URLs pointing to the Hytale accounts portal.
Step 2: On a browser, go to accounts.hytale.com/device and enter the device code displayed in your server console. Alternatively, use the direct URL with the user_code parameter that the server prints.
Step 3: Complete the login with your Hytale credentials in the browser. Once approved, the server console will confirm that authentication succeeded and switch into OAUTH_DEVICE mode.
There is a cap of 100 authenticated servers per Hytale game license. For large fleets you either spread the load across multiple licenses or use the Server Provider authentication flow, which is documented separately in Hypixel’s server provider guide.
For purely local testing, you can switch to an offline authentication mode via a launch flag, but that removes access to official service APIs and anti‑abuse protections.
Configure Hytale server ports and QUIC networking
Hytale’s dedicated server does not use the familiar TCP port used by many other sandbox games. It runs entirely over QUIC on UDP and defaults to port 5520. If players cannot connect, misconfigured UDP rules are often the cause.
Step 1: Decide which port you want to use. If the default 5520 is fine, you don’t have to change anything. To use a custom port, extend your launch command with a bind argument:
java -jar HytaleServer.jar --assets Assets.zip --bind 0.0.0.0:25565
That example binds to all interfaces on port 25565 instead of 5520.
Step 2: Open the chosen UDP port in any host firewalls.
On Linux with ufw:
sudo ufw allow 5520/udp
On Linux with iptables:
sudo iptables -A INPUT -p udp --dport 5520 -j ACCEPT
On Windows, a PowerShell rule might look like:
New-NetFirewallRule -DisplayName "Hytale Server" -Direction Inbound -Protocol UDP -LocalPort 5520 -Action Allow
Step 3: If the server is behind a consumer router, configure port forwarding for UDP only. Forward the external port (for example, 5520) to the internal IP address and same port on your server machine. Forwarding TCP is not required for player traffic.
QUIC usually handles NAT traversal well, but symmetric NAT setups can still cause issues for self‑hosted machines on home networks. If players consistently fail to connect despite open UDP rules and proper forwarding, a VPS or dedicated server with a public IP often removes those variables.
Understand Hytale server directories and worlds
Once the server has run at least once, the root directory fills out with a predictable set of folders and JSON files.
| Path | Purpose |
|---|---|
.cache/ |
Stores optimized and ahead‑of‑time compiled data for faster startup. |
logs/ |
Text logs of server activity and errors. |
mods/ |
Place mod archives here (.zip or .jar) to load them at startup. |
universe/ |
Holds world data, player saves, and related configuration. |
config.json |
Server‑wide settings such as name, view distance, and general behavior. |
permissions.json |
Permission groups and assigned roles. |
whitelist.json |
Accounts allowed to join when whitelisting is enabled. |
bans.json |
List of banned players. |
Inside universe/worlds/, each world gets its own folder with a config.json that describes how it was generated (seed, generator type, gameplay toggles, and so on). Settings like PvP, fall damage, NPC spawning, and time behavior are all controlled there.
Each world runs on its own main thread, with parallel work scheduled onto a shared pool, which gives the engine room to scale across CPU cores when multiple worlds or heavy workloads are active.
Configuration files are both read and written by the server. Edits performed while the server is running can be overwritten by in‑game commands or internal writes. The safest pattern is to shut the server down, modify JSON files, then start it again so your changes load cleanly.
Install mods and plugins on a Hytale server
Hytale treats mods as archives you drop into a dedicated folder. There is no separate plugin loader binary to wire up for basic modifications.
Step 1: Download mods in the supported formats (typically .zip or .jar).
Step 2: Place those files into the mods/ directory in your server root.
Step 3: Restart the server so it can discover and load the new content at startup.
For early plugin development, Hytale ships with Sentry crash reporting enabled. When you are intentionally breaking things, disable that telemetry using the --disable-sentry flag so development crashes do not get reported upstream:
java -jar HytaleServer.jar --assets Assets.zip --disable-sentry
The server also includes an ahead‑of‑time compilation cache file called HytaleServer.aot. Pointing the JVM at this cache improves startup times by skipping a lot of JIT warm‑up work:
java -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar --assets Assets.zip
On the ecosystem side, hosting partners maintain plugins for familiar operational tasks. Examples include web server stubs for APIs, HTTP status endpoints with player counts, performance savers that dynamically throttle view distance under load, and Prometheus exporters for scraping JVM metrics.
Tune view distance and performance
View distance is the single easiest way to blow through RAM on a Hytale server. The default configuration loads a radius equivalent to roughly 24 Minecraft chunks, which means more world data, entities, and structures are held in memory per player.
Limiting maximum view distance to 12 chunks (384 blocks) keeps memory demands under control and usually improves overall server stability, especially when players split up and explore separate regions. For small, tightly clustered groups you can cautiously raise this number, but the effect on memory is immediate.
Alongside view distance, keep an eye on:
- Java heap settings: explicit
-Xmsand-Xmxvalues help prevent the JVM from guessing wrong. - Entity counts: mob farms or dense NPC hubs add CPU load.
- Mods and plugins: poorly behaved code can leak memory or schedule too many tasks.
Monitoring tools such as Prometheus paired with an exporter plugin can surface these behaviors quickly if you are running a larger community server.
Handle updates and protocol versions
Hytale’s client and server must match at the protocol level. The game currently enforces a strict hash check between the protocol implementation on both sides; if the versions don’t line up, the client cannot connect.
That design has a very practical consequence: when the game updates, servers need to update closely in step or your players who patch their clients will be unable to join. Planned protocol tolerance will eventually introduce a small window where newer clients can talk to slightly older servers (and vice versa), but the current behavior expects you to keep everything aligned.
For manual setups, that usually means rerunning the Hytale Downloader CLI to pull updated assets and server binaries, then restarting the server. For launcher‑copied installs, you need to repeat the copy step after the client patches.
Build more complex Hytale server architectures
Hytale bakes in mechanisms that many other games delegate to external proxies. If you plan to run multiple worlds, lobbies, or minigames under a shared umbrella, those hooks matter.
- Player referral: a connected player can be instructed to join another server by sending a referral packet with a host, port, and up to 4KB of payload. The client then establishes a fresh connection to the new target and presents that payload during its handshake.
- Connection redirect: during the initial handshake, a server can reject the connection but provide alternate server details. The client transparently reconnects to the new address, which is useful for region routing or funneling everyone through a lobby.
- Disconnect fallback: when a server fails or a connection drops unexpectedly, the client can automatically reconnect to a preconfigured fallback server, often a central lobby, instead of dumping the player back at the main menu.
The referral payload passes through the client, which means it is not trustworthy on its own. Signing that payload with an HMAC or similar shared secret lets the destination server verify it has not been tampered with.
If you want something closer to a traditional proxy layer, Hytale exposes its protocol definitions in the com.hypixel.hytale.protocol.packets package inside HytaleServer.jar. Combined with Netty’s QUIC support, you can build a proxy that inspects, modifies, and forwards packets between clients and backend game servers while staying fully native to Hytale’s networking stack.
Once Java 25 is installed, the server files are in place, and UDP traffic is flowing on the right port, running a Hytale server becomes an iterative process: tweak view distance, watch CPU and RAM, add mods carefully, and keep the protocol version in sync with your players. The tooling is deliberately minimal but expressive; the tradeoff is that most of the important behavior is in those launch flags and JSON configs rather than a glossy UI.
