Hytale Server Docker Image

A Docker image for running Hytale dedicated servers, inspired by itzg/minecraft-server.

Quick Start

Using Docker Compose (Recommended)

1. Create a docker-compose.yml file:

version: '3.8'

services:
  hytale:
    image: ghcr.io/ginco-org/hytale-server:latest
    container_name: hytale-server
    restart: unless-stopped
    ports:
      - "5520:5520/udp"
    environment:
      EULA: "true"  # Accept Hytale EULA
      MEMORY: "4G"
    volumes:
      - ./data:/data

2. Start the server:

docker-compose up -d

3. Follow the authentication prompts in the logs:

docker-compose logs -f

The server will display a URL and code - visit the URL to authorize the server.

Using Docker CLI

docker run -d \
  --name hytale-server \
  -p 5520:5520/udp \
  -e EULA=true \
  -e MEMORY=4G \
  -v $(pwd)/data:/data \
  ghcr.io/ginco-org/hytale-server:latest

Important Notes

QUIC Protocol (UDP)

Hytale uses the QUIC protocol over UDP, not TCP. Make sure to:

• Expose UDP port 5520 (or your custom port)
• Configure your firewall to allow UDP traffic
• If behind a router, forward UDP port 5520 to your server

System Requirements

Resource	Minimum	Recommended
Memory	4GB	6GB+
CPU	2 cores	4+ cores
Storage	NVMe SSD strongly recommended
Java	25 (included in image)

Environment Variables

Required

Variable	Default	Description
EULA	false	Must be set to true to accept the Hytale EULA

Memory

Variable	Default	Description
MEMORY	4G	Memory allocation (e.g., 4G, 8G, 12G)
JVM_OPTS	G1GC settings	Additional JVM arguments

Version

Variable	Default	Description
HYTALE_VERSION	latest	Server version: latest or pre-release

Network

Variable	Default	Description
BIND_ADDRESS	0.0.0.0:5520	IP and port to bind

Authentication

Variable	Default	Description
AUTH_MODE	authenticated	authenticated or offline
HYTALE_SERVER_SESSION_TOKEN	(empty)	Session token for automated auth
HYTALE_SERVER_IDENTITY_TOKEN	(empty)	Identity token for automated auth
OWNER_UUID	(empty)	Owner UUID for profile selection

Server Options

Variable	Default	Description
ENABLE_AOT_CACHE	true	Enable AOT cache for faster startup
ENABLE_SENTRY	false	Enable Sentry crash reporting
ALLOW_OP	true	Allow operator permissions

Backups

Variable	Default	Description
ENABLE_BACKUP	false	Enable automatic backups
BACKUP_FREQUENCY	30	Backup interval in minutes
BACKUP_DIR	/data/backups	Backup directory

Server Type

Variable	Default	Description
TYPE	vanilla	Server type: vanilla or custom

Authentication

Method 1: Automatic Device Flow (Default - Recommended)

The container automatically initiates OAuth2 device authentication on first startup. Credentials are then cached in the /data volume so subsequent restarts authenticate silently without any user interaction.

1. Start the server:

docker-compose up -d

2. Watch the logs:

docker-compose logs -f

3. On first run you will be prompted to authorize twice — once for the game file downloader and once for the server itself. This is a Hytale security requirement; the two OAuth clients (hytale-downloader and hytale-server) are separate and cannot share tokens.

====================================================================
DEVICE AUTHORIZATION  (1 of 2 — downloader)
====================================================================
Visit: https://accounts.hytale.com/device?user_code=ABCD-1234
...
====================================================================
DEVICE AUTHORIZATION  (2 of 2 — server)
====================================================================
Visit: https://accounts.hytale.com/device?user_code=WXYZ-5678
...

4. Open each URL in your browser and authorize when prompted

5. The server starts; both credential sets are saved to /data

After the first run, no further browser interaction is needed. Both the downloader and server cache their credentials in the persistent /data volume:

