Install NusaGate

Install Java, start NusaGate for the first time, connect your backend servers and check that protection is running.

On this page

This guide takes you from an empty folder to a working NusaGate proxy that sends players to your backend servers. At the end you will check that protection is active with one command.

Before you start

You needDetails
Java 25 or newerJava is installed separately, for example Eclipse Temurin.
At least one backend serverA Paper server (or a Paper fork such as NusaSpigot) that players will be sent to.
Basic Velocity knowledgeNusaGate is a Velocity proxy. Backend servers and forwarding are set in velocity.toml, just like plain Velocity.
A normal user account on LinuxNusaGate refuses to start as root. Use an ordinary user such as minecraft.
Velocity plugins onlyPlugins made only for BungeeCord or Waterfall do not load.

Bedrock players also need the Velocity editions of Geyser and Floodgate, installed separately in the proxy's plugins folder.

Install and start the proxy

  1. Install Java 25 or newer, then check it in a terminal:

    java -version
  2. Create a new, empty folder for the proxy and put the NusaGate JAR you downloaded inside it.

  3. Start the proxy from that folder. Use the exact file name of your JAR and adjust the memory values to your host:

    java -Xms512M -Xmx1G -jar NusaGate-Free-2.0.0+vel4.3.1.jar
  4. Wait until the console finishes starting. NusaGate Free has no license prompt, no account and no license server connection. With NusaGate PRO, see Free and PRO editions for where your license file goes.

  5. Type shutdown in the console to stop the proxy before you edit the configuration.

On Windows you can save the start command in a start.bat file next to the JAR and double-click it:

@echo off
java -Xms512M -Xmx1G -jar NusaGate-Free-2.0.0+vel4.3.1.jar
pause

Files created on first start

File or folderWhat it is for
velocity.tomlStandard Velocity settings: listening address, backend servers and player forwarding.
nusagate.ymlAll NusaGate protection modules. An existing file is never replaced.
forwarding.secretThe shared secret Velocity uses for modern forwarding. Your backends need the same value.
plugins/ViaVersion.jarThe built-in ViaVersion, installed on first start unless you turned it off.
plugins/.nusagate-bundled/Update data and backups for the built-in ViaVersion.
logs/Console logs, plus the reports created by /ng bugreport.

Connect your backend servers

NusaGate uses normal Velocity settings for this step. Open velocity.toml and set at least these values:

bind = "0.0.0.0:25565"
online-mode = true
player-info-forwarding-mode = "modern"
forwarding-secret-file = "forwarding.secret"
 
[servers]
lobby = "127.0.0.1:25566"
survival = "127.0.0.1:25567"
try = [
  "lobby"
]
  • bind is the address and port players connect to.
  • Each line under [servers] gives a backend a short name and its address. try is the list of servers a player is sent to first.
  • player-info-forwarding-mode = "modern" passes each player's real IP address and UUID to your backends securely.

Then prepare every Paper-based backend:

  1. Set online-mode=false in the backend's server.properties. The proxy now handles login.

  2. Open config/paper-global.yml on the backend and enable Velocity support with the secret from the proxy's forwarding.secret file:

    proxies:
      velocity:
        enabled: true
        online-mode: true
        secret: "paste-the-forwarding-secret-here"
  3. Restart the backend. Make sure players cannot reach the backend port directly, only through the proxy.

The official Velocity server compatibility guide covers other server types and more options.

Set your server domain

By default NusaGate refuses players who join with a raw IP address instead of your domain. This stops many bots, which usually connect by IP. Open nusagate.yml and add your domain:

anti-bot:
  dns-check:
    block-direct-ip: true
    allowed-domains:
      - "play.example.com"

If allowed-domains is empty, any domain is accepted and only raw IP addresses are refused. Joining through localhost keeps working for local tests.

Check that it works

  1. Start your backend servers, then start NusaGate.

  2. Join the network in Minecraft using your domain (or localhost on your own computer).

  3. In the proxy console, run ng stats. You should see the protection mode, traffic and blocked-threat counters.

  4. Run ng edition to see which edition and modules are active.

  5. To use the commands in game, give yourself the nusagate.command.admin permission, for example with LuckPerms for Velocity:

    lpv user YourName permission set nusagate.command.admin true

Replace Velocity or an older NusaGate

  1. Stop the proxy and back up the whole folder.
  2. Replace the old JAR with the new NusaGate JAR and update your start command or script.
  3. Start the proxy again.

Your velocity.toml, your plugins and an existing nusagate.yml are kept. PRO-only sections in an older nusagate.yml are simply ignored by the Free JAR.

Next steps

Nusa product documentation · NusaGateFree & PRO editions

Loading the index…