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 ...)

Console Commands (Proxy)

Player Commands

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.