hybrowse/hytale-server repository overview

⁠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

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⁠