Hytale Server Docker

Run the Hytale dedicated server with a fully automated download, extract, config, and launch flow.

Quick Start

1. Create Directory

   mkdir -p hytale
   cd hytale

2. Create compose.yml in hytale directory.

3. Copy in compose reference:

   services:
     hytale:
       image: mbround18/hytale:v0.0.11
       container_name: hytale
       # user directive can be overridden (default is hytale:1000 in image)
       user: "1000:1000"
   
       # Interactive mode for OAuth2 authentication on first run
       stdin_open: true
       tty: true
   
       environment:
         # Optional: Modpack installation (download + extract to /data/server/Server/mods)
         # - MODPACK_URL=https://example.com/modpack.zip
         # - MODPACK_FORMAT=zip
         # - ALWAYS_DOWNLOAD_MODPACK=false
   
         # Patchline: "release" or "pre-release"
         - PATCHLINE=release
   
         # Server configuration
         - SERVER_PORT=5520
         - SERVER_BIND=0.0.0.0
         - DISABLE_SENTRY=false
         - JAVA_OPTS=-Xmx4G -Xms2G
       ports:
         # Hytale server port (UDP for QUIC protocol)
         - "5520:5520/udp"
         # Remote console TCP port (optional)
         - "7000:7000/tcp"
   
       volumes:
         # Persistent storage for credentials and downloads
         - ./data/server:/data/server
         # Optional: To see internals
         # - ./data/.staging:/data/.staging
   
       # Automatically restart unless stopped manually
       restart: unless-stopped

4. Start the server

   docker compose up

On first boot, the server will print a device URL and code. Open the URL, authenticate, and the server will continue.

What This Container Does

• Downloads the latest server build (unless an existing server is present and UPDATE_ON_START is not set)
• Extracts to /data/server
• Applies config overrides from environment variables
• Launches the server with optional CLI flags
• Persists data in the ./data directory

Configuration

All configuration lives in docker-compose.yml. For the full list of options and examples, see guides/server-hosting.md.

Option	Default	Description
DOWNLOAD_PATH	(none)	Use a local zip or extracted directory as the source
UPDATE_ON_START	false	Force a re-download even if a server already exists
SERVER_DIR	/data/server	Extraction and runtime directory
SERVER_BIND	0.0.0.0	Bind address
SERVER_PORT	5520	Server port
JAVA_OPTS	-Xmx4G -Xms2G	JVM options
BOOT_COMMAND	auth login device	Command executed on boot
AUTH_STORE_TYPE	Encrypted	Auth credential store type
REMOTE_CONSOLE_PORT	(empty)	Enable TCP console when set
MODPACK_URL	(none)	Download and extract a modpack before server starts
MODPACK_FORMAT	(none)	Override format: zip, tar, or tar.gz
ALWAYS_DOWNLOAD_MODPACK	false	Force re-download even if URL is unchanged

Data and Logs

• ./data is mounted to /data
• Logs are written to /data/logs
• The downloaded archive is /data/game.zip
• Modpack staging lives in /data/.staging

Troubleshooting

Authentication loop

• Delete the credentials file and restart: ./data/.hytale-downloader-credentials.json

Permission issues

• Ensure ./data is writable by your user

Requirements

• Docker 20.10+
• Docker Compose V2
• A valid Hytale account

License

This image wraps the official Hytale downloader and server binaries. Refer to the official Hytale licensing terms.

Roadmap

• Helm chart: github.com/mbround18/helm-charts