Setting Up a Hytale Server When the Docs Don't Exist Yet

Hytale launched into early access, and I wanted to run a dedicated server. The official documentation covered the basics — download, run, connect — but skipped most of the practical details. No community guides existed yet either. So I set one up, wrote down every step, and automated what I could.

This is what the process looked like.

The Protocol Surprise

The first thing that tripped me up was the network protocol. Most game servers use TCP, or TCP plus UDP for voice. Hytale uses QUIC on UDP port 5520. If your firewall rules only allow TCP, the server starts fine but no one can connect. No error, no timeout, just silence. That cost me more time than I’d like to admit.

Authentication was the next hurdle. Hytale servers require OAuth2 credentials tied to your Hypixel Studios account. The process involves two browser-based phases — registering the server and authorizing it — neither of which can be scripted. You complete them manually, then paste the credentials into the server config. It’s more secure than the old Minecraft model, but it means full automation isn’t possible.

On the Java side: JDK 25 Temurin, which isn’t in most distro repos yet. G1GC tuning, because the default JVM flags aren’t suited for game server workloads. And a 3.2 GB asset download on first launch that the docs don’t mention.

Ten Phases of Setup

The Linux setup script (linux/hytale-setup.sh) walks through ten phases:

1. System preparation — updates, fail2ban, timezone configuration
2. Java installation — Temurin JDK 25 via the Adoptium repository
3. User and directory setup — a dedicated hytale-server user, files under /opt/hytale
4. Server download — interactive, because of the OAuth2 requirement
5. JVM tuning — auto-detects available RAM and sets heap sizes
6. Server configuration — generates config.json, whitelist.json
7. Firewall — UFW rules for SSH on port 22 and game traffic on 5520/UDP
8. Systemd service — auto-start on boot, restart on crash, security hardening
9. First-run authentication — the /auth login step that links the server to your account
10. Summary — prints connection details and next steps

The Windows equivalent covers the same ground in seven phases, using PowerShell, Windows Firewall, and scheduled tasks instead of their Linux counterparts. Same ideas, different tools.

Backup and Update

The setup script gets a server running. The other four scripts keep it running.

The backup scripts (Linux and Windows) create timestamped archives of the server directory. They rotate old backups automatically — seven by default — and support hot backups, meaning you don’t need to stop the server first. The update scripts handle the stop-backup-download-restart cycle: they shut down the server, run a backup, pull the latest server files, and bring it back up.

Six scripts total across two platforms. Each one has a dry-run mode.

Writing the Tutorial

The tutorial file (HYTALE_SERVER_TUTORIAL.md) ended up at 44 KB across 18+ sections. Writing it took longer than the actual setup.

It starts with a managed hosting recommendation — $5-20/month, no Linux knowledge required. Not everyone should self-host, and the tutorial needed to be upfront about that. For those who do want to self-host, there’s a memory scaling table (2-3 GB for 5-10 players, scaling up to 22-26 GB for 50-100), a security checklist, and troubleshooting tables for common problems.

Turning terminal history into a tutorial means making every implicit step explicit. You have to remember what you assumed, what you skipped, what you only knew from experience. The OAuth2 flow was a good example — I’d done it once and internalized the steps, but writing them down revealed how many clicks and redirects were actually involved.

Design Decisions

A few things I kept in mind while writing the scripts:

• Dry-run modes on all six scripts — see what would change before anything does
• Idempotent execution — safe to re-run, skips steps that are already complete
• Auto JVM memory — calculates heap size from available RAM, ranging from 2 GB to 26 GB
• Cross-platform — Bash for Linux, PowerShell for Windows, with equivalent features on both
• Security hardening — systemd sandboxing, dedicated service user, minimal firewall rules

The Linux quick-start is one command:

curl -sL https://raw.githubusercontent.com/blugart-dev/hytale-server-toolkit/main/linux/hytale-setup.sh | bash -s -- --dry-run

Remove --dry-run when you’re ready.

What I Learned

New games need documentation early. There’s always a gap between a game launching and the community having decent guides. Someone has to write the first one, and it doesn’t require deep expertise — just patience and a willingness to write things down.

A guide and a script complement each other. The guide explains what’s happening. The script makes it repeatable. They serve different audiences and neither replaces the other.

Writing things down forces you to understand them. I knew enough to get the server running. Writing the tutorial made me realize how many steps I’d done on autopilot without fully understanding why. The OAuth2 flow in particular — some things can’t be automated, and the script has to handle that gracefully by pausing and telling the user what to do manually.

The toolkit is on GitHub. Whether anyone uses it or not, I understand Hytale server infrastructure better for having written it.