Optimized Hytale dedicated server with Java 25 and multi-arch support
4.3K
An optimized, production-ready Docker image for running Hytale dedicated servers.
This is an unofficial community project. Hytale is a trademark of Hypixel Studios.
All images use SemVer with Hytale version as build metadata:
| Tag | Description | Example |
|---|---|---|
latest | Latest stable release | everhytale/hytale-server:latest |
X.Y.Z+HYTALE_VERSION | Full version (image + Hytale) | 1.0.0+2026.01.15-c04fdfe10 |
HYTALE_VERSION | Latest image for this Hytale version | 2026.01.15-c04fdfe10 |
X.Y | Minor version (latest patch) | 1.0 |
X | Major version (latest minor) | 1 |
rc | Latest release candidate | rc |
dev | Latest development build | dev |
edge | Latest build from main branch | edge |
The CI/CD pipeline automatically checks for new Hytale versions every 12 hours. When a new version is detected, a new Docker image is built and pushed with the appropriate tags.
linux/amd64 and linux/arm64# Latest stable release
docker pull everhytale/hytale-server:latest
# Specific Hytale version (latest image for that version)
docker pull everhytale/hytale-server:2026.01.15-c04fdfe10
# Specific image + Hytale version
docker pull everhytale/hytale-server:1.0.0+2026.01.15-c04fdfe10
# Create data directory
mkdir -p ./data
# Run the server
docker run -d \
--name hytale-server \
-p 5520:5520/udp \
-v ./data:/server \
-v /etc/machine-id:/etc/machine-id:ro \
-e MIN_MEMORY=4G \
-e MAX_MEMORY=8G \
everhytale/hytale-server:latest
Clone the repository
git clone https://github.com/everhytale/dockers.git
cd dockers/dockers/hytale-server
Authenticate with Hytale
chmod +x scripts/hytale-auth.sh
./scripts/hytale-auth.sh
Follow the instructions to complete OAuth2 authentication.
Start the server
docker-compose up -d
View logs
docker-compose logs -f
| Variable | Default | Description |
|---|---|---|
MIN_MEMORY | 4G | Minimum JVM heap size |
MAX_MEMORY | 8G | Maximum JVM heap size |
SERVER_PORT | 5520 | Server port (UDP) |
SERVER_BIND | 0.0.0.0 | Bind address |
AUTH_MODE | authenticated | Authentication mode (authenticated or offline) |
DISABLE_SENTRY | false | Disable crash reporting (for development) |
USE_AOT_CACHE | true | Use AOT cache for faster startup |
BACKUP_ENABLED | false | Enable automatic backups (--backup) |
BACKUP_DIR | /server/backups | Backup directory path (--backup-dir) |
BACKUP_FREQUENCY | 30 | Backup interval in minutes (--backup-frequency) |
BACKUP_MAX_COUNT | 5 | Maximum number of backups to keep (--backup-max-count) |
| Variable | Description |
|---|---|
OWNER_NAME | Server owner username |
OWNER_UUID | Server owner UUID |
SESSION_TOKEN | Session token from OAuth2 |
IDENTITY_TOKEN | Identity token (JWT) |
The image separates game files (read-only) from server data (persistent):
/opt/hytale-server/ # Game files (read-only, in image)
āāā HytaleServer.jar # Server executable
āāā HytaleServer.aot # AOT cache (faster startup)
āāā Assets.zip # Game assets
/server/ # Server data (persistent, mounted volume)
āāā universe/ # Worlds and player data
āāā mods/ # Installed mods
āāā logs/ # Server logs
āāā .cache/ # Optimized cache
āāā auth.enc # Encrypted authentication credentials
āāā config.json # Server configuration
āāā permissions.json # Permissions
āāā whitelist.json # Whitelisted players
āāā bans.json # Banned players
Key benefits:
/server volume/server directoryHytale servers require authentication to communicate with Hytale's service APIs. There are two methods:
Start the server and attach to console:
docker-compose up -d
docker attach hytale-server
Authenticate via device code:
/auth login device
You'll see output like:
===================================================================
DEVICE AUTHORIZATION
===================================================================
Visit: https://accounts.hytale.com/device
Enter code: ABCD-1234
===================================================================
Complete authorization in your browser, then wait for confirmation:
Authentication successful! Use '/auth status' to view details.
WARNING: Credentials stored in memory only - they will be lost on restart!
Persist credentials to survive container restarts:
/auth persistence Encrypted
Output:
Swapped credential store to: EncryptedAuthCredentialStoreProvider
Detach from container (without stopping it):
Press Ctrl+P then Ctrl+Q
auth.enc FileWhen you use /auth persistence Encrypted, Hytale creates an encrypted file auth.enc that stores your authentication credentials. This file:
Important: To use encrypted persistence in Docker, you must:
Quick setup with local files (recommended):
# Create data directory and empty auth.enc
mkdir -p ./data
touch ./data/auth.enc
# Use the local configuration
docker-compose -f docker-compose.local.yml up -d
Or add to your docker-compose.yml:
volumes:
- /etc/machine-id:/etc/machine-id:ro
- /var/lib/dbus/machine-id:/var/lib/dbus/machine-id:ro
- ./data/auth.enc:/server/auth.enc # Persist auth credentials
| Type | Command | Description |
|---|---|---|
Memory | /auth persistence Memory | Credentials lost on restart (default) |
Encrypted | /auth persistence Encrypted | Credentials saved to auth.enc, encrypted with machine-id |
Use the included scripts to obtain tokens programmatically:
# Initial authentication
./scripts/hytale-auth.sh
# Refresh expired tokens
./scripts/hytale-refresh.sh
docker-compose restart
This method sets environment variables (SESSION_TOKEN, IDENTITY_TOKEN) that are passed to the server at startup.
You'll need Hytale credentials stored as a credentials file.
Game files are now downloaded separately before building:
cd dockers/hytale-server
# 1. Create credentials file (or use scripts/hytale-auth.sh)
echo '{"access_token":"...", "refresh_token":"..."}' > .hytale-downloader-credentials.json
# 2. Download game files
./scripts/download-game.sh
# 3. Build the image with HYTALE_VERSION
HYTALE_VERSION=$(cat game-files/.version) docker compose -f docker-compose.build.yml build
# 4. Run the server
docker compose -f docker-compose.build.yml up -d
The download-game.sh script will:
./game-files/./game-files/.version# Build for multiple platforms
HYTALE_VERSION=$(cat game-files/.version) docker buildx build \
--platform linux/amd64,linux/arm64 \
--build-context game=./game-files \
--build-arg HYTALE_VERSION=$HYTALE_VERSION \
-t everhytale/hytale-server:local \
--push .
Security Note: Credentials are never included in the Docker image. Game files are downloaded separately before the build.
The repository includes a GitHub Actions workflow that:
For a release v1.0.0 with Hytale version 2026.01.15-c04fdfe10:
1.0.0+2026.01.15-c04fdfe10 (full version)2026.01.15-c04fdfe10 (Hytale version, latest image)1.0.0, 1.0, 1 (SemVer)latest| Secret | Description |
|---|---|
HYTALE_CREDENTIALS | Required. JSON credentials for the Hytale downloader |
DOCKERHUB_USERNAME | Optional. Docker Hub username |
DOCKERHUB_TOKEN | Optional. Docker Hub access token |
Hytale uses the QUIC protocol over UDP (not TCP).
# Linux (ufw)
sudo ufw allow 5520/udp
# Linux (iptables)
sudo iptables -A INPUT -p udp --dport 5520 -j ACCEPT
# Windows PowerShell
New-NetFirewallRule -DisplayName "Hytale Server" -Direction Inbound -Protocol UDP -LocalPort 5520 -Action Allow
If behind a router, forward UDP port 5520 to your server. TCP is not required.
If you see "Failed to get Hardware UUID":
# docker-compose.yml
volumes:
- /etc/machine-id:/etc/machine-id:ro
Or use memory-based persistence:
/auth persistence Memory
Refresh tokens using the included script:
./scripts/hytale-refresh.sh
docker-compose restart
docker-compose logs -fThis project is licensed under the MIT License - see the LICENSEā file for details.
Contributions are welcome! Please read our Contributing Guidelinesā before submitting a PR.
Content type
Image
Digest
sha256:f7f8eb4a0ā¦
Size
1.5 GB
Last updated
9 months ago
docker pull everhytale/hytale-server