Configuration

All configuration is done through environment variables in your docker-compose.yml.

Environment Variables

Core Settings

Variable	Default	Description
`SERVER_PORT`	`5520`	Server port (UDP)
`JAVA_OPTS`	`-Xms4G -Xmx8G`	JVM memory and GC options
`TZ`	`UTC`	Container timezone
`EXTRA_ARGS`	(empty)	Additional server arguments

Server Configuration

These override fields in /server/Server/config.json on startup.

Variable	Default	Description
`SERVER_NAME`	(empty)	Server name (`ServerName`)
`MOTD`	(empty)	Message of the day (`MOTD`)
`PASSWORD`	(empty)	Server password (`Password`)
`MAX_PLAYERS`	(empty)	Max players (`MaxPlayers`)
`MAX_VIEW_RADIUS`	(empty)	Max view radius (`MaxViewRadius`)
`DEFAULT_WORLD`	(empty)	Default world (`Defaults.World`)
`DEFAULT_GAME_MODE`	(empty)	Default game mode (`Defaults.GameMode`)

Updates

Variable	Default	Description
`AUTO_UPDATE`	`false`	Automatically update server on restart
`PATCHLINE`	`release`	Release channel (`release`, `pre-release`)
`FORCE_UPDATE`	`false`	Force re-download even if files exist

With AUTO_UPDATE=false, use hytale update schedule to manually trigger updates.

Authentication

Variable	Default	Description
`AUTO_REFRESH_TOKENS`	`true`	Refresh tokens before expiry
`AUTOSELECT_GAME_PROFILE`	`true`	Auto-select first profile
`HYTALE_SERVER_SESSION_TOKEN`	(empty)	Pre-provided session token
`HYTALE_SERVER_IDENTITY_TOKEN`	(empty)	Pre-provided identity token

Performance

Variable	Default	Description
`USE_AOT_CACHE`	`true`	Use AOT cache for faster startup
`DISABLE_SENTRY`	`false`	Disable error reporting

CurseForge Mods

Variable	Default	Description
`CF_API_KEY`	(empty)	CurseForge API key
`CF_MODS`	(empty)	Comma-separated mod project IDs

See CurseForge Mods for details.

Modtale Mods

Variable	Default	Description
`MT_API_KEY`	(empty)	Modtale API key
`MT_MODS`	(empty)	Comma-separated mod UUIDs

See Modtale Mods for details.

Complete Example

services:
  hytale:
    image: rxmarin/hytale-docker:latest
    container_name: hytale-server
    restart: unless-stopped
    stdin_open: true
    tty: true
    ports:
      - "5520:5520/udp"
    
    environment:
      # Memory
      JAVA_OPTS: "-Xms4G -Xmx8G -XX:+UseG1GC"
      
      # Updates
      AUTO_UPDATE: "true"
      PATCHLINE: "release"
      
      # Performance
      USE_AOT_CACHE: "true"
      
      # CurseForge (optional)
      CF_API_KEY: "${CF_API_KEY}"
      CF_MODS: "123456,789012"
      
      # Timezone
      TZ: "America/New_York"
    
    volumes:
      - hytale-data:/server
    
    deploy:
      resources:
        limits:
          memory: 10G
        reservations:
          memory: 4G
    
    healthcheck:
      test: ["CMD", "pgrep", "-f", "HytaleServer.jar"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 120s

volumes:
  hytale-data:

Memory Configuration

Adjust Java heap size based on player count:

Players	RAM	JAVA_OPTS
1-5	2-4 GB	`-Xms2G -Xmx4G`
5-10	4-6 GB	`-Xms4G -Xmx6G`
10-20	6-8 GB	`-Xms6G -Xmx8G`
20+	8+ GB	`-Xms8G -Xmx10G`

Set -Xms equal to -Xmx to prevent heap resizing during runtime.

Volume

The container uses one volume at /server:

volumes:
  - hytale-data:/server

Contents:

Server/ — Server JAR and runtime files
Assets.zip — Game assets
.hytale/tokens/ — OAuth and session tokens
mods/ — CurseForge mods (if configured)
World saves and configuration

Port Configuration

Hytale uses QUIC over UDP:

ports:
  - "5520:5520/udp"  # /udp is required!

To use a different external port:

ports:
  - "25565:5520/udp"  # External:Internal

Always keep the internal port as 5520. Only change the external (host) port.

AOT Cache

Ahead-of-Time compilation cache improves startup time:

environment:
  USE_AOT_CACHE: "true"

First startup: Normal speed (cache is generated)
Subsequent startups: Significantly faster

The cache file is stored at /server/Server/HytaleServer.aot.

Resource Limits

Set container resource limits:

deploy:
  resources:
    limits:
      memory: 10G
      cpus: '4.0'
    reservations:
      memory: 4G
      cpus: '2.0'

Health Check

The default health check monitors the Java process:

healthcheck:
  test: ["CMD", "pgrep", "-f", "HytaleServer.jar"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 120s

Next Steps

CLI Reference — Command-line interface
CurseForge Mods — Auto-sync mods
Authentication — Token details

Configuration

On this page