Hytale Server Docker Image

🐳 Production-ready Docker image for dedicated Hytale servers.

Automatic CurseForge mod management, auto-download with smart update detection, Helm chart, CLI, easy configuration, and quick troubleshooting.

Brought to you by Hybrowse and the developer of setupmc.com.

Image

• Image (Docker Hub): hybrowse/hytale-server
• Mirror (GHCR): ghcr.io/hybrowse/hytale-server

Community

Join the Hybrowse Discord Server to get help and stay up to date: https://hybrowse.gg/discord

Quickstart

services:
  hytale:
    image: hybrowse/hytale-server:latest
    environment:
      HYTALE_AUTO_DOWNLOAD: "true"
    ports:
      - "5520:5520/udp"
    volumes:
      - ./data:/data
    tty: true
    stdin_open: true
    restart: unless-stopped

docker compose up -d

Important

Two authentication steps required:

1. Downloader auth (first run): follow the URL + device code in the logs to download server files
2. Server auth (after startup): attach to the console (docker compose attach hytale), then run /auth persistence Encrypted followed by /auth login device

Full guide: docs/image/quickstart.md

Troubleshooting: docs/image/troubleshooting.md

Automation: you can send server console commands from scripts via hytale-cli:

docker exec hytale hytale-cli send "/say Server is running!"

See: docs/image/configuration.md

Documentation

• docs/image/quickstart.md — start here
• docs/image/configuration.md — environment variables, JVM tuning
• docs/image/kubernetes.md — Helm chart, Kustomize overlays, and Kubernetes deployment notes
• docs/image/curseforge-mods.md — automatic CurseForge mod download and updates
• docs/image/troubleshooting.md — common issues
• docs/image/backups.md — backup configuration
• docs/image/server-files.md — manual provisioning (arm64, etc.)
• docs/image/upgrades.md — upgrade guidance
• docs/image/security.md — security hardening

Why this image

• Security-first defaults (least privilege; credentials/tokens treated as secrets)
• Operator UX (clear startup validation and actionable errors)
• Performance-aware (sane JVM defaults; optional AOT cache usage)
• Predictable operations (documented data layout and upgrade guidance)

Java

Hytale requires Java 25. This image uses Adoptium / Eclipse Temurin 25.

Planned features

See ROADMAP.md for details. Highlights:

• Planned next: graceful shutdown guidance, basic healthcheck (with a way to disable), diagnostics helpers, observability guidance, provider-grade patterns

Documentation

• docs/image/: Image usage & configuration
• docs/hytale/: internal notes (not end-user image docs)

Contributing & Security

• CONTRIBUTING.md
• SECURITY.md

Local verification

You can build and run basic container-level validation tests locally:

task verify

Install Task:

• https://taskfile.dev/

License

See LICENSE and NOTICE.