• Restarts reuse cached tokens silently
• Server version upgrades reuse the downloader credentials (no re-auth)
• Credentials auto-refresh; you only need to re-authenticate if a token is explicitly revoked or expires (~30 days)

To force re-authentication, delete the relevant file and restart:

• Server: rm data/.auth/tokens.json
• Downloader: rm data/.hytale-downloader-credentials.json

Both files contain sensitive credentials and are created with restricted permissions. Ensure your /data volume is not world-readable on the host.

Method 2: Token Passthrough (Advanced)

For server hosting providers or automated deployments where you manage tokens externally:

environment:
  HYTALE_SERVER_SESSION_TOKEN: "your-session-token"
  HYTALE_SERVER_IDENTITY_TOKEN: "your-identity-token"
  OWNER_UUID: "your-profile-uuid"

When these environment variables are provided, the automatic device flow is skipped.

See the Server Provider Authentication Guide for details on obtaining and refreshing tokens programmatically.

Method 3: Offline Mode

For testing or local servers:

environment:
  AUTH_MODE: "offline"

Note: Offline mode disables player validation and service API access.

Volumes

Path	Description
/data	Main data directory (world, configs, logs)
/data/universe	World save data
/data/mods	Installed mods
/data/logs	Server logs
/data/backups	Automatic backups (if enabled)
/data/.cache	AOT cache and optimized files
/data/.auth/tokens.json	Cached server OAuth2 credentials (mode 600)
/data/.hytale-downloader-credentials.json	Cached downloader OAuth2 credentials
/data/.version	Installed server version (used for update detection)

Installing Mods

Option 1: Volume Mount

volumes:
  - ./data:/data
  - ./mods:/mods:ro

Place your mod .jar or .zip files in the ./mods directory.

Option 2: Direct Copy

Copy mods directly to ./data/mods/ directory.

Examples

Basic Server

services:
  hytale:
    image: ghcr.io/ginco-org/hytale-server:latest
    ports:
      - "5520:5520/udp"
    environment:
      EULA: "true"
      MEMORY: "4G"
    volumes:
      - ./data:/data

Server with Backups

services:
  hytale:
    image: ghcr.io/ginco-org/hytale-server:latest
    ports:
      - "5520:5520/udp"
    environment:
      EULA: "true"
      MEMORY: "6G"
      ENABLE_BACKUP: "true"
      BACKUP_FREQUENCY: "60"
    volumes:
      - ./data:/data

Server with Mods

services:
  hytale:
    image: ghcr.io/ginco-org/hytale-server:latest
    ports:
      - "5520:5520/udp"
    environment:
      EULA: "true"
      MEMORY: "8G"
      TYPE: "custom"
    volumes:
      - ./data:/data
      - ./mods:/mods:ro

Pre-release Server

services:
  hytale:
    image: ghcr.io/ginco-org/hytale-server:latest
    ports:
      - "5520:5520/udp"
    environment:
      EULA: "true"
      MEMORY: "4G"
      HYTALE_VERSION: "pre-release"
    volumes:
      - ./data:/data

Automated Server (GSP)

services:
  hytale:
    image: ghcr.io/ginco-org/hytale-server:latest
    ports:
      - "5520:5520/udp"
    environment:
      EULA: "true"
      MEMORY: "6G"
      HYTALE_SERVER_SESSION_TOKEN: "${SESSION_TOKEN}"
      HYTALE_SERVER_IDENTITY_TOKEN: "${IDENTITY_TOKEN}"
      OWNER_UUID: "${OWNER_UUID}"
    volumes:
      - ./data:/data

Building from Source

git clone https://github.com/ginco-org/hytale-server.git
cd hytale-server
docker build -t ghcr.io/ginco-org/hytale-server:latest .

Resources

• Hytale Official Site
• Hytale Server Manual
• Server Provider Authentication Guide

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This is an unofficial Docker image. Hytale and related trademarks are property of Hypixel Studios.