Hytale Server Manual

The Hytale server can run on any device with at least 4GB of memory and Java 25. Both x64 and arm64 architectures are supported.

Installing Java 25

Install Java 25. We recommend Adoptium.

Confirm Installation

Verify the installation by running:

java --version

Expected output:

openjdk 25 2025-09-16
OpenJDK Runtime Environment Temurin-25+...

Server Files

Two options to obtain server files:

• Manually copy from your Launcher installation
• Use the Hytale Downloader CLI

Manually Copy from Launcher

Find the files in your launcher installation folder:

# Windows
cd %LOCALAPPDATA%\Hytale\versions\0.5.X\

# macOS
cd ~/Library/Application\ Support/Hytale/versions/0.5.X/

# Linux
cd ~/.local/share/Hytale/versions/0.5.X/

Copy the Server folder and Assets.zip to your destination server folder.

Hytale Downloader CLI

A command-line tool to download Hytale server and asset files with OAuth2 authentication. See QUICKSTART.md inside the archive.

Start the server with:

java -jar HytaleServer.jar

Authentication

After first launch, authenticate your server. Once authenticated, your server can accept player connections.

Help

Review all available arguments:

java -jar HytaleServer.jar --help

Ports

Default port is 5520. Change it with the --bind argument:

java -jar HytaleServer.jar --bind 0.0.0.0:25565

Firewall & Network Configuration

Port Forwarding

If hosting behind a router, forward UDP port 5520 (or your custom port) to your server machine. TCP forwarding is not required.

Firewall Rules

Windows Defender Firewall:

netsh advfirewall firewall add rule name="Hytale Server" dir=in action=allow protocol=UDP localport=5520

Linux (iptables):

sudo iptables -A INPUT -p udp --dport 5520 -j ACCEPT

Linux (ufw):

sudo ufw allow 5520/udp

NAT Considerations

QUIC handles NAT traversal well in most cases. If players have trouble connecting:

• Ensure the port forward is specifically for UDP, not TCP
• Symmetric NAT configurations may cause issues - consider a VPS or dedicated server
• Players behind carrier-grade NAT (common on mobile networks) should connect fine as clients

Installing Mods

Download mods (.zip or .jar) from sources like Mytale or CurseForge and drop them into the mods/ folder.

Disable Sentry Crash Reporting

Hytale uses Sentry to track crashes. Disable it with --disable-sentry to avoid submitting your development errors:

java -jar HytaleServer.jar --disable-sentry

Leverage Ahead-Of-Time Cache

The server ships with a pre-trained AOT cache (HytaleServer.aot) that improves boot times by skipping JIT warmup. See JEP-514.

Recommended Plugins

Development partners at Nitrado and Apex Hosting maintain plugins for common server hosting needs:

View Distance

View distance is the main driver for RAM usage. We recommend limiting maximum view distance to 12 chunks (384 blocks) for both performance and gameplay.

Hytale supports native mechanisms for routing players between servers. No reverse proxy like BungeeCord is required.

Player Referral

Transfers a connected player to another server. The server sends a referral packet containing the target host, port, and an optional 4KB payload. The client opens a new connection to the target and presents the payload.

Connection Redirects

During connection handshake, a server can reject the player and redirect them to a different server. The client automatically connects to the redirected address.

Disconnect Fallback

When a player is unexpectedly disconnected (server crash, network interruption), the client automatically reconnects to a pre-configured fallback server instead of returning to the main menu.

Building a Proxy

Build custom proxy servers using Netty QUIC. Hytale uses QUIC exclusively for client-server communication.

Packet definitions and protocol structure are available in HytaleServer.jar. Use these to decode, inspect, modify, or forward traffic between clients and backend servers.

Java Command-Line Arguments

See Guide to the Most Important JVM Parameters for topics like -Xms and -Xmx to control heap size.

Protocol Updates

The Hytale protocol uses a hash to verify client-server compatibility. If hashes don't match exactly, the connection is rejected.

Configuration Files

Configuration files (config.json, permissions.json, etc.) are read on server startup and written to when in-game actions occur (e.g., assigning permissions via command). Manual changes while the server is running may be overwritten.

Maven Central Artifacts

The HytaleServer jar will be published to Maven Central for use as a dependency in modding projects. Exact details including versioning are pending for launch.

Hytale has announced several upcoming features for server operators: