Getting Started

This page covers how to install and set up a minimal configuration of Velocity.

Installing Java

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.

Downloading Velocity

Head over to the downloads page to get the latest version of Velocity.

Launching Velocity for the first time

Once you have downloaded Velocity, we will launch it for the first time to generate the configuration file, velocity.toml. You can use the start script created to launch Velocity once you're done configuring Velocity.

Launching Velocity under Windows

Create a 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

Once saved, double-check the start.bat file. If it worked, you should now receive a console.

Launching Velocity under macOS or Linux

Create a 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 machine.)


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 file. Then run chmod +x and then ./ If it worked, you should now receive a proxy console.

After launch

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

In essence, we've now launched Velocity and are ready to set it up our velocity.toml. It is now time to modify the configuration and properly set up your servers.

Go ahead and type end at the console and press enter. The proxy shuts 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

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 here along with an explanation on how each option works. To get started, simply open your velocity.toml and search for the [servers] section. Here is where you will begin adding your servers to Velocity, allowing them to be seen by Velocity.

Here's a sample of what the [servers] section should look like initially.

lobby = "
factions = ""
minigames = ""

Go ahead and put your servers in this file, and then restart Velocity. Once you've done that, you will need to open the 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. Velocity should now be ready for use.

This is a minimal setup. Since we're not forwarding IPs and player information, the Minecraft server will assume you connected from offline mode and will use a different UUID and display only the default Steve and Alex skins. However, Velocity can forward this information onto your Minecraft servers with some extra configuration. See Configuring player information forwarding to learn how to configure this feature.

Copyright © 2018-2020 Velocity Contributors. This wouldn't be possible without our generous sponsors.