Skip to content
BranchesTags

Repository files navigation

Hytale Server Docker Image

GitHub Container Registry GitHub Issues

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
  1. Start the server:
docker-compose up -d
  1. 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

Mods

Variable Default Description
MOD_URLS (empty) Space-separated direct download URLs for mod .jar/.zip files

See Installing Mods for details. The image also ships a process-based HEALTHCHECK (check docker ps / docker inspect for container health).

Advanced

Variable Default Description
ADDITIONAL_ARGS (empty) Extra arguments passed to HytaleServer.jar (e.g. --max-players 50 --view-distance 12)

Console Commands

Set ENABLE_CONSOLE_PIPE=true to open a command channel to the running server. Send commands from the host:

docker exec hytale-server /scripts/console.sh "say Server restarts in 5 minutes"

The server console reads from the named pipe /data/console.fifo (override with CONSOLE_FIFO). Note: while the pipe is enabled, docker attach no longer delivers stdin to the server; use docker logs -f for output.

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
  1. Watch the logs:
docker-compose logs -f
  1. 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
...

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

  2. 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/.mods-manifest Tracked mods managed by the image (used for removal sync)
/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

Mods are installed on every container start, combined from any of these sources:

Source Variable / Mount Description
Volume mount ./mods:/mods:ro Place .jar/.zip files in ./mods
Direct download MOD_URLS Space-separated .jar/.zip URLs

Option 1: Volume Mount

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

Place your mod .jar or .zip files in the ./mods directory. They are copied into /data/mods on startup.

Option 2: Direct Copy

Copy mods directly to ./data/mods/. Mods placed there directly are never touched by the mod manager.

Option 3: Automatic Downloads

environment:
  MOD_URLS: "https://example.com/mods/my-mod.zip https://example.com/mods/another.jar"

Mod Management

  • Mods installed by the image are tracked in /data/.mods-manifest. When a mod is removed from all of its sources, it is removed from /data/mods on the next start.
  • Mods placed directly into /data/mods (Option 2) are never removed automatically.
  • Download failures are fatal: the container stops rather than silently starting without a requested mod.

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"
    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

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.

About

A Docker image for running Hytale dedicated servers

Resources

Readme
MIT license

Contributing

Contributing
Activity
Custom properties

Stars

5 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages