Keeping your Hytale server up to date

As a Hytale server administrator, keeping your installation up to date is an essential task to ensure the best gaming experience for your community. Server updates bring new features, important bug fixes, and crucial security improvements. This guide will explain how to use the Hytale Downloader CLI (Command Line Interface), the official recommended tool for dedicated servers, to simplify this process.

Essential prerequisites

Before starting the update procedure, ensure you have the following elements:

• Java 25 (or later): The Hytale Downloader CLI requires Java 25 to function correctly. Check your version with java --version.
• Command line access: A terminal (Linux/macOS) or command prompt (Windows) with basic knowledge to navigate and execute scripts.
• Permissions: Sufficient rights to download, execute files, and manipulate your server directory.

Step 1: Downloading and configuring the Hytale Downloader CLI

The first step is to obtain and configure the Hytale Downloader tool.

Initial installation

1. Download the Downloader:
   Get the latest version of the Hytale Downloader CLI tool from the official Hytale website. The file will usually be a hytale-downloader.zip.
2. Extract the archive:
   Unzip the hytale-downloader.zip file into a dedicated directory on your machine or Hytale server (for example, a hytale-tools folder).
3. Grant permissions (Linux/macOS):
   If you are on Linux or macOS, make the file executable with the following command (adapt the filename if necessary):
   chmod +x hytale-downloader-linux-amd64

Authentication (OAuth 2.0)

The first use of the Hytale Downloader CLI requires OAuth 2.0 authentication. This step secures access to updated server files by linking the tool to your Hytale account.

1. Launch authentication:
   Run the downloader for the first time in your terminal. It will display a message similar to this:
   ================== DEVICE AUTHORIZATION ==================
Visit: https://accounts.hytale.com/device Enter code: ABCD-1234 Or visit: https://accounts.hytale.com/device?user_code=ABCD-1234
==================
Waiting for authorization (expires in 900 seconds)...
2. Authorize access:
   Open the provided URL in your web browser, log in to your Hytale account, and enter the code displayed in your terminal (ABCD-1234).
3. Confirmation:
   Once authorization is successful in your browser, the terminal will confirm: Authentication successful! Mode: OAUTH_DEVICE. Your downloader is now ready for use. It will remember your credentials for future automatic updates.

Step 2: Launching your Hytale server update

With the Downloader CLI configured and authenticated, updating your server is simple and straightforward.

Download server files

1. Navigate to the downloader directory:
   Move to the folder where you extracted hytale-downloader.zip.
2. Run the download command:
   ./hytale-downloader
   
   The tool will automatically download the latest server version as a compressed archive (for example, 2026.01.13-50e69c385.zip). This archive contains the updated server files and the Assets.zip file.

Extraction and file replacement

Once the download is complete:

1. Extract the archive: Unzip the content of the downloaded archive (e.g., 2026.01.13-50e69c385.zip) directly into your Hytale server root directory.
2. Replace existing files: Ensure the extraction overwrites the old Server/ folders and the Assets.zip file. This is how the old server is updated with the new versions.

Using the cache directory

The Hytale Downloader is smart: it uses a cache directory (.cache/) to store already downloaded server JARs. This helps avoid redundant downloads and speed up the process if you have already downloaded a specific version.

Advanced Downloader CLI options

The Downloader CLI offers several useful commands for finer management of your server updates.

• Check server version without downloading:
  ./hytale-downloader -print-version
  This command will display the available update version without starting the download.
• Check for Downloader update:
  ./hytale-downloader -check-update
  Use this command to check if the Hytale Downloader tool itself needs to be updated.
• Access Pre-Release versions:
  For developers or those wishing to test pre-release versions (experimental versions with upcoming features), use the -patchline parameter:
  ./hytale-downloader -patchline pre-release
  
  Keep in mind that pre-release builds can be unstable and introduce bugs.

Best practices and automation

For fluid and professional Hytale server management, it is essential to adopt good practices, especially regarding server updates.

The crucial importance of backups

Before applying any server-side software update, especially for a major server update event, always perform a full backup of your server directory, including your worlds, configurations, and plugins. This will allow you to restore your server in case of a problem.

Automation via script

For production servers, server update automation is highly recommended. A simple script can handle graceful server shutdown, backup, update, and restart. Here is an example Bash script:

#!/bin/bash

# Path to your Hytale server directory
SERVER_DIR="/home/hytale/server"
DOWNLOADER_PATH="/home/hytale/hytale-tools/hytale-downloader" # Adapt if necessary

# --- Step 1: Gracefully stop the Hytale server ---
echo "Stopping Hytale server..."
# Replace this with your server stop command (e.g., via a systemd script or console command)
# Example: screen -S hytale_server -p 0 -X stuff "stop^M"
# Or if your server is managed by systemd:
# sudo systemctl stop hytale_server.service
sleep 10 # Allow time for the server to stop

# --- Step 2: Create a full backup ---
echo "Creating a backup of the server directory..."
BACKUP_DIR="/home/hytale/backups/server-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"
cp -r "$SERVER_DIR" "$BACKUP_DIR"
echo "Backup complete: $BACKUP_DIR"

# --- Step 3: Download and apply the update ---
echo "Launching Hytale Downloader to retrieve updated files..."
cd "$(dirname "$DOWNLOADER_PATH")" # Navigate to the downloader directory
"$DOWNLOADER_PATH" # Run the downloader

# Find the latest downloaded archive (adjust pattern if necessary)
LATEST_ARCHIVE=$(ls -t *.zip | head -n 1)
if [ -z "$LATEST_ARCHIVE" ]; then
    echo "Error: No update archive found. Aborting."
    exit 1
fi

echo "Extracting archive $LATEST_ARCHIVE into server directory..."
unzip -o "$LATEST_ARCHIVE" -d "$SERVER_DIR" # -o to overwrite files
echo "Server files update complete."

# --- Step 4: Restart the Hytale server ---
echo "Restarting Hytale server..."
cd "$SERVER_DIR"
# Replace this with your server start command
# Example: screen -dmS hytale_server java -jar HytaleServer.jar --assets Assets.zip
# Or if your server is managed by systemd:
# sudo systemctl start hytale_server.service

echo "Server update and restart complete."

Common troubleshooting

Encountering problems during an update is frustrating, but several solutions exist for the most frequent issues.

• Authentication problems: If the Downloader CLI displays authentication errors, it may be due to an expired token or incorrect permissions. Relaunch the /auth login device process in the Downloader console to get a new token. Also, ensure your Hytale account has the necessary rights.
• Permission errors (Linux/macOS): If you encounter Permission denied messages when running the Downloader or accessing files, check permissions: chmod +x hytale-downloader-linux-amd64 # Make the downloader executable sudo chown -R $USER:$USER /path/to/your/server/directory # Ensure your user owns the files
• Incompatible Java version: The message Unsupported class file major version 69 indicates your Java version is incorrect. The Hytale Downloader and server require Java 25. Install the appropriate version and ensure it is set as the default version in your system.