Hytale Docker Server

Production-ready Docker container for Hytale dedicated servers

Automated authentication • Auto-updates • CurseForge mods • Secure by default

---

✨ Features

Feature	Description
🚀 One-command startup	Just docker compose up, authenticate once, play forever
🔐 OAuth2 Authentication	Device code flow with 30-day persistent tokens
🔄 Auto-updates	Optional automatic server updates on restart
🧩 CurseForge Mods	Auto-sync mods with CF_MODS environment variable
💻 Unified CLI	Single hytale command for auth, updates, mods, and server commands
🔒 Secure by default	Non-root user, dropped capabilities, hardened container
⚡ Fast boot	AOT cache support for quicker server startup
💾 Persistent data	Worlds, tokens, and mods survive restarts

---

🆕 Meet the New Configurator

Generate a complete docker-compose.yml in minutes with the interactive configurator.
Available at https://hytale.romarin.dev

---

🚀 Quick Start

Create a docker-compose.yml:

services:
  hytale:
    image: rxmarin/hytale-docker:latest
    container_name: hytale-server
    restart: unless-stopped
    stdin_open: true
    tty: true
    ports:
      - "5520:5520/udp"
    environment:
      JAVA_OPTS: "-Xms4G -Xmx8G"
      AUTO_UPDATE: "true"
    volumes:
      - hytale-data:/server

volumes:
  hytale-data:

Start the server:

docker compose up -d
docker compose logs -f  # Watch for auth prompt

On first run, you'll see a device authorization prompt. Visit the URL, enter the code, and authorize. The server starts automatically.

Connect to your-ip:5520 using the Hytale client.

Note: Hytale uses QUIC over UDP (not TCP). Forward UDP port 5520 on your firewall.

---

💻 CLI Usage

# Auth
docker exec -it hytale-server hytale auth status
docker exec -it hytale-server hytale auth login

# Server commands
docker exec -it hytale-server hytale cmd /help
docker exec -it hytale-server hytale cmd /list

# Updates
docker exec -it hytale-server hytale update check
docker exec -it hytale-server hytale update schedule

# CurseForge mods
docker exec -it hytale-server hytale mods list

---

🧩 CurseForge Mods

Auto-sync mods from CurseForge:

environment:
  CF_API_KEY: "${CF_API_KEY}"  # From .env file  #NOTE: $ needs to be escaped via $$ syntax or you might get 403 errors in the logs.
  CF_MODS: "123456,789012"

See CurseForge documentation for setup.

---

📖 Documentation

📚 hytale.romarin.dev — Full documentation

• Quick Start
• Configuration
• CLI Reference
• CurseForge Mods
• Authentication
• Troubleshooting

---

⚙️ Environment Variables

Variable	Default	Description
JAVA_OPTS	-Xms4G -Xmx8G	JVM memory options
AUTO_UPDATE	false	Auto-update server on restart
PATCHLINE	release	Release channel
USE_AOT_CACHE	true	Faster startup
CF_API_KEY	—	CurseForge API key
CF_MODS	—	Comma-separated mod IDs

See Configuration for all options.

---

🏗️ Development

# Build the image locally
docker build -t hytale-server:latest .

# Run locally with Bun
bun run src/main.ts

# Run documentation site
cd docs && pnpm install && pnpm dev

---

📚 References

• Hytale Server Manual
• Server Provider Authentication Guide

---

Made with ❤️ by romarin.dev

Documentation • Discord Support • Report Bug • Request Feature