OpenHytale Server

Production-ready Hytale dedicated server management with Docker and CLI

Quick Start

One-Liner Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/Leetcraft/openhytale-server/main/install.sh | bash

Or Use Docker Compose

curl -fsSL https://raw.githubusercontent.com/Leetcraft/openhytale-server/main/compose.yml -o compose.yml
docker compose up -d

---

Authentication

After starting the server, you must authenticate with your Hytale account:

# Attach to the server console
docker attach hytale-server

# In the server console, run:
auth login device

Follow the on-screen instructions to complete OAuth authentication.

For persistent authentication (survives restarts):

auth persistence Encrypted

Press Ctrl+P, Ctrl+Q to detach without stopping the server.

---

CLI Usage

Initialize Environment

openhytale init                    # Check Docker installation
openhytale init --install          # Auto-install Docker (Linux)

Server Management

# Create a new server
openhytale server create --name my-server

# With custom settings
openhytale server create \
  --name my-server \
  --port 5520 \
  --max-players 50 \
  --server-name "My Hytale Server" \
  --motd "Welcome!" \
  --gamemode Adventure

# Lifecycle
openhytale server start --name my-server
openhytale server stop --name my-server
openhytale server restart --name my-server

# Monitoring
openhytale server status --name my-server
openhytale server list
openhytale server logs --name my-server
openhytale server logs --name my-server --follow

# Console access
openhytale server attach --name my-server

# Maintenance
openhytale server update --name my-server
openhytale server remove --name my-server --force

---

Docker Compose Reference

services:
  hytale:
    image: ghcr.io/leetcraft/openhytale-server:latest
    container_name: hytale-server
    environment:
      # Server binding
      SERVER_IP: "0.0.0.0"
      SERVER_PORT: "5520"

      # Server display
      HYTALE_SERVER_NAME: "My Server"
      HYTALE_MOTD: "Welcome to my server!"
      HYTALE_PASSWORD: ""

      # Game settings
      HYTALE_MAX_PLAYERS: "100"
      HYTALE_MAX_VIEW_RADIUS: "32"
      HYTALE_WORLD: "default"
      HYTALE_GAMEMODE: "Adventure"

      # System
      TZ: "UTC"
      DEBUG: "FALSE"
      PROD: "FALSE"

      # Backups (optional)
      HYTALE_BACKUP: "TRUE"
      HYTALE_BACKUP_DIR: "./backups"
      HYTALE_BACKUP_FREQUENCY: "60"
      HYTALE_BACKUP_MAX_COUNT: "10"

    restart: unless-stopped
    ports:
      - "5520:5520/udp"
    volumes:
      - ./data:/home/container
      - /etc/machine-id:/etc/machine-id:ro
    tty: true
    stdin_open: true

---

Environment Variables

Core Settings

Variable	Default	Description
SERVER_PORT	5520	UDP port for game traffic
SERVER_IP	0.0.0.0	Bind address
TZ	UTC	Timezone
DEBUG	FALSE	Enable debug logging
PROD	FALSE	Production mode checks
JAVA_ARGS	``	Additional JVM arguments

Server Settings (config.json)

Variable	Default	Description
HYTALE_SERVER_NAME	Hytale Server	Display name in server browser
HYTALE_MOTD	``	Message of the Day
HYTALE_PASSWORD	``	Server password (empty = public)
HYTALE_MAX_PLAYERS	100	Maximum concurrent players
HYTALE_MAX_VIEW_RADIUS	32	Maximum chunk view distance
HYTALE_COMPRESSION	false	Local network compression
HYTALE_WORLD	default	World folder name
HYTALE_GAMEMODE	Adventure	Default game mode

Advanced Options

Variable	Default	Description
HYTALE_AUTH_MODE	authenticated	Auth mode: authenticated, offline
HYTALE_BACKUP	FALSE	Create backup on startup
HYTALE_BACKUP_DIR	./backups	Backup directory
HYTALE_BACKUP_FREQUENCY	``	Auto-backup interval (minutes)
HYTALE_BACKUP_MAX_COUNT	``	Max backups to keep
HYTALE_OWNER_NAME	``	Server owner name
HYTALE_OWNER_UUID	``	Server owner UUID
HYTALE_MODS	``	Additional mods directory
HYTALE_TRANSPORT	QUIC	Transport protocol
HYTALE_DISABLE_SENTRY	FALSE	Disable error reporting
HYTALE_ALLOW_OP	FALSE	Auto-grant operator
HYTALE_ACCEPT_EARLY_PLUGINS	FALSE	Allow experimental plugins

---

Data Persistence

All server data is stored in the mounted volume:

./data/
├── config.json          # Server configuration
├── game/
│   ├── Server/          # Server binaries
│   └── Assets.zip       # Game assets
├── worlds/              # World data
├── backups/             # Backup archives
└── logs/                # Server logs

---

System Requirements

• Docker 20.10+ (or Docker Desktop)
• Architecture: x86_64/amd64 (ARM64 pending Hytale support)
• Memory: 4GB+ RAM recommended
• Storage: 6GB+ free space
• Network: UDP port 5520 (configurable)

---

Building from Source

CLI

git clone https://github.com/Leetcraft/openhytale-server.git
cd openhytale-server
go build -o openhytale ./cmd/openhytale

Docker Image

docker build -t openhytale-server -f docker/Dockerfile docker/

---

Troubleshooting

Authentication Issues

If authentication fails:

1. Ensure you have a valid Hytale account
2. Check your internet connection
3. Try auth login device again
4. For persistent auth: auth persistence Encrypted

Permission Errors

# Fix volume permissions
chmod -R 755 ./data

Server Won't Start

1. Check logs: docker logs hytale-server
2. Verify port 5520/udp is not in use
3. Ensure Docker has enough memory allocated

Container Crashes

# View detailed logs
docker logs --tail 100 hytale-server

# Check container status
docker inspect hytale-server

---

License

Apache License 2.0 - See LICENSE

---

Links

• Hytale Official Site
• Hytale Server Manual
• Docker Documentation
• Report Issues