Quick Start
Get your Hytale server running in minutes
Quick Start
Get your Hytale server up and running in just a few minutes.
Prerequisites
Before you begin, ensure you have:
- Docker installed (version 20.10 or later)
- Docker Compose (included with Docker Desktop)
- A Hytale account for server authentication
- UDP port 5520 available on your system
Requirements
| Component | Requirement |
|---|---|
| Java | 25+ (included in image) |
| RAM | 4GB minimum, 8GB+ recommended |
| Disk | ~2GB for server files |
| Network | UDP port 5520 |
Clone the Repository
git clone https://github.com/romariin/hytale-docker.git
cd hytale-docker/examplesStart the Server
docker compose up -dThis command will:
- Build the Docker image
- Download the Hytale server files automatically
- Start the server container
Watch the Logs
docker compose logs -fYou'll see:
- Pre-flight checks (Java version, dependencies)
- Server file download via
hytale-downloader - Server startup
- Authentication prompt (first run only)
Authenticate (First Run Only)
Authentication is automatic. Just watch the logs for the device authorization URL.
When you see the device auth prompt:
- Visit the URL shown in the logs
- Log in with your Hytale account
- Enter the verification code
- Authorize the server
The container will automatically:
- Detect successful authentication
- Enable encrypted persistence (
/auth persistence Encrypted) - Be ready for connections
Connect to Your Server
Open the Hytale client and connect to:
your-ip:5520Replace your-ip with:
localhostif running locally- Your public IP address if hosting remotely
What Happens on Startup
1. Pre-flight checks
├── Java 25+ ✓
├── hytale-downloader ✓
└── Dependencies ✓
2. Download server (if needed)
├── Run hytale-downloader
├── Extract Server/ and Assets.zip
└── Verify files
3. Start server
└── java -jar HytaleServer.jar ...
4. Auto-auth (if enabled)
├── Wait for "Hytale Server Booted"
├── Check for existing persistence
│ ├── Found → Done
│ └── Not found → /auth login device
└── On success → /auth persistence EncryptedImportant Notes
Hytale uses QUIC over UDP (not TCP). Make sure to:
- Forward UDP port 5520 in your firewall
- Configure your router for UDP port forwarding
On subsequent restarts, authentication happens automatically if persistence was configured correctly.
Console Access
To run server commands:
docker attach hytale-serverType commands like /help, /auth status, etc.
Detach without stopping: Press Ctrl+P then Ctrl+Q
Managing the Server
View Logs
docker compose logs -fStop Server
docker compose downRestart Server
docker compose restartForce Re-download
docker compose down
FORCE_UPDATE=true docker compose up -dFull Reset (Deletes All Data!)
docker compose down -v
docker compose up -dThe -v flag deletes all volumes including world data and auth credentials!