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 need | Details |
|---|---|
| Java 25 or newer | Java is installed separately, for example Eclipse Temurin. |
| At least one backend server | A Paper server (or a Paper fork such as NusaSpigot) that players will be sent to. |
| Basic Velocity knowledge | NusaGate is a Velocity proxy. Backend servers and forwarding are set in velocity.toml, just like plain Velocity. |
| A normal user account on Linux | NusaGate refuses to start as root. Use an ordinary user such as minecraft. |
| Velocity plugins only | Plugins 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
-
Install Java 25 or newer, then check it in a terminal:
java -version -
Create a new, empty folder for the proxy and put the NusaGate JAR you downloaded inside it.
-
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 -
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.
-
Type
shutdownin 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
pauseFiles created on first start
| File or folder | What it is for |
|---|---|
velocity.toml | Standard Velocity settings: listening address, backend servers and player forwarding. |
nusagate.yml | All NusaGate protection modules. An existing file is never replaced. |
forwarding.secret | The shared secret Velocity uses for modern forwarding. Your backends need the same value. |
plugins/ViaVersion.jar | The 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"
]bindis the address and port players connect to.- Each line under
[servers]gives a backend a short name and its address.tryis 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:
-
Set
online-mode=falsein the backend'sserver.properties. The proxy now handles login. -
Open
config/paper-global.ymlon the backend and enable Velocity support with the secret from the proxy'sforwarding.secretfile:proxies: velocity: enabled: true online-mode: true secret: "paste-the-forwarding-secret-here" -
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
-
Start your backend servers, then start NusaGate.
-
Join the network in Minecraft using your domain (or
localhoston your own computer). -
In the proxy console, run
ng stats. You should see the protection mode, traffic and blocked-threat counters. -
Run
ng editionto see which edition and modules are active. -
To use the commands in game, give yourself the
nusagate.command.adminpermission, for example with LuckPerms for Velocity:lpv user YourName permission set nusagate.command.admin true
Replace Velocity or an older NusaGate
- Stop the proxy and back up the whole folder.
- Replace the old JAR with the new NusaGate JAR and update your start command or script.
- 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
- Commands and permissions: everything you can do with
/ng. - Anti-bot and anti-exploit: recommended settings before you open to the public.
- Free and PRO editions: what PRO adds and how to upgrade.