This page covers how to install and set up a minimal configuration of Velocity.
Velocity is written in Java, so if you do not already have Java installed, you will need to install it before you continue. Velocity requires Java 8 or newer.
We recommend using the HotSpot-based Java 11 builds from AdoptOpenJDK.
Head over to the downloads page to get the latest version of Velocity. We recommend getting the latest stable version. After downloading Velocity, move the JAR file to a dedicated folder for just the proxy or upload it to your server.
Launching Velocity for the first time
Once you have downloaded Velocity, we will launch it for the first time to generate the
velocity.toml. You can use the start script created to launch Velocity
once you're done configuring Velocity.
Launching Velocity under Windows
start.bat with the following contents in the same directory where you intend
to place the proxy files.
@echo off java -Xms512M -Xmx512M -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -jar velocity.jar pause
velocity.jarto the name of the Velocity JAR that you downloaded, or rename the Velocity JAR to
Once saved, double-click the
start.bat file. If it worked, you should now receive a console similar to the output in the next section.
Launching Velocity under macOS or Linux
start.sh with the following contents in the same directory where you intend
to place the proxy files. You may do this using a file transfer client, or using a text
editor running on the host.
#!/bin/sh java -Xms1G -Xmx1G -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -XX:MaxInlineLevel=15 -jar velocity*.jar
Once saved, open a terminal (or log into the machine) if you haven't already, navigate to the directory where you have placed the Velocity JAR file and the
start.sh file. Then run
chmod +x start.sh and then
./start.sh. If it worked, you should now receive a console similar to the output in the next section.
Here's a sample of what you'll see once we've started the proxy:
[12:04:59 INFO]: Booting up Velocity <unknown>... [12:04:59 INFO]: Connections will use epoll channels, libdeflate (Linux x86_64) compression, OpenSSL 1.1.x (Linux x86_64) ciphers [12:04:59 INFO]: Loading plugins... [12:04:59 INFO]: Loaded 0 plugins [12:04:59 INFO]: Listening on /0:0:0:0:0:0:0:0%0:25577 [12:04:59 INFO]: Done (0.48s)!
Velocity has launched, and you are now ready to configure the proxy completely. Go ahead and type
end at the console and press enter. The proxy will shut down:
> end [12:05:02 INFO]: Shutting down the proxy... [12:05:02 INFO]: Closing endpoint /0:0:0:0:0:0:0:0%0:25577
If you used the Windows batch script from earlier, the window will ask you to press a key. You can either press a key or close the command window.
Configuring your servers
We now need to configure each server to accept connections from the proxy.
Velocity is a highly configurable proxy. While most users will not need to change everything in the config, there are tons of options covered on the configuration wiki page along with an explanation on how each option works. However, in this section we will do the bare minimum to get the proxy up and running.
velocity.toml file in a text editor and search for the
[servers] section. This section specifies the servers that Velocity can connect to. Here's what the
[servers] section will look like initially:
[servers] # Configure your servers here. Each key represents the server's name, and the value # represents the IP address of the server to connect to. lobby = "127.0.0.1:30066" factions = "127.0.0.1:30067" minigames = "127.0.0.1:30068" # In what order we should try servers when a player logs in or is kicked from a server. try = [ "lobby" ]
On the left side, you will specify a name for the server (for example,
lobby) and on right is a string indicating the IP address and port for the server. You will now need to add your servers to the list. You can change the list of servers as needed.
try setting is special. It is a list of servers Velocity should try to connect the player to when the player first logs onto the proxy or gets kicked from a server. If you decided to change the name of the
lobby server, then you should replace
lobby in this list with the name you chose for the first server the player should log into first.
server.properties file for each of your servers and set the
online-mode setting to
false. This allows Velocity to connect to your server. Once you're done, restart your server. While Velocity is now ready for use, you will almost certainly want to secure your servers and configure player information forwarding.