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.

Hybrowse Server Stack

This image is part of the Hybrowse Server Stack — production-grade building blocks for running Hytale at scale:

• Non-interactive server authentication via Hybrowse/hytale-session-token-broker (mints short-lived session_token / identity_token at startup to skip the interactive /auth flow)
• Stateless QUIC entrypoint + referral routing via Hybrowse/hyrouter

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

Optional (advanced / providers): if you run the Hytale Session Token Broker by Hybrowse, you can fetch session/identity tokens at container startup and skip the interactive /auth flow. See: docs/image/configuration.md

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.

Documentation

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

Contributing & Security

• CONTRIBUTING.md
• LICENSING.md
• SECURITY.md

Local verification

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

task verify

Install Task:

• https://taskfile.dev/

Legal and policy notes

This is an unofficial community project and is not affiliated with or endorsed by Hypixel Studios Canada Inc.

This repository and image do not redistribute proprietary Hytale game/server files. Server operators are responsible for complying with the Hytale EULA, Terms of Service, and Server Operator Policies (including monetization and branding rules): https://hytale.com/server-policies

License

Current repository license (releases after v0.4.0): LICENSE

Non-binding summary (see LICENSE for the full, binding terms):

• Free production use is permitted for self-operated communities that are not a managed service, within the license’s free-use thresholds (currently: Peak CCU <= 250 and Peak Game Server Count <= 10).
• Managed-service/hosting usage requires a commercial agreement.

Apache-2.0 license text for releases v0.4.0 and older: LICENSE-APACHE-2.0

See also: NOTICE.

For an overview (including commercial agreements and trademarks), see:

• LICENSING.md
• COMMERCIAL_LICENSE.md
• TRADEMARKS.md