How to Enable F2P Players on Your Hytale Server: DualAuth Setup Guide

Step-by-step guide for Hytale server administrators to enable F2P player access using the DualAuth agent. Supports three installation modes — no server JAR modification required.

What is DualAuth?

DualAuth is a server-side agent that allows both official Hytale players and F2P (free-to-play) players to connect to the same server simultaneously. It works by intercepting JWT token validation at runtime — the original HytaleServer.jar is never modified.

Key features:

Official + F2P players on the same server
No server JAR modification (runtime bytecode transformation)
Supports Omni-Auth (decentralized self-signed tokens)
Federated JWKS key discovery
Player password protection support
Compatible with all Hytale server versions

Quick Start (5 minutes)

Option A: Agent Mode (Recommended)

This is the most reliable method. The agent loads before the server starts.

1. Download the agent:

wget https://github.com/sanasol/hytale-auth-server/releases/latest/download/dualauth-agent.jar

2. Start your server with the agent flag:

java -javaagent:dualauth-agent.jar -jar HytaleServer.jar

That's it. Your server now accepts F2P players.

Option B: Early Plugin Mode

Drop the JAR into the earlyplugins/ folder. No JVM flags needed. Works with singleplayer too.

1. Download the agent:

wget https://github.com/sanasol/hytale-auth-server/releases/latest/download/dualauth-agent.jar

2. Create the folder and place the JAR:

mkdir -p earlyplugins
mv dualauth-agent.jar earlyplugins/

3. Start your server normally:

java -jar HytaleServer.jar

Option C: Plugin/Mod Mode

For hosting providers that block JVM startup flags. Drop the JAR into mods/ folder.

1. Download and place in mods:

mkdir -p mods
wget -O mods/dualauth-agent.jar https://github.com/sanasol/hytale-auth-server/releases/latest/download/dualauth-agent.jar

2. Start with dynamic agent loading enabled:

java -XX:+EnableDynamicAgentLoading -jar HytaleServer.jar

Note: Some hosting providers may not support -XX:+EnableDynamicAgentLoading. Use Agent Mode or Early Plugin Mode instead.

Verify It Works

Check your server logs after starting. You should see the DualAuth banner:

[DualAuth] ========================================
[DualAuth] DualAuth Agent v1.1.x loaded
[DualAuth] Mode: STATIC (-javaagent flag)
[DualAuth] Auth Domain: auth.sanasol.ws
[DualAuth] Trust All Issuers: true
[DualAuth] ========================================

If you see this, DualAuth is active and F2P players can connect.

Configuration

DualAuth works out of the box with zero configuration. For advanced setups, use environment variables:

Essential:

HYTALE_AUTH_DOMAIN — F2P auth domain (default: auth.sanasol.ws)
HYTALE_TRUST_ALL_ISSUERS — Accept tokens from any valid auth server (default: true)
HYTALE_TRUST_OFFICIAL — Also accept official Hytale accounts (default: true)

Advanced:

HYTALE_TRUSTED_ISSUERS — Comma-separated list of specific trusted auth servers
HYTALE_ISSUER_BLACKLIST — Block specific auth servers
HYTALE_KEYS_CACHE_TTL — How long to cache auth keys in seconds (default: 3600)
DUALAUTH_LOGGING_ENABLED — Enable debug logging (default: false)

Example with custom config:

HYTALE_AUTH_DOMAIN=auth.sanasol.ws \
DUALAUTH_LOGGING_ENABLED=true \
java -javaagent:dualauth-agent.jar -jar HytaleServer.jar

Docker Setup

If you run your server with Docker, use the official F2P Docker image which includes DualAuth pre-configured:

docker run -d \
  -p 5520:5520/udp \
  -e HYTALE_SERVER_NAME="My Server" \
  ghcr.io/sanasol/hytale-server-docker:latest

See the Docker server guide for full details.

Pterodactyl / Panel Hosting

If you use Pterodactyl panel:

Import the F2P server egg
Create a new server using the egg
DualAuth is pre-configured — no additional setup needed

Free Hosted Server

Don't want to manage your own server? Get a free hosted Hytale server with DualAuth pre-installed:

hytale.sanhost.net — 3 GB RAM, instant provisioning, full control panel

Get Listed

Once your server has DualAuth enabled, it will automatically be detected as F2P-compatible by santale.top. Your server will show an F2P badge in the server browser, making it discoverable by F2P Evo launcher users.

How F2P Players Connect

F2P players use the F2P Evo launcher to connect. They don't need an official Hytale account. The launcher generates authentication tokens that DualAuth validates server-side.

Both official and F2P players can play together on the same server with no difference in gameplay.

Troubleshooting

DualAuth not loading:

Check server logs for the DualAuth banner
Verify the JAR file exists in the correct location
For Agent mode: ensure -javaagent:dualauth-agent.jar is BEFORE -jar
For Plugin mode: ensure -XX:+EnableDynamicAgentLoading flag is set

F2P players can't connect:

Enable debug logging: DUALAUTH_LOGGING_ENABLED=true
Check that HYTALE_TRUST_ALL_ISSUERS=true (default)
Verify outbound HTTPS is not blocked (agent fetches auth keys)

Server crashes on start:

Download the latest agent version from GitHub releases
Ensure you're using Java 21+ (same as HytaleServer.jar requires)