Numdrassl: the complete Hytale proxy guide

For Hytale server administrators looking to create interconnected networks (multi-server setups to distribute load), Numdrassl – Hytale Proxy Server is the go-to solution.

This high-performance proxy allows you to link multiple Hytale servers (lobby, survival, mini-games) behind a single address, offering a seamless experience inspired by BungeeCord or Velocity.

This guide details installation, network configuration, and mastering the permission system.

What is Numdrassl?

Numdrassl is a Java proxy server that sits between the player and your backend servers. It handles authentication and packet routing via Hytale’s native QUIC protocol.

Key Features:

• Multi-Server Network: Navigate between servers without disconnecting.
• Player Transfer: Native /server commands.
• Security: Centralized authentication and support for signed referrals.
• Permission System: Granular management by groups and users.

Prerequisites

• Java 25 or higher.
• One or more Hytale servers.
• The proxy-*.jar and bridge-*.jar files (available on CurseForge).

Proxy Installation

1. Startup

1. Place the proxy-*.jar file in a dedicated folder.
2. Launch the proxy:
   jar proxy-1.0-SNAPSHOT.jar
3. Authentication: Upon the first launch, type auth login in the console and follow the instructions to link your Hytale account.

2. Configuration (config/proxy.yml)

Edit the generated file to define your network:

# Network
bindAddress: "0.0.0.0"
bindPort: 45585
publicAddress: "play.my-server.com"
publicPort: 45585

# SECURITY (Must be identical on the Bridge)
proxySecret: "your-very-secure-secret"

# Backend Servers
backends:
  - name: "lobby"
    host: "127.0.0.1"
    port: 5520
    defaultServer: true
  - name: "survival"
    host: "127.0.0.1"
    port: 5521
    defaultServer: false

Backend Server Configuration

Your game servers must no longer authenticate players themselves.

1. Bridge Installation

Copy bridge-*.jar into the plugins/ folder of every Hytale backend server.

2. Launch Arguments

Start your servers with the following arguments (mandatory for the proxy to work):

java -jar HytaleServer.jar --auth-mode insecure --transport QUIC

3. Bridge Configuration (plugins/Bridge/config.json)

{ 
  "proxySecret": "your-very-secure-secret", 
  "serverName": "lobby" 
} 

Important Notes:

• serverName is used to identify this server in logs and the network.
• proxySecret must match the one in the proxy configuration exactly.

4. Firewall Security

You must block direct connections to the UDP ports of your backend servers to force traffic through the proxy.

Permission System

Folder Structure

data/permissions/
├── players/
│   └── {uuid}.yml       # Permissions specific to a player
├── groups/
│   ├── default.yml      # Default group (all players)
│   └── admin.yml        # Custom groups
└── player-groups.yml    # Assigning players to groups

Configuration Examples

Group (groups/admin.yml):

name: admin 
default: false 
permissions:
  - numdrassl.command.* # Wildcard
  - numdrassl.admin

Player (players/{uuid}.yml):

permissions:
  - numdrassl.command.server
  - numdrassl.command.help
  - -numdrassl.command.stop # Denied (prefix with -)

Commands and Administration

Permission Commands (/numdrassl perm ...)

Command	Description
/numdrassl perm user <player> info	Displays a player’s groups and permissions.
/numdrassl perm user <player> add <perm>	Adds a permission to a player.
/numdrassl perm user <player> remove <perm>	Removes a permission from a player.
/numdrassl perm user <player> addgroup <group>	Adds a player to a group.
/numdrassl perm user <player> removegroup <group>	Removes a player from a group.
/numdrassl perm group <group> add <perm>	Adds a permission to a group.
/numdrassl perm group <group> remove <perm>	Removes a permission from a group.
/numdrassl perm reload	Reloads the permission configuration from disk.

Console Commands (Proxy)

Command	Description
auth login	Initiates authentication with Hytale.
auth status	Displays the authentication status.
auth logout	Clears stored credentials.
sessions	Lists players currently connected to the proxy.
stop	Gracefully stops the proxy.
help	Displays available commands.

Player Commands

Command	Description
/server (or /srv)	Lists available servers.
/server <name>	Transfers the player to the target server.
/numdrassl version	Displays the proxy version.

Common Errors

• Error “Proxy not authenticated”: Type auth login in the console.
• Error “Invalid player info message”: Your proxySecret does not match between the proxy and the bridge.
• Unable to connect: Check that the backend server is launched with the --transport QUIC argument.